当文档字符串引用按键序列时,应使用当前实际生效的按键绑定。可以通过下文描述的若干特殊文本序列实现这一点。以常规方式访问文档字符串时,会将这些特殊序列替换为当前的按键绑定信息,这一过程通过调用 substitute-command-keys 完成。你也可以直接调用该函数。
以下是特殊序列及其含义的列表:
\[command]表示可调用 command 的按键序列;若该命令无绑定按键,则显示为 ‘M-x command’。
\{mapvar}表示变量 mapvar 的值所对应的按键映射概览。该概览由 describe-bindings 生成。
概览通常不包含菜单绑定,但若 substitute-command-keys 的 include-menus 参数非 nil,则会包含菜单绑定。
\<mapvar>本身不输出任何文本,仅产生副作用:将本文档字符串中后续所有 ‘\[command]’ 序列所使用的按键映射指定为 mapvar 的值。
\`KEYSEQ'表示按键序列 KEYSEQ,显示面孔与命令替换结果一致。该序列仅应在按键序列无对应命令时使用,例如通过 read-key-sequence 直接读取的按键。其必须是符合 key-valid-p 的合法按键序列。也可用于命令名,如 ‘\`M-x foo'’,使其以按键序列样式高亮,但不执行 ‘\[foo]’ 那样的按键翻译。
`(反引号)表示左引号。
根据 text-quoting-style 的值,会生成左单引号、撇号或反引号。
See 文本引用样式。
'(撇号)表示右引号。
根据 text-quoting-style 的值,会生成右单引号或撇号。
\=对其后字符进行转义并自身被忽略;因此 ‘\=`’ 输出 ‘`’,‘\=\[’ 输出 ‘\[’,‘\=\=’ 输出 ‘\=’。
\+表示紧随其后的符号在 *Help* 框架中不应标记为链接。
请注意:在 Emacs Lisp 字符串中书写时,每个 ‘\’ 都必须写成两个(see 字符串语法)。
该函数扫描 string 中的上述特殊序列并将其替换为对应内容,以字符串形式返回结果。这使得文档可以准确显示用户自定义后的按键绑定。默认情况下,按键绑定会使用特殊面孔 help-key-binding;若可选参数 no-face 非 nil,则不会为结果字符串添加该面孔。
若一个命令有多个绑定,该函数通常使用找到的第一个。你可以为命令指定 :advertised-binding 符号属性来指定优先显示的绑定,示例如下:
(put 'undo :advertised-binding [?\C-/])
:advertised-binding 属性也会影响菜单项中显示的绑定(see 菜单栏)。若该属性指定的按键并非该命令实际拥有的绑定,则会被忽略。
以下是特殊序列的使用示例:
(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
"
按键映射描述通常不包含菜单项,但若 include-menus 非 nil,则会包含。
(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 类似,但仅替换引号字符。
文档字符串中的文本还有其他特殊约定—例如可以引用本手册中的函数、变量与章节。详情参见 See Tips for Documentation Strings。