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

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

[Howard Melman]

The Emacs 28.1 NEWS item:

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

ends with:

    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.

But I think this isn't true because the new command
execute-extended-command-for-buffer bound to M-S-x by
default will filter the commands based on these declare forms.

Howard


In GNU Emacs 28.1 (build 1, x86_64-apple-darwin20.6.0, Carbon Version 164 AppKit 2022.6)
of 2022-04-09 built on Mac-1649520554451.local
Repository revision: ee79b048bbb2fd4a962dfb2204cc7a2f0d5237d8
Repository branch: 28.1-mac-9.0-CI
Windowing system distributor 'Apple Inc.', version 11.6.5
System Description:  macOS 11.6.5

Configured using:
'configure --with-mac
--enable-locallisppath=/usr/local/share/emacs/site-lisp:/opt/homebrew/share/emacs/site-lisp
--enable-mac-app=/Users/runner/work/homebrew-emacsmacport/homebrew-emacsmacport/build-scripts/emacs-source/tmproot
--prefix=/Users/runner/work/homebrew-emacsmacport/homebrew-emacsmacport/build-scripts/emacs-source/tmproot
--enable-mac-self-contained --with-modules'

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

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Fri, 15 Apr 2022 16:16:07 -0400
> 
> The Emacs 28.1 NEWS item:
> 
>     ** New 'declare' forms to control completion of commands in 'M-x'.
> 
> ends with:
> 
>     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.
> 
> But I think this isn't true because the new command
> execute-extended-command-for-buffer bound to M-S-x by
> default will filter the commands based on these declare forms.

What you say is true, but how is it relevant to the 'declare' forms
mentioned in that NEWS entry?  M-S-x doesn't use any of them, and the
NEWS entry doesn't describe that command, it only describes the two
new 'declare' forms.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> What you say is true, but how is it relevant to the 'declare' forms
> mentioned in that NEWS entry?  M-S-x doesn't use any of them, and the
> NEWS entry doesn't describe that command, it only describes the two
> new 'declare' forms.

M-S-x does use the new declare forms, though?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Howard Melman <hmelman@gmail.com>,  54964@debbugs.gnu.org
> Date: Sat, 16 Apr 2022 11:27:23 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > What you say is true, but how is it relevant to the 'declare' forms
> > mentioned in that NEWS entry?  M-S-x doesn't use any of them, and the
> > NEWS entry doesn't describe that command, it only describes the two
> > new 'declare' forms.
> 
> M-S-x does use the new declare forms, though?

That NEWS entry describes two 'declare' forms:

   '(declare (completion PREDICATE))'
   '(declare (modes MODE...))'

Are you saying that M-S-x uses one of these two?  Then I must be
missing something.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> That NEWS entry describes two 'declare' forms:
>
>    '(declare (completion PREDICATE))'
>    '(declare (modes MODE...))'
>
> Are you saying that M-S-x uses one of these two?  Then I must be
> missing something.

Doc string:

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.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: hmelman@gmail.com,  54964@debbugs.gnu.org
> Date: Sat, 16 Apr 2022 12:59:52 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > That NEWS entry describes two 'declare' forms:
> >
> >    '(declare (completion PREDICATE))'
> >    '(declare (modes MODE...))'
> >
> > Are you saying that M-S-x uses one of these two?  Then I must be
> > missing something.
> 
> Doc string:
> 
> 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.

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

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> 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

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

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sat, 16 Apr 2022 09:30:27 -0400
> 
> 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.

There's no real way for us to clarify NEWS entries after the
corresponding Emacs version was released, since we cannot
retroactively modify released versions, and Emacs 28.2 will have its
own section in NEWS, separate from Emacs 28.1.  And since this is
about something that is not even explicitly stated in NEWS, but your
inference from what is written there, I don't see an urgent need to
try to find some way of clarifying it.  The downside, I presume, is
that someone else could perhaps be led to the same erroneous
conclusion as you were.  We'll have to live with that, I guess.

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

[Howard Melman]

On Apr 16, 2022, at 9:55 AM, Eli Zaretskii <eliz@gnu.org> wrote:

>> 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.
> 
> There's no real way for us to clarify NEWS entries after the
> corresponding Emacs version was released, since we cannot
> retroactively modify released versions, and Emacs 28.2 will have its
> own section in NEWS, separate from Emacs 28.1.  And since this is
> about something that is not even explicitly stated in NEWS, but your
> inference from what is written there, I don't see an urgent need to
> try to find some way of clarifying it.  The downside, I presume, is
> that someone else could perhaps be led to the same erroneous
> conclusion as you were.  We'll have to live with that, I guess.

I mean you could clarify the 28.1 entry and then anyone that 
skipped 28.1 and went to a later version would benefit.  

This is obviously minor. I don't need the clarification, I reported it
to benefit anyone else that might.

Howard

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

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> I mean you could clarify the 28.1 entry and then anyone that 
> skipped 28.1 and went to a later version would benefit.  

Yup.  I've now done so on the emacs-28 branch.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  54964@debbugs.gnu.org
> Date: Sat, 16 Apr 2022 16:25:10 +0200
> 
> Howard Melman <hmelman@gmail.com> writes:
> 
> > I mean you could clarify the 28.1 entry and then anyone that 
> > skipped 28.1 and went to a later version would benefit.  
> 
> Yup.  I've now done so on the emacs-28 branch.

So now you get to merge that to master, as punishment ;-)

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> So now you get to merge that to master, as punishment ;-)

Eek!  I forgot the "don't merge to master" thing.  I'm sorry.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no