Ideas to improve the output of C-h m?

[Clément Pit-Claudel]

Hi all,

A while ago I tried to improve the discoverability of the keybindings of one of 
my packages by writing an enhanced version of the keybindings part of C-h m.  
The idea was to list keybindings along with the first line of their docstrings, 
instead of just listing the name of the function.

I have pasted at the botom of this email the output of the current C-h m and 
the output of the code I wrote a while ago.  Here's how it looks for a single 
entry, to see the difference (note that unlike C-h m, it currently groups 
keybindings that map to the same command):

Current output:
  h               describe-mode
  …
  ?               describe-mode

In biblio.el:
  ‘h’, ‘?’ (describe-mode)
    Display documentation of current major mode and minor modes.

Is there interest in integrating something like this to the usual C-h m? I'm 
not thinking of replacing the existing code with the one I wrote; rather, I'm 
wondering if some of its ideas could be used to improve C-h m, by adjusting the 
layout slightly and inserting (maybe only when a user-customizable option is 
set?) the first line of each docstring (possibly with a button to expand the 
full docstring?).

Or maybe there's a better way to display this information? (one thing I did in 
that package was to use the order of bindings as defined in the keymap, while 
C-h m sorts the keybindings alphabetically; the idea was to give control to 
package developers over the order of the keybindings)

Cheers,
Clément.

    key             binding
    ---             -------

    C-c         Prefix Command
    ESC         Prefix Command

    C-c C-a             outline-show-all
    C-c C-b             outline-backward-same-level
    C-c C-c             outline-hide-entry
    C-c C-d             outline-hide-subtree
    C-c C-e             outline-show-entry
    C-c C-f             outline-forward-same-level
    C-c TAB             outline-show-children
    C-c C-k             outline-show-branches
    C-c C-l             outline-hide-leaves
    C-c RET             outline-insert-heading
    C-c C-n             outline-next-visible-heading
    C-c C-o             outline-hide-other
    C-c C-p             outline-previous-visible-heading
    C-c C-q             outline-hide-sublevels
    C-c C-s             outline-show-subtree
    C-c C-t             outline-hide-body
    C-c C-u             outline-up-heading
    C-c C-v             outline-move-subtree-down
    C-c C-^             outline-move-subtree-up
    C-c @               outline-mark-subtree
    C-c C-<             outline-promote
    C-c C->             outline-demote

After:

    Help with ‘outline-mode’

    ‘C-c @’ (outline-mark-subtree)
      Mark the current subtree in an outlined document.
    ‘C-c C-n’ (outline-next-visible-heading)
      Move to the next visible heading line.
    ‘C-c C-p’ (outline-previous-visible-heading)
      Move to the previous heading line.
    ‘C-c TAB’ (outline-show-children)
      Show all direct subheadings of this heading.
    ‘C-c C-s’ (outline-show-subtree)
      Show everything after this heading at deeper levels.
    ‘C-c C-d’ (outline-hide-subtree)
      Hide everything after this heading at deeper levels.
    ‘C-c C-u’ (outline-up-heading)
      Move to the visible heading line of which the present line is a 
subheading.
    ‘C-c C-f’ (outline-forward-same-level)
      Move forward to the ARG'th subheading at same level as this one.
    ‘C-c C-b’ (outline-backward-same-level)
      Move backward to the ARG'th subheading at same level as this one.
    ‘C-c C-t’ (outline-hide-body)
      Hide all body lines in buffer, leaving all headings visible.
    ‘C-c C-a’ (outline-show-all)
      Show all of the text in the buffer.
    ‘C-c C-c’ (outline-hide-entry)
      Hide the body directly following this heading.
    ‘C-c C-e’ (outline-show-entry)
      Show the body directly following this heading.
    ‘C-c C-l’ (outline-hide-leaves)
      Hide the body after this heading and at deeper levels.
    ‘C-c C-k’ (outline-show-branches)
      Show all subheadings of this heading, but not their bodies.
    ‘C-c C-q’ (outline-hide-sublevels)
      Hide everything but the top LEVELS levels of headers, in whole buffer.
    ‘C-c C-o’ (outline-hide-other)
      Hide everything except current body and parent and top-level headings.
    ‘C-c C-^’ (outline-move-subtree-up)
      Move the current subtree up past ARG headlines of the same level.
    ‘C-c C-v’ (outline-move-subtree-down)
      Move the current subtree down past ARG headlines of the same level.
    ‘C-c C-<’ (outline-promote)
      Promote headings higher up the tree.
    ‘C-c C->’ (outline-demote)
      Demote headings lower down the tree.
    ‘C-c RET’ (outline-insert-heading)
      Insert a new heading at same depth at point.

(in a real Emacs window, the function names and the keybindings are 
highlighted, and on graphical terminals there's a thin line between each entry).

signature.asc
Description: OpenPGP digital signature