Subject: Re: bug#54964: 28.1; mistatement in NEWS about read-extended-command-predicate

From: Howard Melman <[email-masked]>
Date: Sat, 16 Apr 2022 09:30:27 -0400

Eli Zaretskii <[email-masked]> writes:

>> This is like ‘execute-extended-command’, but it limits the
>> completions to commands that are particularly relevant to the
>> current buffer.  This includes commands that have been marked as
>> being specially designed for the current major mode (and enabled
>> minor modes), as well as commands bound in the active local key
>> maps.
>
> Yes, but again: how is this relevant to that particular NEWS entry?
>
> execute-extended-command-for-buffer is covered by a separate NEWS
> entry, which says:
>
>   ** New command 'execute-extended-command-for-buffer'.
>   This new command, bound to 'M-S-x', works like
>   'execute-extended-command', but limits the set of commands to the
>   commands that have been determined to be particularly useful with the
>   current mode.
>
> By contrast, the NEWS entry with which this bug report deals doesn't
> mention execute-extended-command-for-buffer at all.  Its says this:
>
>   ** New 'declare' forms to control completion of commands in 'M-x'.
>   '(declare (completion PREDICATE))' can be used as a general predicate
>   to say whether the command should be considered a completion candidate
>   when completing with 'M-x TAB'.
>
>   '(declare (modes MODE...))' can be used as a short-hand way of saying
>   that the command should be considered a completion candidate when
>   completing on commands from buffers in major modes derived from
>   MODE..., or, if it's a minor mode, when that minor mode is enabled in
>   the current buffer.
>
>   Note that these forms will only have their effect if the
>   'read-extended-command-predicate' user option is customized to call
>   'command-completion-default-include-p' or a similar function.  The
>   default value of 'read-extended-command-predicate' is nil, which means
>   no commands that match what you have typed are excluded from being
>   completion candidates.
>
> Is something wrong/inaccurate with the text of the above NEWS entry?
> An honest question, because I really don't see anything wrong here.

If the NEWS entry in question is just about M-x then you are
correct that it is fine.  But if it's about these declare
forms in general then it seems to be problematic.  I read it
as the latter for two reasons.  First the header:

   ** New 'declare' forms to control completion of commands in 'M-x'.

reads to me as being about "New 'declare' forms" which are
(incidently) used to control completion in M-x. That they
are also used in M-S-x seems relevant though it's not
stated.

Second, the final paragraph in question, talks about "these
forms" and doesn't mention M-x so I took "excluded from being
completion candidates" to mean from all commands.

This entry read to me as if it was written before
execute-extended-command-for-buffer existed and wasn't
updated after it was.

I think adding to the end something like: "from M-x (though
they are used by M-S-x which see below)". would clarify it.

-- 

Howard