[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Improving describe-mode and discoverability

From: Clément Pit--Claudel
Subject: Improving describe-mode and discoverability
Date: Thu, 23 Jun 2016 14:29:00 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.8.0

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 

    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 

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


Attachment: shell-script-mode-help
Description: Text document

Attachment: elisp-mode-help
Description: Text document

Attachment: python-mode-help
Description: Text document

Attachment: rst-mode-help
Description: Text document

Attachment: c-mode-help
Description: Text document

Attachment: shell-mode-help
Description: Text document

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

Attachment: signature.asc
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]