bug#13571: 24.3.50; doc of `interactive'

bug#13571: 24.3.50; doc of `interactive'

[Drew Adams]

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 eliz@gnu.org-20130125143821-1ykj7ia1qjojjjnp
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#13571: 24.3.50; doc of `interactive'

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

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

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

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#13571: 24.3.50; doc of `interactive'

[Drew Adams]

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