Subject: bug#52839: closed (Re: bug#52839: 29.0.50; The '(declare (modes MODE...))' NEWS entry is confusing)

From: [email-masked] (GNU bug Tracking System)
Date: Wed, 29 Dec 2021 14:46:02 +0000

Your bug report

#52839: 29.0.50; The '(declare (modes MODE...))' NEWS entry is confusing

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].

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

Subject: Re: bug#52839: 29.0.50; The '(declare (modes MODE...))' NEWS entry is confusing
From: Eli Zaretskii <[email-masked]>
To: Dmitry Gutov <[email-masked]>
Cc: [email-masked]
Date: Wed, 29 Dec 2021 16:45:17 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Dmitry Gutov <[email-masked]>
> Date: Tue, 28 Dec 2021 03:49:33 +0200
> 
> It says these syntaxes "declare how completion should happen" or one of
> them "can be used as a general predicate to say whether the command
> should be present when completing with 'M-x TAB'", but neither have any
> effect unless the user customizes read-extended-command-predicate.
> 
> The previous entry (the one about (interactive "p" dired-mode)) doesn't
> mention the predicate user option either.
> 
> Should read-extended-command-predicate be set to
> #'command-completion-default-include-p by default? Otherwise the NEWS
> entries (at least one of them) should probably mention it.

Thanks, I added the caveat to these NEWS entries.

> When reading the manual (subsection "Specifying Modes For Commands"),
> I'm feeling a similar problem.
> command-completion-default-include-p *is* mentioned, but only somewhere
> in the middle.

That's a 75-line node, so "in the middle" is also "close to the
beginning".  In fact, it mentions it immediately after explaining the
issue and saying that Emacs has a mechanism for tagging commands as
being specific to modes.  I don't see how this could be moved earlier
without severely disrupting the text didactically.

> The intro gives the impression that "specifying modes" will have an
> effect by default.

I don't think so, but I now tried to make it even more evident.

>    * Change the 'M-x' binding to call execute-extended-command-for-buffer
>    instead. The behavior of execute-extended-command won't change, but
>    that probably isn't going to save anybody: the user who set up the
>    binding to call that command explicitly is probably rare.
> 
>    * Have the subsection be actually about the command
>    execute-extended-command-for-buffer. Mention its binding (M-X) and say
>    that (interactive nil dired-mode) affects its behavior. Then mention
>    that by customizing read-extended-command-predicate the user can have
>    'M-x' behaving like that as well. If they like.

I've added the reference to execute-extended-command-for-buffer and
its binding.

Subject: 29.0.50; The '(declare (modes MODE...))' NEWS entry is confusing
From: Dmitry Gutov <[email-masked]>
To: [email-masked]
Date: Tue, 28 Dec 2021 03:49:33 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

It says these syntaxes "declare how completion should happen" or one of
them "can be used as a general predicate to say whether the command
should be present when completing with 'M-x TAB'", but neither have any
effect unless the user customizes read-extended-command-predicate.

The previous entry (the one about (interactive "p" dired-mode)) doesn't
mention the predicate user option either.

Should read-extended-command-predicate be set to
#'command-completion-default-include-p by default? Otherwise the NEWS
entries (at least one of them) should probably mention it.

When reading the manual (subsection "Specifying Modes For Commands"),
I'm feeling a similar problem.
command-completion-default-include-p *is* mentioned, but only somewhere
in the middle. The intro gives the impression that "specifying modes"
will have an effect by default.

The small two paragraphs saying

   Specifying modes _may_ affect completion in @kbd{M-x}

   ...when using the ... predicate ...

look kind of sneaky. Like, we have just described a way to set up a
bunch of meaningful information, and that _may_ affect your Emacs's
behavior if (...). That's weird, but I'm not sure how to resolve that
best. Apart from changing the default value, that is.

Other options may be:

   * Change the 'M-x' binding to call execute-extended-command-for-buffer
   instead. The behavior of execute-extended-command won't change, but
   that probably isn't going to save anybody: the user who set up the
   binding to call that command explicitly is probably rare.

   * Have the subsection be actually about the command
   execute-extended-command-for-buffer. Mention its binding (M-X) and say
   that (interactive nil dired-mode) affects its behavior. Then mention
   that by customizing read-extended-command-predicate the user can have
   'M-x' behaving like that as well. If they like.