Re: describe-mode bindings (was: [ELPA] New package: disk-usage)

[Clément Pit-Claudel]

On 19/02/2019 15.58, Stefan Monnier wrote:
>> Of course, and I did. But a menue is more convenient. 'C-h m' returns:
> [...]
>> --8<---------------cut here---------------end--------------->8---
>> A longer list than needed; the relevant keys must be found.
> 
> Maybe `C-h m` should be improved to distinguish the mode's own bindings
> from the ones inherited from the parent keymap!?

An overhaul of C-h m would be nice.  In biblio.el I list the docstrings along 
with the commands, so h gives this:

    Help with ‘biblio-selection-mode’

    ‘C-p’, ‘<up>’ (biblio--selection-previous)
      Move to previous search result.

    ‘C-n’, ‘<down>’ (biblio--selection-next)
      Move to next search result.

    ‘RET’ (biblio--selection-browse)
      Open the web page of the current entry in a web browser.

    ‘C-RET’, ‘<C-return>’ (biblio--selection-browse-direct)
      Open the full text of the current entry in a web browser.

    ‘c’, ‘M-w’ (biblio--selection-copy)
      Copy BibTeX of current entry at point.

    ‘C’, ‘C-w’ (biblio--selection-copy-quit)
      Copy BibTeX of current entry at point and close results.
    
    … etc.

… while C-h m gives this:

    Bibliographic search results (→ magit: mpd) mode defined in 
‘biblio-core.el’:
    Browse bibliographic search results.
    key             binding
    ---             -------

    RET             biblio--selection-browse
    C-n             biblio--selection-next
    C-p             biblio--selection-previous
    C-w             biblio--selection-copy-quit
    C-y             biblio--selection-insert-quit
    ESC             Prefix Command
    ?               biblio--selection-help
    C               biblio--selection-copy-quit
    I               biblio--selection-insert-quit
    b               biblio--selection-change-buffer
    c               biblio--selection-copy
    h               biblio--selection-help
    i               biblio--selection-insert
    q               quit-window
    x               biblio--selection-extended-action
    C-RET           biblio--selection-browse-direct
    <C-return>      biblio--selection-browse-direct
      (that binding is currently shadowed by another mode)
    <down>          biblio--selection-next
    <up>            biblio--selection-previous

    M-w             biblio--selection-copy