Emacs 提供多种内置帮助函数,用户均可通过前缀键 C-h 的子命令访问。更多信息参见 Help in The GNU Emacs Manual。本节介绍用于访问相同信息的程序级接口。
该函数查找所有名称包含 apropos 模式 pattern 匹配内容的有效符号。apropos 模式可以是待匹配单词、至少匹配两个单词的空格分隔列表,或正则表达式(若出现正则表达式特殊字符)。符号为有效符号,当且仅当其具有函数、变量或面孔定义,或拥有属性。
函数返回元素格式如下的列表:
(symbol score function-doc variable-doc plist-doc widget-doc face-doc group-doc)
其中 score 为整数,表示该符号匹配的相关程度。其余各项分别为 symbol 作为函数、变量等的文档字符串或 nil。
该函数同时在名为 *Apropos* 的框架中显示符号,并从文档字符串开头提取一行作为简介。
若 do-all 非 nil,或用户选项 apropos-do-all 非 nil,则 apropos 还会显示找到函数的按键绑定,并显示**所有**已 intern 的符号而非仅有效符号(同时也会在返回值中列出)。
该变量的值为帮助键 C-h 后续字符所使用的局部按键映射。
该符号并非函数,其函数定义单元中保存名为 help-map 的按键映射。它在 help.el 中定义如下:
(keymap-set global-map (key-description (string help-char)) 'help-command) (fset 'help-command help-map)
该变量的值为帮助字符,即 Emacs 识别为帮助含义的字符。默认值为 8,对应 C-h。当 Emacs 读取该字符时,若 help-form 为非 nil 的 Lisp 表达式,则求值该表达式,若结果为字符串则在框架中显示。
通常 help-form 为 nil,此时帮助字符在命令输入层无特殊含义,会按常规方式成为按键序列的一部分。C-h 的标准绑定是多个通用帮助功能的前缀键。
帮助字符在前缀键之后也具有特殊性。若其在前缀键下无子命令绑定,则运行 describe-prefix-bindings,显示该前缀键的所有子命令列表。
该变量的值为事件类型列表,用作备用帮助字符。这些事件的处理方式与 help-char 指定的事件相同。
若该变量非 nil,则每当读取到 help-char 字符时,就会求值其值对应的表达式。若求值结果为字符串,则显示该字符串。
调用 read-event、read-char-choice、read-char、read-char-from-minibuffer 或 y-or-n-p 的命令,在执行输入时通常应将 help-form 绑定为非 nil 表达式(C-h 另有含义时除外)。该表达式的求值结果应为字符串,说明输入用途与正确输入方式。
进入小框架时,该变量会被绑定为 minibuffer-help-form 的值(see Definition of minibuffer-help-form)。
该变量保存用于打印前缀键帮助的函数。当用户输入前缀键后紧跟帮助字符,且帮助字符在该前缀下无绑定时调用。变量默认值为 describe-prefix-bindings。
该函数调用 describe-bindings 显示最近按键序列中前缀键的所有子命令列表。所描述的前缀由该按键序列除最后一个事件外的所有事件组成(最后一个事件通常为帮助字符)。
以下两个函数面向希望在不交出控制权的情况下提供帮助的模式(如电子模式)设计。其名称以 ‘Helper’ 开头,以与普通帮助函数区分。
该命令弹出一个框架,显示包含局部与全局按键映射所有绑定的帮助框架。其通过调用 describe-bindings 实现。
该命令为当前模式提供帮助。它在小框架中提示用户 ‘Help (Type ? for further options)’,然后协助用户查询按键绑定与模式用途。返回 nil。
可通过修改映射 Helper-help-map 进行自定义。
该变量保存 Emacs 查找其附带的特定文档与文本文件的目录名。
该函数返回帮助框架的名称,通常为 *Help*;若该框架不存在,则先创建再返回。
该宏与 with-output-to-temp-buffer 类似地求值 body(see Temporary Displays),并将其表单产生的输出插入 buffer-or-name 指定的框架中(buffer-or-name 可为框架或框架名,常用值为 help-buffer 函数返回结果)。该宏将指定框架设为帮助模式,并显示提示信息告知用户如何退出与滚动帮助窗口。若用户选项 help-window-select 已相应设置,则选中帮助窗口。返回 body 中最后一个表达式的值。
该函数更新 *Help* 框架中的交叉引用数据,用于用户点击 ‘Back’ 或 ‘Forward’ 按钮时重新生成帮助信息。大多数使用 *Help* 框架的命令在清空框架前都应调用此函数。item 参数格式应为 (function . args),其中 function 为重新生成帮助框架所需调用的函数,args 为参数列表。若调用命令为交互式执行,则 interactive-p 非 nil,此时 *Help* 框架的 ‘Back’ 按钮历史栈会被清空。
使用 help-buffer、with-help-window 与 help-setup-xref 的示例参见 See describe-symbols example。
该宏定义名为 fname 的帮助命令,行为类似前缀键,显示其所提供子命令的列表。
调用时,fname 在窗口中显示 help-text,然后根据 help-map 读取并执行按键序列。字符串 help-text 应描述 help-map 中可用的绑定。
命令 fname 自身处理部分事件,用于滚动 help-text 显示。当 fname 读取到这类特殊事件时,执行滚动并继续读取下一个事件。当读取到不属于此类且在 help-map 中有绑定的事件时,执行该按键绑定并返回。
参数 help-line 应为 help-map 中可选操作的单行摘要。在当前 Emacs 版本中,仅当将选项 three-step-help 设为 t 时才会使用该参数。
该宏用于命令 help-for-help,其绑定为 C-h C-h。
若该变量非 nil,则由 make-help-screen 定义的命令会先在回显区显示 help-line 字符串,仅当用户再次输入帮助字符时才显示较长的 help-text 字符串。