[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#55408: Explain the word "interactively" in the Emacs Manual
From: |
Drew Adams |
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:...