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