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

[Eli Zaretskii <eliz@gnu.org>]

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