GNU bug report logs - #13571
24.3.50; doc of `interactive'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13571 in the body.
You can then email your comments to 13571 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.3.50; doc of `interactive'
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 eliz <at> 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'
 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 14577 <at> debbugs.gnu.org, 13571 <at> debbugs.gnu.org
Subject: Re: bug#14577: 24.3.50; doc string of `interactive' is wrong
Date: Fri, 29 Apr 2016 00:18:05 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> The doc string confuses wrt its optional argument.  Please refer to
> (elisp) `Using Interactive' for a proper description, the essentials of
> which can be used to fix the doc string.
>
> 1. There is one optional argument, which should not be called ARGS, as
> that confuses things.  If there is an argument for `interactive' then
> there is only one.  The optional argument to `interactive' provides the
> arguments to the command.  The Elisp manual calls the `interactive'
> argument ARG-DESCRIPTOR, which is OK.
>
> 2. "To get several arguments" - Again, such language is
> misleading/confusing.  The doc string tries to use "argument" in more
> than one sense, without distinguishing or defining them.  IOW, if you
> want to speak about the arguments that get passed to the command (not to
> `interactive'), then be careful about the wording.
>
> 3. "it is evaluated to get a list of arguments to pass to the function".
> Say "command", not "function", here, to avoid confusion with the
> argument to `interactive'.  Better is to avoid such language altogether.

I've now tweaked this on the trunk.

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13571 <at> debbugs.gnu.org
Subject: Re: bug#13571: 24.3.50; doc of `interactive'
Date: Fri, 29 Apr 2016 00:23:07 +0200

"Drew Adams" <drew.adams <at> 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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 13571 <at> debbugs.gnu.org
Subject: RE: bug#13571: 24.3.50; doc of `interactive'
Date: Fri, 29 Apr 2016 09:00:59 -0700 (PDT)

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

Previous Next

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