25.3 Substituting Key Bindings in Documentation

When documentation strings refer to key sequences, they should use the current, actual key bindings. They can do so using certain special text sequences described below. Accessing documentation strings in the usual way substitutes current key binding information for these special sequences. This works by calling substitute-command-keys. You can also call that function yourself.

Here is a list of the special sequences and what they mean:

\[command]

stands for a key sequence that will invoke command, or ‘M-x command’ if command has no key bindings.

\{mapvar}

stands for a summary of the keymap which is the value of the variable mapvar. The summary is made using describe-bindings.

\<mapvar>

stands for no text itself. It is used only for a side effect: it specifies mapvar’s value as the keymap for any following ‘\[command]’ sequences in this documentation string.

\`KEYSEQ'

stands for a key sequence KEYSEQ, which will use the same face as a command substitution. This should be used only when a key sequence has no corresponding command, for example when it is read directly with read-key-sequence. It must be a valid key sequence according to key-valid-p. It can also be used with command names, like ‘\`M-x foo'’, where you want this to be fontified like a keyboard sequence, but you want to inhibit translating it into a key sequence like ‘\[foo]’ does.

`

(grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave accent depending on the value of text-quoting-style. See Text Quoting Style.

'

(apostrophe) stands for a right quote. This generates a right single quotation mark or an apostrophe depending on the value of text-quoting-style.

\=

quotes the following character and is discarded; thus, ‘\=`’ puts ‘`’ into the output, ‘\=\[’ puts ‘\[’ into the output, and ‘\=\=’ puts ‘\=’ into the output.

\+

This indicates that the symbol directly following should not be marked as link in the *Help* buffer.

Please note: Each ‘\’ must be doubled when written in a string in Emacs Lisp.

Function: substitute-command-keys string &optional no-face include-menus ¶

This function scans string for the above special sequences and replaces them by what they stand for, returning the result as a string. This permits display of documentation that refers accurately to the user’s own customized key bindings. By default, the key bindings are given a special face help-key-binding, but if the optional argument no-face is non-nil, the function doesn’t add this face to the produced string.

Function: substitute-quotes string ¶

This function works like substitute-command-keys, but only replaces quote characters.

If a command has multiple bindings, this function normally uses the first one it finds. You can specify one particular key binding by assigning an :advertised-binding symbol property to the command, like this:

(put 'undo :advertised-binding [?\C-/])

The :advertised-binding property also affects the binding shown in menu items (see The Menu Bar). The property is ignored if it specifies a key binding that the command does not actually have.

Here are examples of the special sequences:

(substitute-command-keys
   "To abort recursive edit, type `\\[abort-recursive-edit]'.")
⇒ "To abort recursive edit, type ‘C-]’."

(substitute-command-keys
   "The keys that are defined for the minibuffer here are:
  \\{minibuffer-local-must-match-map}")
⇒ "The keys that are defined for the minibuffer here are:

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

The keymap description will normally exclude menu items, but if
include-menus is non-nil, include them.

(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type \
`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
⇒ "To abort a recursive edit from the minibuffer, type ‘C-g’."

There are other special conventions for the text in documentation strings—for instance, you can refer to functions, variables, and sections of this manual. See Tips for Documentation Strings, for details.