bug#55408: Explain the word "interactively" in the Emacs Manual

bug#55408: Explain the word "interactively" in the Emacs Manual

[Stefan Kangas]

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?

bug#55408: Explain the word "interactively" in the Emacs Manual

[Eli Zaretskii]

> From: Stefan Kangas <stefan@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’.            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

bug#55408: Explain the word "interactively" in the Emacs Manual

[Stefan Kangas]

Eli Zaretskii <eliz@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".

bug#55408: Explain the word "interactively" in the Emacs Manual

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 15 May 2022 14:20:41 +0200
> Cc: 55408@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@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.

bug#55408: Explain the word "interactively" in the Emacs Manual

[Lars Ingebrigtsen]

Stefan Kangas <stefan@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

bug#55408: Explain the word "interactively" in the Emacs Manual

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@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.

bug#55408: Explain the word "interactively" in the Emacs Manual

[Drew Adams]

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

bug#55408: Explain the word "interactively" in the Emacs Manual

[Drew Adams]

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