Improving describe-mode and discoverability

[Clément Pit--Claudel]

Hey Emacs,

Among the many ways to get information about a package (READMEs, Commentaries, 
manuals, menu-bar menus, and describe-mode; are there others?), describe-mode 
is the only universally available one. It always works, but it's not very nice 
to use: it just gives you a list of function names and the associated bindings.

Recently I added an extra documentation feature to one of my packages, 
biblio.el.  It's a single function that walks a keymap, and displays for each 
binding not only the name of the associated function, but also the first line 
of the documentation of each function. Here's how it looks in haskell-mode:

    Help with ‘haskell-mode’

    ‘C-M-q’ (prog-indent-sexp)
      Indent the expression after point.

    ‘C-c C-c’ (haskell-compile)
      Compile the Haskell program including the current buffer.

    ‘C-c C-s’ (haskell-mode-toggle-scc-at-point)
      If point is in an SCC annotation, kill the annotation.  Otherwise, try to 
insert a new annotation.

    ‘C-c TAB’ (haskell-process-do-info)
      Print info on the identifier at point.

    ‘C-c C-t’ (haskell-process-do-type)
      Print the type of the given expression.

    ‘C-c C-v’ (haskell-mode-enable-process-minor-mode)
      Tell the user to choose a minor mode for process interaction.

    ‘C-c C-b’, ‘C-c C-z’ (haskell-interactive-switch)
      Switch to the interactive mode for this session.

    ‘C-c C-l’ (haskell-process-load-file)
      Load the current buffer file.

    ‘C-c C-.’ (haskell-mode-format-imports)
      Format the imports by aligning and sorting them.

    ‘<remap> <delete-indentation>’ (haskell-delete-indentation)
      Like `delete-indentation' but ignoring Bird-style ">".

It's not much, but I think it looks much better. I've attached examples of the 
output for several other modes to this email, as well as the code used to 
generate this example. Contrast with the default output of C-h m for 
haskell-mode:

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

    C-c             Prefix Command
    C-x             Prefix Command
    ESC             Prefix Command
    <remap>         Prefix Command

    <remap> <delete-indentation>    haskell-delete-indentation

    C-c C-b         haskell-interactive-switch
    C-c C-c         haskell-compile
    C-c TAB         haskell-process-do-info
    C-c C-l         haskell-process-load-file
    C-c C-s         haskell-mode-toggle-scc-at-point
    C-c C-t         haskell-process-do-type
    C-c C-v         haskell-mode-enable-process-minor-mode
    C-c C-z         haskell-interactive-switch
    C-c ESC         Prefix Command
    C-c C-.         haskell-mode-format-imports

    C-M-q           prog-indent-sexp

My implementation is rather brittle (I don't have sufficient knowledge of 
keymaps), but I think a documentation facility in the line of the one demoed 
above would be very useful.  Most interactive functions are already documented, 
so we'd be tapping into a large body of existing docs, making them more 
accessible.

What do you think? I would be happy to get help in refining this code (and this 
proposal). For example, we could consider hyperlinking the function names to 
their sources, or letting users expand the first line of the documentation to 
show the full docstring. We could also think about ways to cover functions that 
are not bound to a key by default, but which users may want to bind (e.g. by 
looking for interactive functions starting with the mode's name).

Cheers,
Clément.

shell-script-mode-help
Description: Text document

elisp-mode-help
Description: Text document

python-mode-help
Description: Text document

rst-mode-help
Description: Text document

c-mode-help
Description: Text document

shell-mode-help
Description: Text document

help-with-major-mode.el
Description: Text Data

signature.asc
Description: OpenPGP digital signature