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

[Dmitry Gutov <dgutov@yandex.ru>]

On 29.12.2021 17:45, Eli Zaretskii wrote:
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> 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.

Thank you.