* bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect @ 2013-01-07 1:02 Drew Adams 2013-01-07 21:27 ` Aaron S. Hawley 2014-02-08 13:14 ` Lars Ingebrigtsen 0 siblings, 2 replies; 6+ messages in thread From: Drew Adams @ 2013-01-07 1:02 UTC (permalink / raw) To: 13373 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' ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect 2013-01-07 1:02 bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect Drew Adams @ 2013-01-07 21:27 ` Aaron S. Hawley 2013-01-07 22:29 ` Drew Adams 2014-02-08 13:14 ` Lars Ingebrigtsen 1 sibling, 1 reply; 6+ messages in thread From: Aaron S. Hawley @ 2013-01-07 21:27 UTC (permalink / raw) To: 13373 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect 2013-01-07 21:27 ` Aaron S. Hawley @ 2013-01-07 22:29 ` Drew Adams 2013-01-07 23:08 ` Aaron S. Hawley 0 siblings, 1 reply; 6+ messages in thread From: Drew Adams @ 2013-01-07 22:29 UTC (permalink / raw) To: 'Aaron S. Hawley', 13373 > 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect 2013-01-07 22:29 ` Drew Adams @ 2013-01-07 23:08 ` Aaron S. Hawley 2013-01-07 23:59 ` Drew Adams 0 siblings, 1 reply; 6+ messages in thread From: Aaron S. Hawley @ 2013-01-07 23:08 UTC (permalink / raw) To: Drew Adams; +Cc: 13373 >> 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect 2013-01-07 23:08 ` Aaron S. Hawley @ 2013-01-07 23:59 ` Drew Adams 0 siblings, 0 replies; 6+ messages in thread From: Drew Adams @ 2013-01-07 23:59 UTC (permalink / raw) To: 'Aaron S. Hawley'; +Cc: 13373 > >> 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect 2013-01-07 1:02 bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect Drew Adams 2013-01-07 21:27 ` Aaron S. Hawley @ 2014-02-08 13:14 ` Lars Ingebrigtsen 1 sibling, 0 replies; 6+ messages in thread From: Lars Ingebrigtsen @ 2014-02-08 13:14 UTC (permalink / raw) To: Drew Adams; +Cc: 13373 "Drew Adams" <drew.adams@oracle.com> 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/ ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-02-08 13:14 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2013-01-07 1:02 bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect Drew Adams 2013-01-07 21:27 ` Aaron S. Hawley 2013-01-07 22:29 ` Drew Adams 2013-01-07 23:08 ` Aaron S. Hawley 2013-01-07 23:59 ` Drew Adams 2014-02-08 13:14 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.