Displaying bindings for prefix keymaps

Question

I have a tree of deeply nested keymaps, with many possible leaves (commands), too many for a human to remember. For simplicity, let's say each command is associated with a given file name.

I would like to display a help tool-tip as the user is walking down these keymaps, indicating which files/commands are bound to which keys.

So, I would like to associate with certain keymaps a short documentation, and display it whenever the user is "on" the keymap (perhaps using help-fns+.el or some other custom docstring).

What is the best way of doing this?

Answer 1

This sounds like exactly what the which-key package does. When you type a prefix key, after a short pause, a list of keys in the keymap and the commands they are bound to is shown in a side window. It's great for things you don't quit do often enough to have memorized.

Install it with package-install which-key and activate it with (which-key-mode).

Answer 2

There is an underused built-in functionality with a similar aim.

You can see it in action by doing: M-x smerg-mode RET and then C-c ^ = which should immediately show you the possible options in that prefix keymap, along the lines of

Diff: = = mine-other, > = base-other, < = base-mine

Being underused it's also rather primitive (the confusion between the = key and the = sign is rather annoying in the above example). To get this, the main part of the code was (transliterated from the use of easy-mmode-defmap):

(define-key map [?=] (make-sparse-keymap "Diff")
(define-key map [?= ?<] '("base-mine" . smerge-diff-base-mine))
(define-key map [?= ?>] '("base-other" . smerge-diff-base-other))
(define-key map [?= ?=] '("mine-other" . smerge-diff-mine-other))

Answer 3

1. Not sure I understand the question, but it sounds like Icicles key completion will help.

   When you have hit a prefix key (e.g. C-x or C-x 4), if you hit S-TAB (by default) all of the bindings on that prefix key are displayed in buffer *Completions* along with the commands they are bound to. You can explore them (showing complete descriptions on demand or short descriptions just by cycling among them) -- and hit C-g if you don't want to invoke any of them. Or you can complete any of them and invoke it.

   This works also for prefix keys that are on prefix keys, such as C-x 4, which is in C-x. If you hit C-x S-TAB then one of the candidates you see in *Completions* is 4 = .... The ... here means that 4 is itself a prefix key. If you choose that candidate then *Completions* is changed to show you the keys (and commands) bound on C-x 4.

   You can also navigate upward in the keymap hierarchy. The first candidate in *Completions* for a prefix keymap is ... Choosing that candidate moves you back up to the parent keymap.

2. There is another library, guide-key, which some of what Icicles key completion does, if you are not interested in using Icicles in general.

3. Without Icicles or guide-key, you can at least use C-h with vanilla Emacs to get a listing (in *Help*) of the keys bound on a prefix key. For example, C-x C-h shows you the keys bound on prefix key C-x.