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

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 15 May 2022 15:01:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
55408: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=55408
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#55408: Explain the word "interactively" in the Emacs Manual
From: Stefan Kangas <[email-masked]>
To: Lars Ingebrigtsen <[email-masked]>
Cc: Eli Zaretskii <[email-masked]>, [email-masked]
Date: Sun, 15 May 2022 17:00:25 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Lars Ingebrigtsen <[email-masked]> writes:

> Stefan Kangas <[email-masked]> 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.

Subject: Explain the word "interactively" in the Emacs Manual
From: Stefan Kangas <[email-masked]>
To: [email-masked]
Date: Sat, 14 May 2022 10:16:06 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

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?