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.