GNU bug report logs - #55408
Explain the word "interactively" in the Emacs Manual

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Eli Zaretskii <eliz <at> gnu.org>
Cc: "55408 <at> debbugs.gnu.org" <55408 <at> debbugs.gnu.org>
Subject: bug#55408: Explain the word "interactively" in the Emacs Manual
Date: Sun, 15 May 2022 15:07:00 +0000

> IMHO, it is not immediately clear what is meant.
> 
> The docstring of `package-update-all' currently says: "Interactively,
> QUERY is always true."  AFAIU, this is short for "When called
> interactively," which is more clear but still not as clear as it could
> be.  In general, perhaps docstrings should prefer something like "When
> used as a command," instead of "When called interactively,".

FWIW -

1. I don't have a problem with doc strings that say
   either "When called interactively" or "Interactively".
   But that's likely because I've picked up the habit /
   convention.

2. Speaking of use as a "command" isn't too helpful, I
   think, in particular because many users don't know
   that a "command" is a function that can be called
   interactively, i.e., with `M-x' or a key binding. And
   if a command is not called interactively, is it not
   still called "as a command"?  Arguably not, but this
   isn't immediately clear to all.

3. Clearest of all, I think, is to use "When called from
   Lisp".

   IOW, don't bother to characterize the non-Lisp case
   as "interactive".  (Well, maybe sometimes it helps
   to explicitly characterize each case: use by "Lisp"
   and use "interactively".) 

   We typically (should) start the doc string with a
   description of the interactive use.  Following that
   with "When called from Lisp" makes things pretty
   clear, I think.

> > The very first line presented in the *Help* buffer says:
> >   package-update-all is an interactive compiled Lisp function in
> >   ‘package.el’.            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> I think it would probably be more helpful if that line said "a
> command" instead of "an interactive compiled Lisp function".

See above.  I kinda disagree, because "command" is
not always immediately clear to users.

There's maybe no magic bullet here: something short
and sweet that can be repeated in most doc strings,
but that also gets across everything about this:

1. A "command" is a function that you can call
   "interactively", i.e., with `M-x' or a key binding.

2. A command can also be called noninteractively,
   i.e., "from Lisp".

3. Arguments, and more seldom behavior in general,
   can differ, depending on whether a command is
   invoked interactively or from Lisp.

4. For #3, here are the argument (and behavior)
   descriptions:...

Previous Next

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