* bug#55408: Explain the word "interactively" in the Emacs Manual
@ 2022-05-14 8:16 Stefan Kangas
2022-05-14 8:46 ` Eli Zaretskii
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Kangas @ 2022-05-14 8:16 UTC (permalink / raw
To: 55408
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?
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-14 8:16 bug#55408: Explain the word "interactively" in the Emacs Manual Stefan Kangas
@ 2022-05-14 8:46 ` Eli Zaretskii
2022-05-15 12:20 ` Stefan Kangas
0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2022-05-14 8:46 UTC (permalink / raw
To: Stefan Kangas; +Cc: 55408
> 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’. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-14 8:46 ` Eli Zaretskii
@ 2022-05-15 12:20 ` Stefan Kangas
2022-05-15 13:15 ` Eli Zaretskii
` (2 more replies)
0 siblings, 3 replies; 8+ messages in thread
From: Stefan Kangas @ 2022-05-15 12:20 UTC (permalink / raw
To: Eli Zaretskii; +Cc: 55408
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".
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-15 12:20 ` Stefan Kangas
@ 2022-05-15 13:15 ` Eli Zaretskii
2022-05-15 15:12 ` Drew Adams
2022-05-15 13:34 ` Lars Ingebrigtsen
2022-05-15 15:07 ` Drew Adams
2 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2022-05-15 13:15 UTC (permalink / raw
To: Stefan Kangas; +Cc: 55408
> 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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-15 12:20 ` Stefan Kangas
2022-05-15 13:15 ` Eli Zaretskii
@ 2022-05-15 13:34 ` Lars Ingebrigtsen
2022-05-15 15:00 ` Stefan Kangas
2022-05-15 15:07 ` Drew Adams
2 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-05-15 13:34 UTC (permalink / raw
To: Stefan Kangas; +Cc: Eli Zaretskii, 55408
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-15 13:34 ` Lars Ingebrigtsen
@ 2022-05-15 15:00 ` Stefan Kangas
0 siblings, 0 replies; 8+ messages in thread
From: Stefan Kangas @ 2022-05-15 15:00 UTC (permalink / raw
To: Lars Ingebrigtsen; +Cc: Eli Zaretskii, 55408-done
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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-15 12:20 ` Stefan Kangas
2022-05-15 13:15 ` Eli Zaretskii
2022-05-15 13:34 ` Lars Ingebrigtsen
@ 2022-05-15 15:07 ` Drew Adams
2 siblings, 0 replies; 8+ messages in thread
From: Drew Adams @ 2022-05-15 15:07 UTC (permalink / raw
To: Stefan Kangas, Eli Zaretskii; +Cc: 55408@debbugs.gnu.org
> 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:...
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#55408: Explain the word "interactively" in the Emacs Manual
2022-05-15 13:15 ` Eli Zaretskii
@ 2022-05-15 15:12 ` Drew Adams
0 siblings, 0 replies; 8+ messages in thread
From: Drew Adams @ 2022-05-15 15:12 UTC (permalink / raw
To: Eli Zaretskii, Stefan Kangas; +Cc: 55408@debbugs.gnu.org
> 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.
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2022-05-15 15:12 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-05-14 8:16 bug#55408: Explain the word "interactively" in the Emacs Manual Stefan Kangas
2022-05-14 8:46 ` Eli Zaretskii
2022-05-15 12:20 ` Stefan Kangas
2022-05-15 13:15 ` Eli Zaretskii
2022-05-15 15:12 ` Drew Adams
2022-05-15 13:34 ` Lars Ingebrigtsen
2022-05-15 15:00 ` Stefan Kangas
2022-05-15 15:07 ` Drew Adams
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.