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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 15 May 2022 16:15:45 +0300

> From: Stefan Kangas <[email-masked]>
> Date: Sun, 15 May 2022 14:20:41 +0200
> Cc: [email-masked]
> 
> Eli Zaretskii <[email-masked]> 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.