Next: Describing Characters, Previous: Accessing Documentation, Up: Documentation [Contents][Index]
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 value of mapvar, which should be a
keymap. The summary is made by describe-bindings
.
\<mapvar>
stands for no text itself. It is used for a side effect: it specifies mapvar as the keymap for any following ‘\[command]’ sequences in this documentation string.
\=
quotes the following character and is discarded; this ‘\=\=’ puts ‘\=’ into the output, and ‘\=\[’ puts ‘\[’ into the output.
Please note: Each ‘\’ must be doubled when written in a string in SXEmacs Lisp.
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 LFD 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."
(substitute-command-keys "Substrings of the form \\=\\{MAPVAR} are replaced by summaries \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR as the keymap for future \\=\\[COMMAND] substrings. \\=\\= quotes the following character and is discarded; thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.") ⇒ "Substrings of the form \{MAPVAR} are replaced by summaries (made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \<MAPVAR> specify to use the value of MAPVAR as the keymap for future \[COMMAND] substrings. \= quotes the following character and is discarded; thus, \=\= puts \= into the output, and \=\[ puts \[ into the output."
Next: Describing Characters, Previous: Accessing Documentation, Up: Documentation [Contents][Index]