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

[JD Smith <jdtsmith@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3792 bytes --]



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

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. 


[-- Attachment #2: Type: text/html, Size: 20149 bytes --]