From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect Date: Mon, 7 Jan 2013 14:29:07 -0800 Message-ID: References: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1357597815 21635 80.91.229.3 (7 Jan 2013 22:30:15 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 7 Jan 2013 22:30:15 +0000 (UTC) To: "'Aaron S. Hawley'" , <13373@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jan 07 23:30:31 2013 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1TsLD9-0006y1-6O for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Jan 2013 23:30:27 +0100 Original-Received: from localhost ([::1]:39225 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TsLCt-00044b-MR for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Jan 2013 17:30:11 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:48734) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TsLCq-00043P-D3 for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 17:30:10 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TsLCl-0003Hr-An for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 17:30:08 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42441) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TsLCl-0003HO-7D for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 17:30:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TsLCk-00032E-Tw for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 17:30:03 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 07 Jan 2013 22:30:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 13373 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 13373-submit@debbugs.gnu.org id=B13373.135759776211594 (code B ref 13373); Mon, 07 Jan 2013 22:30:02 +0000 Original-Received: (at 13373) by debbugs.gnu.org; 7 Jan 2013 22:29:22 +0000 Original-Received: from localhost ([127.0.0.1]:55682 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsLC5-00030w-Jl for submit@debbugs.gnu.org; Mon, 07 Jan 2013 17:29:21 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:41442) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsLC2-00030h-9y for 13373@debbugs.gnu.org; Mon, 07 Jan 2013 17:29:19 -0500 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id r07MTADi024889 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 7 Jan 2013 22:29:10 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r07MT919023108 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 7 Jan 2013 22:29:10 GMT Original-Received: from abhmt112.oracle.com (abhmt112.oracle.com [141.146.116.64]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r07MT9tH028773; Mon, 7 Jan 2013 16:29:09 -0600 Original-Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 07 Jan 2013 14:29:09 -0800 X-Mailer: Microsoft Office Outlook 11 In-reply-to: Thread-Index: Ac3tHeLjOd1obKFsQ9myWlOf0CctlQAAxPDg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:69471 Archived-At: > 1. Yes, the first line should say "command" and not "function". > Although since the word "command" is in execute-extended-command it > seems the intent was to avoid sounding repetitive. There is no way to know what the intent was, but what you describe is a bad intent, in any case. Function names do not substitute for doc. A non-command function is not accepted as argument. It cannot be read interactively, and if you pass it as argument in Lisp then an error is raised. It does not help users to call this parameter FUNCTION. > 2. True, the definition for execute-extended-command doesn't contain > code for reading arguments. That's because the work is off-loaded to > command-execute and in turn call-interactively. So for all intents > and purposes that's what execute-extended-command does. Agreed; my bad. 2.1. The doc might also mention something else that `e-e-c' does, besides invoking a command: it displays keys that the command is bound to, when `suggest-key-bindings' is non-nil. > 3. The usage in the Emacs manual is "numeric argument", so for better > or worse, it seems consistent. Where do you see "numeric argument" used in the Elisp manual for the doc of `e-e-c'? That doc is in node `Interactive Call'. It says no such thing, and explicitly refers to the raw prefix argument: "If `execute-extended-command' is called interactively, the current raw prefix argument is used for PREFIX-ARGUMENT, and thus passed on to whatever command is run. If the Elisp manual did as you say it does, then it too would wrong. Two wrongs are not to be rewarded just because they are "consistent" with each other. In Lisp code you can of course pass anything you like as argument PREFIXARG. But, as the doc string says (correctly), what you pass should be acceptable to the invoked command as a prefix argument value. (A raw prefix argument value, that is.) > 4. Is a white space nit pick. Emacs convention, AFAIK. But yes, not very important. > 5. Yeah, best to delete "with" from "you are invoking with". This is > actually worth fixing. > > 6. Yeah, "accepts an argument" is probably more correct language than > "asks for an argument". This is actually worth fixing as well. #6 is also a bug in the Elisp manual. It too says "If the command asks for a prefix argument, it receives the value PREFIX-ARGUMENT." Same fix: "asks for" -> "accepts". The main thing "worth fixing" is the misleading statements about the prefix arg.