Subject: bug#68236: [PATCH] help.el: allow help-quick to use local commands/quick-sections

From: Stefan Kangas <[email-masked]>
Date: Wed, 10 Jan 2024 04:51:48 -0800

Eli Zaretskii <[email-masked]> writes:

>> Right now the code does
>>
>>   (with-current-buffer (get-buffer-create "*Quick Help*")
>>
>> right away, then checks `where-is-internal' for each listed command
>> in `help-quick-sections'.  So only global bindings (and bindings
>> available in help-mode) are accessible for display.  My patch simply
>> delays switching to *Quick Help* buffer, so that binding information
>> can be gathered from the local buffer from which quick help was
>> summoned.  Note that help-quick omits any bindings that are nil, as
>> well as any empty sections.  So adding sections to the defcustom that
>> do not apply (=have no bindings) in some buffer is not a problem.
>
> Your proposal has the disadvantage that the user must switch to a
> buffer under some major mode to see the entries for that mode in the
> quick-help window.  It could be an annoyance; e.g., consider a user
> who wants to see this while in a *Help* buffer.  And I don't think
> being in the buffer under the major mode is the only way of getting
> mode-specific bindings; for example, where-is-internal can accept a
> KEYMAP argument, which will be used to find key bindings.

Yes, this is a problem.  I see the quick help as basically intended for
global Emacs keys, so I think they should display the global ones
always.  Let's not break that.

> Or maybe we should have a separate command for cheat sheets specific
> to a major mode.  The window we pop up cannot be too large, so if the
> user only wants a quick help for the current mode, she might consider
> global bindings an annoying waste of screen estate.  Moreover, the
> current quick help shows "popular commands", which are likely to be
> already known to some users, whereas when the user works in a major
> mode that is new to the user, one is likely to be in the need of the
> cheat sheet for that one mode.  (Yes, we do already have "C-h b", but
> the output of that could be overwhelming: for example in an Org buffer
> I get almost 1400 lines in the *Help* buffer showing the Org-specific
> bindings.)
>
> IOW, if we want to consider mode-specific quick help, we should
> perhaps discuss more about the goals before we consider code tricks to
> implement it.

I think a more specific cheat sheet for major modes would be more
suitable, yes.

Here's an idea that I've had:

Typically, I only want to remember a few commands in each major mode.
It would be useful to be able to mark them for highlighting or somesuch
in the general describe-mode *Help* buffer (preferably using keys, and
not using M-x customize, though they could persist by saving the result
to the custom file).  Then, the next time I display `describe-mode',
they would be highlighted, in this or future sessions.  How about
something like that?

We could also add a separate command to show only those commands somehow
in a similar way to `help-quick-toggle'.