GNU Info

(elisp)Keys in Documentation

---

Next: Describing Characters Prev: Accessing Documentation Up: Documentation

---

Enter node , (file) or (file)node

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.

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

   *Please note:* Each `\' must be doubled when written in a string in
Emacs Lisp.

 - Function: substitute-command-keys string
     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.

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