On Jan 5, 2024, at 3:40 AM, Eli Zaretskii <eliz@gnu.org> wrote:
From: JD Smith <jdtsmith@gmail.com>
Date: Thu, 4 Jan 2024 20:28:27 -0500
Cc: 68236@debbugs.gnu.org
On Jan 4, 2024, at 8:57 AM, Eli Zaretskii <eliz@gnu.org> wrote:
If we are going to expose help-quick-sections as a defcustom, then I
don't understand why we need to change the code at all. Is the idea
that sections will depend on the current buffer? If so, then we just
need to add an element to the list members which will store the
major-mode for which the member is relevant.
Or what am I missing?
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 abuffer under some major mode to see the entries for that mode in thequick-help window. It could be an annoyance; e.g., consider a userwho wants to see this while in a *Help* buffer. And I don't thinkbeing in the buffer under the major mode is the only way of gettingmode-specific bindings; for example, where-is-internal can accept aKEYMAP argument, which will be used to find key bindings.
The current disadvantage is related, but much worse than this: you currently cannot configure quick help to show any bindings other than global and help-mode bindings. It might be nice to see e.g. org-bindings from anywhere, but to me it’s an advantage to show “quick help for this mode”.
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.
I’d probably disable most of the global bindings, since I already know those. But some are useful (e.g. I often forget the project bindings).
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.)
Agree, this is a real problem for discoverability. Also command names are not always informative enough to find what you are actually looking for (org is terrible for this).
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 do like this idea. Perhaps mode authors could add a “starter pack” of this information themselves, if they are suitably admonished to keep this information brief, high level, and with clear few-word command descriptions. Perhaps adding a ‘help-quick property to the mode command symbol?
One guiding principle I suggest: users in the end should be able to decide what quick help they need; what’s memorable for some may be frequently forgotten for others.