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.