1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
|
<h3 class="section">Substituting Key Bindings in Documentation</h3> <p>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 <code>substitute-command-keys</code>. You can also call that function yourself. </p> <p>Here is a list of the special sequences and what they mean: </p> <dl compact> <dt><code>\[<var>command</var>]</code></dt> <dd>
<p>stands for a key sequence that will invoke <var>command</var>, or ‘<samp>M-x <var>command</var></samp>’ if <var>command</var> has no key bindings. </p> </dd> <dt><code>\{<var>mapvar</var>}</code></dt> <dd>
<p>stands for a summary of the keymap which is the value of the variable <var>mapvar</var>. The summary is made using <code>describe-bindings</code>. </p> </dd> <dt><code>\<<var>mapvar</var>></code></dt> <dd>
<p>stands for no text itself. It is used only for a side effect: it specifies <var>mapvar</var>’s value as the keymap for any following ‘<samp>\[<var>command</var>]</samp>’ sequences in this documentation string. </p> </dd> <dt><code>`</code></dt> <dd>
<p>(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 <code>text-quoting-style</code>. See <a href="text-quoting-style">Text Quoting Style</a>. </p> </dd> <dt><code>'</code></dt> <dd>
<p>(apostrophe) stands for a right quote. This generates a right single quotation mark or an apostrophe depending on the value of <code>text-quoting-style</code>. </p> </dd> <dt><code>\=</code></dt> <dd><p>quotes the following character and is discarded; thus, ‘<samp>\=`</samp>’ puts ‘<samp>`</samp>’ into the output, ‘<samp>\=\[</samp>’ puts ‘<samp>\[</samp>’ into the output, and ‘<samp>\=\=</samp>’ puts ‘<samp>\=</samp>’ into the output. </p></dd> </dl> <p><strong>Please note:</strong> Each ‘<samp>\</samp>’ must be doubled when written in a string in Emacs Lisp. </p> <dl> <dt id="text-quoting-style">User Option: <strong>text-quoting-style</strong>
</dt> <dd>
<p>The value of this variable is a symbol that specifies the style Emacs should use for single quotes in the wording of help and messages. If the variable’s value is <code>curve</code>, the style is <tt>‘like this’</tt> with curved single quotes. If the value is <code>straight</code>, the style is <tt>'like this'</tt> with straight apostrophes. If the value is <code>grave</code>, quotes are not translated and the style is <tt>`like this'</tt> with grave accent and apostrophe, the standard style before Emacs version 25. The default value <code>nil</code> acts like <code>curve</code> if curved single quotes seem to be displayable, and like <code>grave</code> otherwise. </p> <p>This option is useful on platforms that have problems with curved quotes. You can customize it freely according to your personal preference. </p>
</dd>
</dl> <dl> <dt id="substitute-command-keys">Function: <strong>substitute-command-keys</strong> <em>string &optional no-face</em>
</dt> <dd>
<p>This function scans <var>string</var> 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 <code>help-key-binding</code>, but if the optional argument <var>no-face</var> is non-<code>nil</code>, the function doesn’t add this face to the produced string. </p> <p>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 <code>:advertised-binding</code> symbol property to the command, like this: </p> <div class="example"> <pre class="example">(put 'undo :advertised-binding [?\C-/])
</pre>
</div> <p>The <code>:advertised-binding</code> property also affects the binding shown in menu items (see <a href="menu-bar">Menu Bar</a>). The property is ignored if it specifies a key binding that the command does not actually have. </p>
</dd>
</dl> <p>Here are examples of the special sequences: </p> <div class="example"> <pre class="example">(substitute-command-keys
"To abort recursive edit, type `\\[abort-recursive-edit]'.")
⇒ "To abort recursive edit, type ‘C-]’."
</pre>
<pre class="example">(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:
</pre>
<pre class="example">
? 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
"
</pre>
<pre class="example">(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’."
</pre>
</div> <p>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 <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html">Documentation Tips</a>, for details. </p><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Keys-in-Documentation.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Keys-in-Documentation.html</a>
</p>
</div>
|
