From debbugs-submit-bounces@debbugs.gnu.org Sun Jan 06 20:02:37 2013 Received: (at submit) by debbugs.gnu.org; 7 Jan 2013 01:02:37 +0000 Received: from localhost ([127.0.0.1]:33351 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Ts16r-0007Xc-BL for submit@debbugs.gnu.org; Sun, 06 Jan 2013 20:02:37 -0500 Received: from eggs.gnu.org ([208.118.235.92]:53883) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1Ts16o-0007XN-Qe for submit@debbugs.gnu.org; Sun, 06 Jan 2013 20:02:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Ts16h-0006PG-Gv for submit@debbugs.gnu.org; Sun, 06 Jan 2013 20:02:28 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-104.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY, USER_IN_WHITELIST autolearn=unavailable version=3.3.2 Received: from lists.gnu.org ([208.118.235.17]:47482) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ts16h-0006PC-EM for submit@debbugs.gnu.org; Sun, 06 Jan 2013 20:02:27 -0500 Received: from eggs.gnu.org ([208.118.235.92]:37005) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ts16g-0006P8-6X for bug-gnu-emacs@gnu.org; Sun, 06 Jan 2013 20:02:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Ts16f-0006Oi-0m for bug-gnu-emacs@gnu.org; Sun, 06 Jan 2013 20:02:26 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:21228) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Ts16e-0006Oa-Pk for bug-gnu-emacs@gnu.org; Sun, 06 Jan 2013 20:02:24 -0500 Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id r0712NO9011481 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 7 Jan 2013 01:02:24 GMT Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r0712Mei027700 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 7 Jan 2013 01:02:23 GMT 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 r0712M6Z008573 for ; Sun, 6 Jan 2013 19:02:22 -0600 Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 06 Jan 2013 17:02:22 -0800 From: "Drew Adams" To: Subject: 24.3.50; doc string of `execute-extended-command' is incorrect Date: Sun, 6 Jan 2013 17:02:10 -0800 Message-ID: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 Thread-Index: Ac3scp9eeT6Yv6wmSJC7xLxLwpzo4Q== X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 208.118.235.17 X-Spam-Score: -3.4 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.2 (----) The doc string is incorrect and misleading in several ways. Read function name, then read its arguments and call it. To pass a numeric argument to the command you are invoking with, specify the numeric argument to this command. Noninteractively, the argument PREFIXARG is the prefix argument to give to the command you invoke, if it asks for an argument. 1. It is not just a function name that is read. It is (it must be) a COMMAND name, i.e., an interactive function. 2. `execute-extended-command' does NOT read the arguments of the "function name" it reads. First, a function NAME does not have any arguments. Second, it is the command so named that reads its own arguments, if any are read. `e-e-c' does nothing of the kind. 3. (What prompted me to write this bug report.) It is not about passing a "numeric argument" to the command invoked by `e-e-c'. It is about passing it THE prefix argument, in fact the RAW prefix argument. There is a LOT of confusion in this doc string. Almost everything it says is wrong or misleading. [Also: 4. There is no reason to skip a line after the first doc line. That is not the Emacs convention. 5. The second sentence is grammatically incorrect. "...to the command you are invoking with" - invoking WITH? invoking with what? 6. The third sentence is confusing. "if it asks for an argument". No command ever asks the user for a prefix argument. Presumably what is meant is "if it accepts a prefix argument." Anyway, the second and third sentences are verbose and somewhat repetitive.] In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600) of 2012-12-31 on ODIEONE Bzr revision: 111388 rudalics@gmx.at-20121231113513-subz2dazg6yjukzh Windowing system distributor `Microsoft Corp.', version 5.1.2600 Configured using: `configure --with-gcc (4.7) --no-opt --enable-checking --cflags -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib' From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 07 16:27:53 2013 Received: (at 13373) by debbugs.gnu.org; 7 Jan 2013 21:27:53 +0000 Received: from localhost ([127.0.0.1]:55638 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsKEa-0001XG-Aa for submit@debbugs.gnu.org; Mon, 07 Jan 2013 16:27:53 -0500 Received: from mail-qc0-f182.google.com ([209.85.216.182]:55342) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsKEY-0001X1-K1 for 13373@debbugs.gnu.org; Mon, 07 Jan 2013 16:27:51 -0500 Received: by mail-qc0-f182.google.com with SMTP id k19so13294348qcs.13 for <13373@debbugs.gnu.org>; Mon, 07 Jan 2013 13:27:44 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:date:message-id:subject:from:to:content-type; bh=hzuPbyCbbvbYPqAXEehonUwmsmn0EcI9bdvG6Yepraw=; b=AapckqLTM2la3I3F114qtnWcvQnCBNK0Z6pskJYuQEbhOcJ9PgB5n/jE4HbzLtjo4l vge9Is+ovOrC2X9ZAmXyEy6csnOmt8E3vr50OPiI7bnkjydzA5/QPk+Vrh+3K4f1jPMT VMNNnfYQga1FwmUcMNsg4o12jQDhShn+3L6q573k1lO4YH4bAQQDwmNaPFMs+jm9Umlx rhqlnEseszACFP0Um9yU2erzRTfmp9I5PexgoZcVMF0DAgXG5g/LC54o90J6Ia17I5WH IfsoKMks3VRb/bRkddMUHXob2bXizvgh64jFLzwAIMeDDKYi759O8dpgeegSOdexAR5g xYCQ== MIME-Version: 1.0 Received: by 10.49.74.73 with SMTP id r9mr50677444qev.44.1357594064856; Mon, 07 Jan 2013 13:27:44 -0800 (PST) Received: by 10.49.48.42 with HTTP; Mon, 7 Jan 2013 13:27:44 -0800 (PST) Date: Mon, 7 Jan 2013 16:27:44 -0500 Message-ID: Subject: Re: 24.3.50; doc string of `execute-extended-command' is incorrect From: "Aaron S. Hawley" To: 13373@debbugs.gnu.org Content-Type: text/plain; charset=ISO-8859-1 X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 13373 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: 0.1 (/) When I translated the C code to Lisp I tried to carry everything over, including any "warts". Clearly this was the case for the documentation as well. I enjoy how succinct the doc is though. Until Emacs 21, the docstring was just "Read function name, then read its arguments and call it." 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. 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. Sometimes it's the case that "the command so named reads its own arguments", but that's only true when the command has an interactive Lisp form -- which gets eval'd by call-interactively. Otherwise, interactive specs of the string-variety are really handled by call-interactively. I'd file this as a distinction without a difference or at least as implementation details that are hopefully already covered appropriately in the Elisp manual. 3. The usage in the Emacs manual is "numeric argument", so for better or worse, it seems consistent. 4. Is a white space nit pick. As Yoda might have said, "A horse in the race I have not." 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. Looking forward to the release of the Lisp version of M-x! /a -- In general, we reserve the right to have a poor memory--the computer, however, is supposed to remember! Poor computer. -- Guy Lewis Steele Jr. From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 07 17:29:22 2013 Received: (at 13373) by debbugs.gnu.org; 7 Jan 2013 22:29:22 +0000 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 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 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 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 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 Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 07 Jan 2013 14:29:09 -0800 From: "Drew Adams" To: "'Aaron S. Hawley'" , <13373@debbugs.gnu.org> References: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> Subject: RE: bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect Date: Mon, 7 Jan 2013 14:29:07 -0800 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit 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-Spam-Score: -1.5 (-) X-Debbugs-Envelope-To: 13373 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.5 (-) > 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. From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 07 18:08:39 2013 Received: (at 13373) by debbugs.gnu.org; 7 Jan 2013 23:08:39 +0000 Received: from localhost ([127.0.0.1]:55733 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsLo6-0003vo-Sz for submit@debbugs.gnu.org; Mon, 07 Jan 2013 18:08:39 -0500 Received: from mail-qc0-f178.google.com ([209.85.216.178]:63627) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsLo4-0003va-ND for 13373@debbugs.gnu.org; Mon, 07 Jan 2013 18:08:37 -0500 Received: by mail-qc0-f178.google.com with SMTP id j34so13495916qco.9 for <13373@debbugs.gnu.org>; Mon, 07 Jan 2013 15:08:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=O+BoxRSgCfxWo81s+FI4v4G1yQ8DpzVzAcLkUPVpXME=; b=OeWzn0ktgwVNVvuvyMCCED0oySpD9ERG2hevjHFgZBgiagFRu+Nq79SHR599c/Skoh iAy9jwCUg3i/ECxpDZ39B/R4QoWvMrNx620J/r8p2aPAIpydNPuvN+OXaqZAvc7Cu9md tFMzVVQApIw2ALdMXmN1ks1bpG1MXdBwXLMl0dcof6xaxvEsnDvS/Xnfl4a0GVQXMgyY QKKCcACOc2Hhob72MDBwYuFaYne2V/r5SMr+NRevHWTf6W2Byvnjxm3tOHrrRKqOhgbQ NmHz10nqk6pdKkHNRcNamKFozwi+848q+U1tVUXAi0SmWCYK29gw7FEgL/VtC8TlPTfq tNTg== MIME-Version: 1.0 Received: by 10.224.146.136 with SMTP id h8mr10396725qav.97.1357600108444; Mon, 07 Jan 2013 15:08:28 -0800 (PST) Received: by 10.49.48.42 with HTTP; Mon, 7 Jan 2013 15:08:28 -0800 (PST) In-Reply-To: References: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> Date: Mon, 7 Jan 2013 18:08:28 -0500 Message-ID: Subject: Re: bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect From: "Aaron S. Hawley" To: Drew Adams Content-Type: text/plain; charset=ISO-8859-1 X-Spam-Score: 0.1 (/) X-Debbugs-Envelope-To: 13373 Cc: 13373@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: 0.1 (/) >> 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: The *Emacs* manual uses the term "numeric argument". It's the name of the section: (info "(emacs) Arguments") > 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. > The main thing "worth fixing" is the misleading statements about the prefix arg. Again, the user manual introduces them as "numeric arguments". It's not as precise as "prefix argument" for the Lisp hackers in the room, but for user's purposes it is probably helpful to do it this way -- as long the section is read in its entirety since the second half has all the special cases. Numeric arguments, prefix arguments, universal arguments, the use of a C-u as a terminator in some cases ("terminator argument?")... the terrain is fraught with peril. It's an Emacs world, we just live in it. -- In general, we reserve the right to have a poor memory--the computer, however, is supposed to remember! Poor computer. -- Guy Lewis Steele Jr. From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 07 18:59:25 2013 Received: (at 13373) by debbugs.gnu.org; 7 Jan 2013 23:59:25 +0000 Received: from localhost ([127.0.0.1]:55755 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsMbE-00058P-ME for submit@debbugs.gnu.org; Mon, 07 Jan 2013 18:59:25 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:20073) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TsMbC-00058D-FR for 13373@debbugs.gnu.org; Mon, 07 Jan 2013 18:59:23 -0500 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by userp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id r07NxF2K004474 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 7 Jan 2013 23:59:15 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r07NxEtZ001294 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 7 Jan 2013 23:59:15 GMT Received: from abhmt102.oracle.com (abhmt102.oracle.com [141.146.116.54]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r07NxEu0025129; Mon, 7 Jan 2013 17:59:14 -0600 Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 07 Jan 2013 15:59:14 -0800 From: "Drew Adams" To: "'Aaron S. Hawley'" References: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> Subject: RE: bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect Date: Mon, 7 Jan 2013 15:59:12 -0800 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-reply-to: Thread-Index: Ac3tK+hHi8LyCFvHQ46fMt+bquU3iQAATiTw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Spam-Score: -1.5 (-) X-Debbugs-Envelope-To: 13373 Cc: 13373@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.2 (----) > >> 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: > > The *Emacs* manual uses the term "numeric argument". It's the name of > the section: (info "(emacs) Arguments") The Emacs manual glosses over some differences that are pertinent to Emacs Lisp. The Elisp manual is the reference in the present context. The Emacs manual here (very near the beginning of the manual) is trying to be pedagogical, presenting an introduction to the concept and the use of a prefix argument. Introducing the prefix argument as something numeric is an abuse that can be excused only on grounds that it presumably helps ease users into understanding the full concept. And it is an abuse that is corrected and clarified in the same node, where it is pointed out that the interpretation of the prefix argument is not always numeric. The last sentence in that introductory node emphasizes that Emacs and its doc refer to this thingie as the "prefix argument". Sure, when the interpretation for a given command is only numeric, it makes little difference whether we refer to it as "numeric argument" or "prefix argument". But it does make a difference in general. There are plenty of cases where it is not numeric or is not interpreted numerically. The difference is especially important for Lisp, where code can explicitly distinguish the raw prefix argument from its numeric value. And in particular, the use by `execute-extended-command' of a prefix argument is not numeric. It passes the raw prefix argument, not its numeric value. This needs to be handled correctly in (elisp) `Interactive Call', where `execute-extended-command' is described. The emphasis here is on the command itself, not on end users and a simplified view of the prefix argument as being only numeric. There is absolutely no numeric interpretation of the prefix argument being done by `execute-extended-command'. It is necessary that it is the raw prefix argument that it passes along, not just its `prefix-numeric-value'. > > 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. > > > The main thing "worth fixing" is the misleading statements > > about the prefix arg. > > Again, the user manual introduces them as "numeric arguments". It's > not as precise as "prefix argument" for the Lisp hackers in the room, > but for user's purposes it is probably helpful to do it this way -- as > long the section is read in its entirety since the second half has all > the special cases. Unlike the Emacs manual, the Elisp manual is primarily a reference manual. And in particular it is aimed at Lisp users. It should be as correct as possible and should use terminology that is not misleading. `We use the term "prefix argument"', as the Emacs manual says in the node you cite. We especially do when there is no numeric interpretation or when imposing such an interpretation would be incorrect - as in the case of `execute-extended-command'. > Numeric arguments, prefix arguments, universal arguments, the use of a > C-u as a terminator in some cases ("terminator argument?")... the > terrain is fraught with peril. It is not at all fraught with peril. But if the manual is not clear then we create unnecessary peril. These terms have specific meanings. Universal argument refers to a command, not to the prefix argument. It "specifies a prefix argument for the following command." Similarly, `C-u' is a key binding for `universal-command'; it is not a prefix argument. These various things are all related, of course, but they are not all the same thing. Their names are not synonyms. Search the Emacs manual for "numeric argument". You will find many occurrences, in places where the numeric interpretion of the prefix argument is involved. Now search the Elisp manual for "numeric argument". You will find very few occurrences, and, again, only where the interpretation is in fact numeric. That is not the case in node `Interactive Call'. "Numeric argument" makes no sense there, but is harmful and misleading. From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 08 08:15:33 2014 Received: (at 13373) by debbugs.gnu.org; 8 Feb 2014 13:15:33 +0000 Received: from localhost ([127.0.0.1]:56706 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC7kq-0003GB-Mh for submit@debbugs.gnu.org; Sat, 08 Feb 2014 08:15:33 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:58839) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC7ko-0003Dd-RU for 13373@debbugs.gnu.org; Sat, 08 Feb 2014 08:15:31 -0500 Received: from [204.14.154.233] (helo=building.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1WC7kZ-0002zr-Km; Sat, 08 Feb 2014 14:15:16 +0100 From: Lars Ingebrigtsen To: "Drew Adams" Subject: Re: bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect References: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> Date: Sat, 08 Feb 2014 05:14:06 -0800 In-Reply-To: <9C4F75D8489349839D5B5F312F55B023@us.oracle.com> (Drew Adams's message of "Sun, 6 Jan 2013 17:02:10 -0800") Message-ID: <87y51lpx0h.fsf@building.gnus.org> User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1WC7kZ-0002zr-Km X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392470116.9017@1JmDiycL+/BXt4tCQ/EVfw X-Spam-Status: No X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 13373 Cc: 13373@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) "Drew Adams" writes: > The doc string is incorrect and misleading in several ways. > > Read function name, then read its arguments and call it. > > To pass a numeric argument to the command you are invoking with, specify > the numeric argument to this command. > > Noninteractively, the argument PREFIXARG is the prefix argument to > give to the command you invoke, if it asks for an argument. > > 1. It is not just a function name that is read. It is (it must be) a > COMMAND name, i.e., an interactive function. > > 2. `execute-extended-command' does NOT read the arguments of the > "function name" it reads. First, a function NAME does not have any > arguments. Second, it is the command so named that reads its own > arguments, if any are read. `e-e-c' does nothing of the kind. > > 3. (What prompted me to write this bug report.) It is not about passing > a "numeric argument" to the command invoked by `e-e-c'. It is about > passing it THE prefix argument, in fact the RAW prefix argument. > > There is a LOT of confusion in this doc string. Almost everything it > says is wrong or misleading. > > [Also: > > 4. There is no reason to skip a line after the first doc line. That is > not the Emacs convention. > > 5. The second sentence is grammatically incorrect. "...to the command > you are invoking with" - invoking WITH? invoking with what? > > 6. The third sentence is confusing. "if it asks for an argument". No > command ever asks the user for a prefix argument. Presumably what is > meant is "if it accepts a prefix argument." > > Anyway, the second and third sentences are verbose and somewhat > repetitive.] Fixed on trunk. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 08 08:15:40 2014 Received: (at control) by debbugs.gnu.org; 8 Feb 2014 13:15:40 +0000 Received: from localhost ([127.0.0.1]:56709 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC7kv-0003Lx-Rv for submit@debbugs.gnu.org; Sat, 08 Feb 2014 08:15:38 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:58846) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC7ku-0003K2-LW for control@debbugs.gnu.org; Sat, 08 Feb 2014 08:15:36 -0500 Received: from [204.14.154.233] (helo=building.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1WC7kf-000300-PJ for control@debbugs.gnu.org; Sat, 08 Feb 2014 14:15:22 +0100 Date: Sat, 08 Feb 2014 05:14:13 -0800 Message-Id: <87wqh5px0a.fsf@building.gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #13373 X-MailScanner-ID: 1WC7kf-000300-PJ X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392470123.01155@vWn+WIMxkmXy9vzpa1P5dA X-Spam-Status: No X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) close 13373 24.4 From unknown Sat Aug 09 04:59:09 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 09 Mar 2014 11:24:08 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator