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 15:59:12 -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 1357603221 3322 80.91.229.3 (8 Jan 2013 00:00:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 8 Jan 2013 00:00:21 +0000 (UTC) Cc: 13373@debbugs.gnu.org To: "'Aaron S. Hawley'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jan 08 01:00:34 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 1TsMcK-0000gr-Ri for geb-bug-gnu-emacs@m.gmane.org; Tue, 08 Jan 2013 01:00:33 +0100 Original-Received: from localhost ([::1]:50127 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TsMc4-0005VY-Pn for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Jan 2013 19:00:16 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:38127) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TsMc0-0005VT-6O for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 19:00:14 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TsMbt-0002wB-Iy for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 19:00:11 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42514) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TsMbt-0002rM-Gf for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 19:00:05 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TsMbr-00059m-O1 for bug-gnu-emacs@gnu.org; Mon, 07 Jan 2013 19:00:04 -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: Tue, 08 Jan 2013 00:00:03 +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.135760316519745 (code B ref 13373); Tue, 08 Jan 2013 00:00:03 +0000 Original-Received: (at 13373) by debbugs.gnu.org; 7 Jan 2013 23:59:25 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 07 Jan 2013 15:59:14 -0800 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-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:69474 Archived-At: > >> 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.