bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Drew Adams]

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'
 

bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Aaron S. Hawley]

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.

bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Drew Adams]

> 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.

bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Aaron S. Hawley]

>> 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.

bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Drew Adams]

> >> 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.

bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Lars Ingebrigtsen]

"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/