3.5.12 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

Function: substitute-command-keys string ¶

Substitute key descriptions for command names in ‘STRING’.

‘\[COMMAND]’

Each substring of the form ‘\[COMMAND]’ is replaced by either a keystroke sequence that invokes ‘COMMAND’, or ‘M-x COMMAND’ if ‘COMMAND’ is not on any keys.

‘\{MAPVAR}’

Each substring of the form ‘\{MAPVAR}’ is replaced by a summary of the value of ‘MAPVAR’ as a keymap.

‘\<MAPVAR>’

Each substring of the form ‘\<MAPVAR>’ specifies the use of ‘MAPVAR’ as the keymap for future ‘\[COMMAND]’ substrings.

grave accent ‘`’

Each is replaced by left quote;

apostrophe ‘'’

Each is replaced by right quote;

‘\=’

quotes the following character and is discarded

RETURN

Returns the original ‘STRING’ if no substitutions are made. Otherwise, return a new string (without any text properties).

Examples of substitute-command-keys

(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
;; "

(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’."