--- Begin Message ---
|
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?
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#55408: Explain the word "interactively" in the Emacs Manual |
|
Date: |
Sun, 15 May 2022 17:00:25 +0200 |
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.
--- End Message ---