bug#13571: 24.3.50; doc of `interactive'

[Drew Adams <drew.adams@oracle.com>]

> > 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.
> 
> I disagree.  Saying that it's a variable helps with understanding here.

No.  There are several kinds of variable in Emacs Lisp.  This is
a very particular kind of variable.  And what is  particularly
special about it (besides being global and dynamic) is that it is
(1) specifically intended for user modification and, in particular,
(2) modification using the Customize UI.

> > 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
> 
> All these say that are symbols, and I think that's clear enough.

1. Wrong. z and Z say no such thing (in the doc string).

2. You miss the point, which is made extra clear in the part of
the report that you elided:

  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.

If you consult that entry you see this:

  `S'
     An interned symbol whose name is read in the minibuffer.  Terminate
     the input with either `C-j' or <RET>.  Other characters that
     normally terminate a symbol (e.g., whitespace, parentheses and
     brackets) do not do so here.  Prompt.

Very clear.  It reads a name and returns a symbol.  The same
behavior is true for the other codes mentioned in this bug
report, but their descriptions do NOT make this clear.  That's
the bug.

A symbol is an object that has a name.  A name is not a symbol.
A symbol name is read with these codes.  A symbol is not read,
but a symbol is returned.