Subject: bug#13571: 24.3.50; doc of `interactive'

From: "Drew Adams" <[email-masked]>
Date: Sun, 27 Jan 2013 18:21:48 -0800

1. For `v' it should not say "Variable name", even if it also mentions
`custom-variable-p'.  It should speak of "option", not "variable".  E.g.:
 
 Option: a symbol that is `custom-variable-p'.  The name is read.
 
A user should not need to click `custom-variable-p', or be already
familiar with that Lisp predicate, to understand that this reads
an option name, not the name of an arbitrary variable.

2. There is confusion in the doc string and in (elisp) `Interactive Codes'
regarding (a) what a given interactive code reads and (b) what value it
returns/provides for the argument.

In particular, we misleadingly see mention of "name" here and there.

A name is read in such cases, but a name, i.e., a string, is not always what is
returned.  In many cases, a symbol is returned.  A symbol is a special Lisp
object, and definitely not a name.  It has a name, as well as other properties.

Some of the entries, such as `b', are correct: they read and return a name, not
the object named (e.g. a buffer).

The following entries incorrectly speak of "name".  They read names, but they
return symbols, and the doc is not clear about this.

a
C
v
z
Z

See the entry for `S' in the manual (not the doc string), for proper distinction
between what is read (a symbol name) and what is returned (a symbol).  See also
#1 above, for another example of possible wording.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-01-25 on ODIEONE
Bzr revision: 111604 [email-masked]
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'