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

Previous Next

Full log

Message #11 received at 13373 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Aaron S. Hawley'" <aaron.s.hawley <at> gmail.com>, <13373 <at> debbugs.gnu.org>
Subject: RE: bug#13373: 24.3.50;
	doc string of `execute-extended-command' is incorrect
Date: Mon, 7 Jan 2013 14:29:07 -0800

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.