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

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

[Dmitry Gutov]

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.

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

[Eli Zaretskii]

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

Stefan, any comments?

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Apart from changing the default value, that is.

That seems to be asking a question: what is the reason for the current
default value.  AFAICT this comes from:

    commit 927b88571cebb4f64aca360fbfa5d15a1f922ad6
    Author: Eli Zaretskii <eliz@gnu.org>
    Date:   Wed Feb 17 18:53:54 2021 +0200
    
        Disable filtering of commands in M-x completion
        
        This makes the default behavior like it was before:
        M-x completion doesn't filter out any commands.  To
        have commands filtered based on their relevance to the
        current buffer's modes, customize the option
        'read-extended-command-predicate' to call
        'command-completion-default-include-p'.
    
        * doc/lispref/commands.texi (Interactive Call):
        * doc/emacs/m-x.texi (M-x): Update the description of
        'read-extended-command-predicate' and improve wording.
        
        * etc/NEWS: Update the entry about
        'read-extended-command-predicate'.
        
        * lisp/simple.el (read-extended-command-predicate): Change default
        value to nil.  Update doc string.  Add :group.
        (read-extended-command): Handle nil as meaning to apply
        no-filtering.

But the commit doesn't say why this change was made (other than saying
"like it was before").  Was there a specific problem introduced by the
filtering, or was it a change based on a judgment call about what the
default should be to balance the tradeoffs between bringing new
features and surprising the users?


        Stefan "who doesn't have an opinion on this one"

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

[Eli Zaretskii]

> Cc: 52839@debbugs.gnu.org
> Date: Tue, 28 Dec 2021 15:27:38 -0500
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> But the commit doesn't say why this change was made (other than saying
> "like it was before").  Was there a specific problem introduced by the
> filtering, or was it a change based on a judgment call about what the
> default should be to balance the tradeoffs between bringing new
> features and surprising the users?

The latter.  We then added the "M-X" binding for the new command that
always omits inapplicable commands from the completion, so now users
can have the cake and eat it, too.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> The latter.  We then added the "M-X" binding for the new command that
> always omits inapplicable commands from the completion, so now users
> can have the cake and eat it, too.

That's not what `M-X' does, though -- it filters out commands that
aren't particularly marked for the current mode, but there's always
other commands that will be useful.

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

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  52839@debbugs.gnu.org,
>   dgutov@yandex.ru
> Date: Wed, 29 Dec 2021 15:51:00 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The latter.  We then added the "M-X" binding for the new command that
> > always omits inapplicable commands from the completion, so now users
> > can have the cake and eat it, too.
> 
> That's not what `M-X' does, though -- it filters out commands that
> aren't particularly marked for the current mode, but there's always
> other commands that will be useful.

How is that different from what I said?

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> > The latter.  We then added the "M-X" binding for the new command that
>> > always omits inapplicable commands from the completion, so now users
>> > can have the cake and eat it, too.
>> 
>> That's not what `M-X' does, though -- it filters out commands that
>> aren't particularly marked for the current mode, but there's always
>> other commands that will be useful.
>
> How is that different from what I said?

There's many commands that are applicable in any given mode that will
not be listed by `M-X'.  (I.e., all commands that are generally useful
across modes.)

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

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

[Eli Zaretskii]

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

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

[Dmitry Gutov]

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.