bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Stefan Kangas]

Severity: wishlist

For example, in Dired, I type `C-h f dired-do-chmod RET' and read:

    It is bound to M, <menu-bar> <operate> <Change Mode...>.

Is the "<menu-bar> ..." part there very useful?  I personally find it
confusing and distracting.  This is true even when I am specifically
developing menus; I'd rather look at the menu definition and the
resulting menu bar.

I would therefore like to suggest either:

a) Displaying nothing at all for such bindings.  The menu entries will
   be shown in the menu itself, and that is enough.

   In this case, we could have an option to revert to the old behavior.

b) Show it separately from other key bindings at the end, maybe
   something like this:

  Probably introduced at or before Emacs version 24.3.
  It can be invoked from the menu: "Operate" -> "Change Mode..."

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> b) Show it separately from other key bindings at the end, maybe
>    something like this:
>
>   Probably introduced at or before Emacs version 24.3.
>   It can be invoked from the menu: "Operate" -> "Change Mode..."

I think that's a good idea.

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

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 29 Dec 2021 04:40:56 -0800
> 
> For example, in Dired, I type `C-h f dired-do-chmod RET' and read:
> 
>     It is bound to M, <menu-bar> <operate> <Change Mode...>.
> 
> Is the "<menu-bar> ..." part there very useful?

I think it's as useful as the other key bindings we show there.  This
doesn't annoy me, and I sometimes find it useful.

There's no reason to believe that people remember all the menu items
by heart, no more than we expect them to remember key sequences.  I'm
sure that if you look at the menu bindings, you will sometimes find
items there you didn't know about, or knew but forgot.

> I would therefore like to suggest either:
> 
> a) Displaying nothing at all for such bindings.  The menu entries will
>    be shown in the menu itself, and that is enough.
> 
>    In this case, we could have an option to revert to the old behavior.
> 
> b) Show it separately from other key bindings at the end, maybe
>    something like this:

This is a serious change in behavior, so I think it could only fly as
an opt-in feature.  It sounds like a personal preference, so an
option, off by default, for it sounds about right.

Thanks.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I would therefore like to suggest either:
>>
>> a) Displaying nothing at all for such bindings.  The menu entries will
>>    be shown in the menu itself, and that is enough.
>>
>>    In this case, we could have an option to revert to the old behavior.
>>
>> b) Show it separately from other key bindings at the end, maybe
>>    something like this:
>
> This is a serious change in behavior, so I think it could only fly as
> an opt-in feature.  It sounds like a personal preference, so an
> option, off by default, for it sounds about right.

I assume you are talking by option a).  I retract that proposal, and
propose option b) as the default behaviour.  Thanks.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 29 Dec 2021 06:49:12 -0800
> Cc: 52870@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> I would therefore like to suggest either:
> >>
> >> a) Displaying nothing at all for such bindings.  The menu entries will
> >>    be shown in the menu itself, and that is enough.
> >>
> >>    In this case, we could have an option to revert to the old behavior.
> >>
> >> b) Show it separately from other key bindings at the end, maybe
> >>    something like this:
> >
> > This is a serious change in behavior, so I think it could only fly as
> > an opt-in feature.  It sounds like a personal preference, so an
> > option, off by default, for it sounds about right.
> 
> I assume you are talking by option a).  I retract that proposal, and
> propose option b) as the default behaviour.  Thanks.

If by b) you mean to push the menu binding to the very end, where it
will probably not seen at all, then I don't think that could be the
default, either.  Just changing the order, so that non-menu bindings
are shown first, is okay, I think.  But banishing that to after the
version where the command was introduced doesn't sound like something
I could agree to by default.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> If by b) you mean to push the menu binding to the very end, where it
> will probably not seen at all,

You would only ever need to see it in specific situations.

Furthermore, screens are at least 80x24 ( more these days, I guess) so
we can usually fit the entire documentation on one screen.

> then I don't think that could be the default, either.  Just changing
> the order, so that non-menu bindings are shown first, is okay, I
> think.

That's already the case, AFAICT.  But I might be wrong: I never look at
that line, as I always found it too noisy to read comfortably.

I suspect for many users, that line will be worse than useless, as it is
hardly immediately clear what e.g. "<menu-bar> <help-menu> <describe>
<describe-function>" is even supposed to mean.  It looks like
line-noise.

BTW, it is even worse for describe-function:

    describe-function is an autoloaded interactive compiled Lisp function in
    ‘help-fns.el’.

    It is bound to <menu-bar> <help-menu> <describe> <describe-function>.

We don't even get to see `C-h f' here.

> But banishing that to after the version where the command was
> introduced doesn't sound like something I could agree to by default.

What is your rationale for this?  Is it easier to accept if it is before
the "Probably introduced" line?

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Drew Adams]

It ain't broke.  Please don't "fix" it.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 29 Dec 2021 12:19:32 -0800
> Cc: 52870@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > If by b) you mean to push the menu binding to the very end, where it
> > will probably not seen at all,
> 
> You would only ever need to see it in specific situations.

You assume that people don't have any use for these bindings, but that
is not necessarily so.

> Furthermore, screens are at least 80x24 ( more these days, I guess) so
> we can usually fit the entire documentation on one screen.

I don't see how the screen size is relevant.  The Help window can be a
small window, and users (like me) sometimes limit them in their
maximum size.  So the last part can well be invisible unless one
scrolls the window to the end.

> I suspect for many users, that line will be worse than useless, as it is
> hardly immediately clear what e.g. "<menu-bar> <help-menu> <describe>
> <describe-function>" is even supposed to mean.  It looks like
> line-noise.

That is not a catastrophe.  By contrast, _not_ seeing that information
could be a catastrophe, in that the user may not be aware of the
menu-bar binding.

> BTW, it is even worse for describe-function:
> 
>     describe-function is an autoloaded interactive compiled Lisp function in
>     ‘help-fns.el’.
> 
>     It is bound to <menu-bar> <help-menu> <describe> <describe-function>.
> 
> We don't even get to see `C-h f' here.

That's an issue I'd like us to fix, but it is not directly related to
what we are discussing here.  (And I cannot reproduce this on my
system, FWIW: I do see "C-h f" and "F1 f".)  There's no argument that
keyboard bindings should be shown when they exist.

However, I could turn the table and ask you whether you think it's
reasonable to put the menu-bar bindings at the end for functions that
have no other bindings but the menu-bar?  If you do that, the user
could think the command has no binding at all, until and unless he/she
reads all the way to the end of the Help text.

> > But banishing that to after the version where the command was
> > introduced doesn't sound like something I could agree to by default.
> 
> What is your rationale for this?  Is it easier to accept if it is before
> the "Probably introduced" line?

The rationale is that hardly anyone ever looks at the "Probably
introduced" line.  Before it is slightly better, but not good enough:
some doc strings are very long, so the menu-bar bindings will be
pushed too far.

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Drew Adams]

+1 to all that Eli said.
___

It may come down to this: Some people might not
find this or that standard part of *Help* text
to be important, or even helpful.  Other people
might find that same part to be helpful.
___

If the problem is that some people are annoyed
by seeing info they think isn't useful/helpful,
then a possible answer is to add the ability
for users to customize some of the parts, to
keep or remove them.

I suggested (and provided code for) the same
thing for `report-emacs-bug': letting a user
decide which automatically gathered info to
include.

Perhaps Stefan K would like to do something
similar for the standard parts of *Help*
output.  IOW, instead of imposing a personal
preference on Emacs in general, give users a
way to customize the parts they do or don't
want to include.  (And leave the default
behavior as is.)

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> What is your rationale for this?  Is it easier to accept if it is before
>> the "Probably introduced" line?
>
> The rationale is that hardly anyone ever looks at the "Probably
> introduced" line.  Before it is slightly better, but not good enough:
> some doc strings are very long, so the menu-bar bindings will be
> pushed too far.

I think saying explictly

  It can be invoked from the menu: "Help Menu" -> "Describe..."

is a lot clearer (and helpful) for users than the current

It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
<describe-function>.

Perhaps keeping it grouped with the binding info would be good, though.
So:

It is bound to C-h f and <help> f
It can also be invoked from the menu: "Help Menu" -> "Describe" ...

or something like that?

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

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Stefan Kangas <stefan@marxist.se>,  52870@debbugs.gnu.org
> Date: Sat, 15 Jan 2022 11:09:58 +0100
> 
> Perhaps keeping it grouped with the binding info would be good, though.
> So:
> 
> It is bound to C-h f and <help> f
> It can also be invoked from the menu: "Help Menu" -> "Describe" ...
> 
> or something like that?

If you mean to have them one after the other, like shown above, I'm
okay with that.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> It is bound to C-h f and <help> f
>> It can also be invoked from the menu: "Help Menu" -> "Describe" ...
>> 
>> or something like that?
>
> If you mean to have them one after the other, like shown above, I'm
> okay with that.

I've now almost implemented this.  I'm trying to find something that
maps

[menu-bar help-menu describe describe-function]

to "Help" -> "Describe" -> "Describe Function"

but I'm not finding anything.  I looked at the tmm code, and it does a
lot of tedious keymap traversing to do its stuff, but then again, it's
more extensive.

Do we have a function somewhere that maps key strokes to menu names?

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

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> The rationale is that hardly anyone ever looks at the "Probably
>> introduced" line.  Before it is slightly better, but not good enough:
>> some doc strings are very long, so the menu-bar bindings will be
>> pushed too far.

FWIW, I disagree that putting it at the end "pushes it too far".
Most docstrings can fit on a single screen so users will quickly learn
where to find it.

> Perhaps keeping it grouped with the binding info would be good, though.
> So:
>
> It is bound to C-h f and <help> f
> It can also be invoked from the menu: "Help Menu" -> "Describe" ...
>
> or something like that?

Sounds good to me.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

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

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> What is your rationale for this?  Is it easier to accept if it is before
>>> the "Probably introduced" line?
>>
>> The rationale is that hardly anyone ever looks at the "Probably
>> introduced" line.  Before it is slightly better, but not good enough:
>> some doc strings are very long, so the menu-bar bindings will be
>> pushed too far.
>
> I think saying explictly
>
>   It can be invoked from the menu: "Help Menu" -> "Describe..."
>
> is a lot clearer (and helpful) for users than the current
>
> It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
> <describe-function>.
>
> Perhaps keeping it grouped with the binding info would be good, though.
> So:
>
> It is bound to C-h f and <help> f
> It can also be invoked from the menu: "Help Menu" -> "Describe" ...
>
> or something like that?

FWIW I think it would be a good idea to do something like this:

  It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
  <describe-function> (which means it can be invoked from the menu:
  "Help Menu" -> "Describe" ...).

Though I don't think I got the wording completely right there.

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Drew Adams]

> FWIW I think it would be a good idea to do something like this:
> 
>   It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
>   <describe-function> (which means it can be invoked from the menu:
>   "Help Menu" -> "Describe" ...).

That too is reasonable.

Don't lose what we have now.  If you want to _add_
info to say which menu it's in (as you suggested),
that's reasonable.

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> FWIW I think it would be a good idea to do something like this:
>>
>>   It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
>>   <describe-function> (which means it can be invoked from the menu:
>>   "Help Menu" -> "Describe" ...).

IMO, that would be a step backwards.  This bug report started out with
me saying that this information is already confusing and distracting,
and this would make it even more so.

I don't think we should pretend that menu items are key bindings, because they
are not.  That is just an implementation detail.  Our user manual correctly
contrasts the two:

    "Each Emacs frame normally has a 'menu bar' at the top which you can use
    to perform common operations ...

       "On a display that supports a mouse, you can use the mouse to choose a
    command from the menu bar ...

       "Some of the commands in the menu bar have ordinary key bindings as
    well; if so, a key binding is shown after the item itself."

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Drew Adams]

> Drew Adams <drew.adams@oracle.com> writes:
> 
> >> FWIW I think it would be a good idea to do something like this:
> >>
> >>   It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
> >>   <describe-function> (which means it can be invoked from the menu:
> >>   "Help Menu" -> "Describe" ...).

You give the impression that Drew Adams said
what you quoted.  A careful reader might
notice that the quoted text is not from me;
others might not.  Why do that?

> IMO, that would be a step backwards.  This bug report started out with
> me saying that this information is already confusing and distracting,
> and this would make it even more so.

Why would providing additional information
about where that menu command can be found
in the menu be confusing?

To be clear, as I said, no change is needed.
Nothing is broken, confusing, or distracting.

But if someone wants to add more info, that's
OK too.

> I don't think we should pretend that menu items are key bindings, because
> they are not.

They certainly are - for Emacs.  Always have
been, ever since we've had menus.

> That is just an implementation detail.

No, it's not.  It's the way Emacs itself
talks about menu-item key bindings. 

> Our user manual correctly contrasts the two:
> 
>     "Each Emacs frame normally has a 'menu bar' at the top which you can use
>     to perform common operations ...
> 
>        "On a display that supports a mouse, you can use the mouse to choose
> a
>     command from the menu bar ...
> 
>        "Some of the commands in the menu bar have ordinary key bindings as
>     well; if so, a key binding is shown after the item itself."

Nothing there contradicts Emacs's treatment
everywhere of these as key bindings.  Yes,
that last sentence would be clearer if it
said "keyboard key bindings" instead of
"ordinary key bindings".

"Keyboard key bindings" is _very_ clear.
"Ordinary" means nothing here - that wording
is a bug.

Is a function-key binding an "ordinary" key
binding?  What about a function-key that's
not associated with a physical keyboard key?

Please don't try to change the longstanding
and very clear Emacs nomenclature about key
bindings.

Is the _text_ of a menu item the same as the
menu item?  If so, then your uses of "menu
item" above are incorrect - the text is not
bound.  But if not, then yes, menu items are
key bindings.  They're bound in a menu keymap.

And yes, it's important that Emacs itself,
when it speaks to users, use the same terms
as when it talks about Elisp entities.  Emacs
users are very often Elisp users.

And Elisp and its entities are not just
"implementation details".  Far from it, thank
goodness.

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Drew Adams]

> I think saying explictly
>   It can be invoked from the menu: "Help Menu" -> "Describe..."
> is a lot clearer (and helpful) for users than the current
>   It is bound to C-h f, <help> f, <menu-bar> <help-menu> <describe>
>   <describe-function>.

No, it's not.  It doesn't tell you the key binding
(the menu it's in isn't the same thing).  And it
tells you nothing about how to find out more about
that binding or to do something with its menu.

This ain't broke.  Please don't fix it.

bug#52870: [External] : bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Drew Adams]

> For example, in Dired, I type `C-h f dired-do-chmod RET' and read:
> 
>     It is bound to M, <menu-bar> <operate> <Change Mode...>.

I don't see that in Emacs 22 through the latest
release (Emacs 27.2).  It was likely introduced
in Emacs 21.

Perhaps someone has changed it for Emacs 28/29?
If so, why?

This is what I see:

 It is bound to M, <menu-bar> <operate> <chmod>.
                                        ^^^^^^^

Why change the name of the (pseudo-)function
key to be that of a menu item (including `...'
no less)?  Then, if that menu-item name changes
are you going to change the name of the key,
and thus break code that refers to the previous
name?  (Apparently such breakage is already in
progress for Emacs 28/29, by replacing <chmod>.)

> Is the "<menu-bar> ..." part there very useful?  I personally find it
> confusing and distracting.  This is true even when I am specifically
> developing menus; I'd rather look at the menu definition and the
> resulting menu bar.

What is it that you're confused about?

Yes, it's useful.  It's important to show all of
the bindings.  Ignore it if it doesn't interest you.

> I would therefore like to suggest either:
> 
> a) Displaying nothing at all for such bindings.  The menu entries will
>    be shown in the menu itself, and that is enough.

No, it's not enough.

This is about help (`C-h...').  It's about seeing
the bindings together with the doc for the command.

>    In this case, we could have an option to revert to the old behavior.

The proposed "new" behavior has no reason to be
adopted (apart from your being confused and
distracted by it).  What's the need/purpose?
Just to remove helpful information that you're
not interested in?

Why do you suppose that that info was added to
this help output - for no reason?  Or just to
confuse and distract?

> b) Show it separately from other key bindings at the end,

Why?  These bindings are bindings, like the others.
They're neither more nor less important.  Why split
the locations?

And why wouldn't we want to show (all) the key
bindings up front.  For a command, showing key
bindings is super-helpful, succinct info.

>   maybe something like this:
> 
>   Probably introduced at or before Emacs version 24.3.
>   It can be invoked from the menu: "Operate" -> "Change Mode..."

Absolutely not.  It's not about the menu-item text.
It's about the _key sequence_: what Emacs itself
calls that sequence - how Emacs itself talks about
such keys.

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

>   It can be invoked from the menu: "Operate" -> "Change Mode..."

I previously implemented the split-up logic, but didn't output the menu
item names.  I've now also implemented this in Emacs 29.

Some tweaking of the display (or what faces to use here) is probably
necessary.

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

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Juri Linkov]

> Some tweaking of the display (or what faces to use here) is probably
> necessary.

It fails on 'C-h f vc-diff', and I have no idea how to fix this.

  Debugger entered--Lisp error: (wrong-type-argument listp vc-menu-map)
    ...
    help-fns--insert-menu-bindings(([menu-bar tools vc vc-diff]) "It can also be invoked from the menu: ")
    help-fns--key-bindings(vc-diff)
    describe-function-1(vc-diff)
    describe-function(vc-diff)

bug#52870: Is displaying <menu-bar> bindings in describe-function useful?

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> It fails on 'C-h f vc-diff', and I have no idea how to fix this.
>
>   Debugger entered--Lisp error: (wrong-type-argument listp vc-menu-map)
>     ...
>     help-fns--insert-menu-bindings(([menu-bar tools vc vc-diff]) "It can also be invoked from the menu: ")
>     help-fns--key-bindings(vc-diff)
>     describe-function-1(vc-diff)
>     describe-function(vc-diff)

Yup; now fixed.

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