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

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 55408 in the body.
You can then email your comments to 55408 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: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Explain the word "interactively" in the Emacs Manual
Date: Sat, 14 May 2022 10:16:06 +0200

Severity: wishlist

It would be useful if the word "interactively" was explained in the
Emacs manual, and if there was an index entry for it.  Otherwise, it
might be hard to understand a docstring like this one for a new user:

    (defun package-update-all (&optional query)
      "Upgrade all packages.
    If QUERY, ask the user before updating packages.  Interactively,
    QUERY is always true."

Perhaps it should be explained in `(emacs) Commands' and/or in the Glossary?

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 55408 <at> debbugs.gnu.org
Subject: Re: bug#55408: Explain the word "interactively" in the Emacs Manual
Date: Sat, 14 May 2022 11:46:52 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 14 May 2022 10:16:06 +0200
> 
> It would be useful if the word "interactively" was explained in the
> Emacs manual, and if there was an index entry for it.  Otherwise, it
> might be hard to understand a docstring like this one for a new user:
> 
>     (defun package-update-all (&optional query)
>       "Upgrade all packages.
>     If QUERY, ask the user before updating packages.  Interactively,
>     QUERY is always true."
> 
> Perhaps it should be explained in `(emacs) Commands' and/or in the Glossary?

Does it really need to be explained?  It's a word used for its literal
meaning.  The very first line presented in the *Help* buffer says:

  package-update-all is an interactive compiled Lisp function in
  ‘package.el’.            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55408 <at> debbugs.gnu.org
Subject: Re: bug#55408: Explain the word "interactively" in the Emacs Manual
Date: Sun, 15 May 2022 14:20:41 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> Does it really need to be explained?  It's a word used for its literal
> meaning.

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

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 55408 <at> debbugs.gnu.org
Subject: Re: bug#55408: Explain the word "interactively" in the Emacs Manual
Date: Sun, 15 May 2022 16:15:45 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 15 May 2022 14:20:41 +0200
> Cc: 55408 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Does it really need to be explained?  It's a word used for its literal
> > meaning.
> 
> 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,".

We use this style in many doc strings.  I'd consider it a standard
Emacs language of describing what happens in interactive invocations,
and presume that any Emacs user knows only too well what it means.
If we change our style, we'd have to change it in many places,
including the manual.

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

It is both a command and a function.  Every command can be also
invoked non-interactively.  That is what that sentence says, and has
been saying since day one.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55408 <at> debbugs.gnu.org
Subject: Re: bug#55408: Explain the word "interactively" in the Emacs Manual
Date: Sun, 15 May 2022 15:34:58 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

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

Yes, that could be clearer; please go ahead and alter.

> In general, perhaps docstrings should prefer something like "When
> used as a command," instead of "When called interactively,".

I'm not sure that's an improvement.  Yes, we do use "command" with a
clear meaning in some parts (like in `describe-command'), but I think
"called interactively" is probably more immediately understandable to
most people who've used Emacs a bit.

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

Message #22 received at 55408-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55408-done <at> debbugs.gnu.org
Subject: Re: bug#55408: Explain the word "interactively" in the Emacs Manual
Date: Sun, 15 May 2022 17:00:25 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
> > 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.
>
> Yes, that could be clearer; please go ahead and alter.

Done.

> > In general, perhaps docstrings should prefer something like "When
> > used as a command," instead of "When called interactively,".
>
> I'm not sure that's an improvement.  Yes, we do use "command" with a
> clear meaning in some parts (like in `describe-command'), but I think
> "called interactively" is probably more immediately understandable to
> most people who've used Emacs a bit.

OK, I guess since neither you or Eli are too enthusiastic, we can just
leave this as is.  I'm therefore closing this bug.

Thanks for considering the proposal.

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

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: RE: [External] : 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:...

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

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

> We use this style in many doc strings.  I'd consider it a standard
> Emacs language of describing what happens in interactive invocations,
> and presume that any Emacs user knows only too well what it means.
> If we change our style, we'd have to change it in many places,
> including the manual.

I happen to agree with that, generally.  It's part
of what I meant by:

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

> > > 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".
> 
> It is both a command and a function.  Every command can be also
> invoked non-interactively.  That is what that sentence says, and has
> been saying since day one.

Agreed.  The "problem" is that the meaning might
not be clear to some (many?) users consulting a
doc string.

Whether it's worth trying to solve that problem,
with the attendant bother you mention (changing
lots of doc strings), and with the difficulty of
coming up with a short-and-sweet-and-clear fix,
which I mention, is another question.

IMO, things are pretty good already.  But yeah,
it's likely a bit of a problem, esp. for newbies.

Previous Next

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