25 文档

GNU Emacs 具有方便的内置帮助工具，其中大部分从与函数和变量相关的文档字符串中获取信息。 本章描述如何在 Lisp 程序中访问文档字符串。

文档字符串的内容应遵循某些约定。 特别是，它的第一行应该是一个完整的句子（或两个完整的句子），简要描述函数或变量的作用。 请参阅文档字符串提示，了解如何编写好的文档字符串。

请注意，Emacs 的文档字符串与 Emacs 手册不同。 手册有自己的源文件，用 Texinfo 语言编写； 文档字符串在它们适用的函数和变量的定义中指定。 文档字符串的集合不足以作为手册，因为好的手册不是以这种方式组织的； 它是根据讨论的主题组织的。

有关显示文档字符串的命令，请参阅 GNU Emacs 手册中的帮助。

25.1 文档基础

文档字符串是使用 Lisp 字符串语法编写的，文本周围有双引号字符。 事实上，它是一个真正的 Lisp 字符串。 当字符串出现在函数或变量定义中的适当位置时，它充当函数或变量的文档。

在函数定义（lambda 或 defun 形式）中，文档字符串在参数列表之后指定，并且通常直接存储在函数对象中。 请参阅函数的文档字符串。 您还可以将函数文档放在函数名称的函数文档属性中（请参阅访问文档字符串）。

在变量定义（defvar 形式）中，文档字符串在初始值之后指定。 请参阅定义全局变量。 该字符串存储在变量的变量文档属性中。

有时，Emacs 不会将文档字符串保存在内存中。 这样的情况有两种。 首先，为了节省内存，预加载函数和变量（包括原语）的文档保存在一个名为 DOC 的文件中，该文件位于 doc-directory 指定的目录中（请参阅对文档字符串的访问）。 其次，当从字节编译文件加载函数或变量时，Emacs 会避免加载其文档字符串（请参阅文档字符串和编译）。 在这两种情况下，Emacs 仅在需要时才从文件中查找文档字符串，例如当用户为函数调用 Ch f (describe-function) 时。

文档字符串可以包含特殊的键替换序列，指的是仅在用户查看文档时才查找的键绑定。 即使用户重新排列默认键绑定，这也允许帮助命令显示正确的键。 请参阅替换文档中的键绑定。

在自动加载命令的文档字符串中（请参阅 Autoload），这些键替换序列具有额外的特殊效果：它们会导致命令上的 Ch f 触发自动加载。 （这是正确设置 Help 缓冲区中的超链接所必需的。）

25.2 访问文档字符串

Function: documentation-property symbol property &optional verbatim ¶

此函数返回记录在属性属性下的符号属性列表中的文档字符串。 它最常用于查找变量的文档字符串，其属性为变量文档。 但是，它也可用于查找其他类型的文档，例如自定义组（但对于功能文档，请使用下面的文档功能）。

如果属性值引用存储在 DOC 文件或字节编译文件中的文档字符串，则此函数查找该字符串并返回它。

如果属性值不是 nil，不是字符串，并且不引用文件中的文本，则将其作为 Lisp 表达式求值以获得字符串。

最后，此函数通过substitute-command-keys 传递字符串以替换键绑定（请参阅文档中的替换键绑定）。 如果 verbatim 不为零，则跳过此步骤。

    (documentation-property 'command-line-processed
	 'variable-documentation)
	   ⇒ "Non-nil once command line has been processed"

    (symbol-plist 'command-line-processed)
	   ⇒ (variable-documentation 188902)

    (documentation-property 'emacs 'group-documentation)
	   ⇒ "Customization of the One True Editor."

Function: documentation function &optional verbatim ¶

此函数返回函数的文档字符串。 它处理宏、命名键盘宏、特殊形式以及普通函数。

如果 function 是一个符号，则此函数首先查找该符号的函数文档属性； 如果它具有非零值，则文档来自该值（如果该值不是字符串，则对其进行评估）。

如果 function 不是符号，或者它没有 function-documentation 属性，则文档从实际函数定义中提取文档字符串，如果需要，则从文件中读取它。

最后，除非 verbatim 不是 nil，否则此函数调用替代命令键。 结果是要返回的文档字符串。

如果函数没有函数定义，则文档函数会发出 void-function 错误信号。 但是，如果函数定义没有文档字符串，也可以。 在这种情况下，文档返回 nil。

Function: face-documentation face ¶

该函数将人脸的文档字符串作为人脸返回。

下面是使用文档和文档属性这两个函数的示例，用于在 Help 缓冲区中显示多个符号的文档字符串。

 (defun describe-symbols (pattern)
   "Describe the Emacs Lisp symbols matching PATTERN.
 All symbols that have PATTERN in their name are described
 in the *Help* buffer."
   (interactive "sDescribe symbols matching: ")
   (let ((describe-func
	   (lambda (s)

	     ;; Print description of symbol.
	     (if (fboundp s)             ; It is a function.
		 (princ
		  (format "%s\t%s\n%s\n\n" s
		    (if (commandp s)
			(let ((keys (where-is-internal s)))
			  (if keys
			      (concat
			       "Keys: "
			       (mapconcat 'key-description
					  keys " "))
			    "Keys: none"))
		      "Function")

		    (or (documentation s)
			"not documented"))))

	     (if (boundp s)              ; It is a variable.

		 (princ
		  (format "%s\t%s\n%s\n\n" s
		    (if (custom-variable-p s)
			"Option " "Variable")

		    (or (documentation-property
			  s 'variable-documentation)
			"not documented"))))))
	  sym-list)


     ;; Build a list of symbols that match pattern.
     (mapatoms (lambda (sym)
		  (if (string-match pattern (symbol-name sym))
		      (setq sym-list (cons sym sym-list)))))


     ;; Display the data.
     (help-setup-xref (list 'describe-symbols pattern)
		   (called-interactively-p 'interactive))
     (with-help-window (help-buffer)
	(mapcar describe-func (sort sym-list 'string<)))))

describe-symbols 函数的工作方式与 apropos 类似，但提供了更多信息。

(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option
Semipermanent goal column for vertical motion, as set by …


minibuffer-temporary-goal-position      Variable
not documented


set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.

Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument ARG, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable ‘goal-column’.

(fn ARG)


temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was at the start of the current run
of vertical motion commands.

When moving by visual lines via the function ‘line-move-visual’, it is a cons
cell (COL . HSCROLL), where COL is the x-position, in pixels,
divided by the default column width, and HSCROLL is the number of
columns by which window is scrolled from left margin.

When the ‘track-eol’ feature is doing its job, the value is
‘most-positive-fixnum’.
---------- Buffer: *Help* ----------

Function: Snarf-documentation filename ¶

这个函数在构建 Emacs 时使用，就在可运行的 Emacs 被转储之前。 它找到存储在文件 filename 中的文档字符串的位置，并将这些位置记录到函数定义和变量属性列表中的内存中。 请参阅构建 Emacs。

Emacs 从 emacs/etc 目录中读取文件 filename。 稍后执行转储的 Emacs 时，将在目录 doc-directory 中查找相同的文件。 通常文件名是“DOC”。

Variable: doc-directory ¶

该变量包含目录的名称，该目录应包含文件“DOC”，该文件包含内置和预加载函数和变量的文档字符串。

在大多数情况下，这与数据目录相同。 当您从构建它的目录运行 Emacs 而不实际安装它时，它们可能会有所不同。 请参阅数据目录的定义。

25.3 替换文档中的键绑定

当文档字符串引用键序列时，它们应该使用当前的实际键绑定。 他们可以使用下面描述的某些特殊文本序列来做到这一点。 以通常的方式访问文档字符串会将当前的键绑定信息替换为这些特殊序列。 这通过调用替代命令键来工作。 您也可以自己调用该函数。

以下是特殊序列的列表及其含义：

\[command]

代表将调用命令的键序列，如果命令没有键绑定，则表示“Mx 命令”。

\{mapvar}

代表 keymap 的摘要，它是变量 mapvar 的值。 使用 describe-bindings 进行摘要。

\<mapvar>

代表没有文本本身。 它仅用于副作用：它指定 mapvar 的值作为此文档字符串中任何后续 ‘\[command]’ 序列的键映射。

`

（重音）代表左引号。 这会根据 text-quoting-style 的值生成左单引号、撇号或重音符。 请参阅文本引用样式。

'

（撇号）代表正确的引用。 这会根据 text-quoting-style 的值生成右单引号或撇号。

\=

引用以下字符并被丢弃； 因此，’\=`’ 将 ‘`’ 放入输出，’\=\[’ 将 ‘\[’ 放入输出，而 ‘\=\=’ 将 ‘\=’ 放入输出。

请注意：在 Emacs Lisp 中写入字符串时，每个 ‘' 必须加倍。

User Option: text-quoting-style ¶

这个变量的值是一个符号，它指定 Emacs 应该在帮助和消息的措辞中为单引号使用的样式。 如果变量的值为curve，则样式为带有弯曲单引号的“like this”。 如果值为直，则样式为带有直撇号的“like this”。 如果值是严重的，则不翻译引号并且样式是带有重音和撇号的“like this”，这是 Emacs 版本 25 之前的标准样式。如果弯曲的单引号似乎是可显示的，则默认值 nil 的作用类似于曲线，并且喜欢否则严重。

此选项在存在弯引号问题的平台上很有用。 您可以根据个人喜好自由定制。

Function: substitute-command-keys string &optional no-face ¶

此函数扫描字符串以查找上述特殊序列并将其替换为它们所代表的内容，并将结果作为字符串返回。 这允许显示准确引用用户自己定制的键绑定的文档。 默认情况下，键绑定被赋予一个特殊的面帮助键绑定，但如果可选参数 no-face 为非零，则该函数不会将此面添加到生成的字符串中。

如果一个命令有多个绑定，这个函数通常使用它找到的第一个。 您可以通过将 :advertised-binding 符号属性分配给命令来指定一个特定的键绑定，如下所示：

(put 'undo :advertised-binding [?\C-/])

:advertised-binding 属性也会影响菜单项中显示的绑定（参见菜单栏）。 如果该属性指定了命令实际上没有的键绑定，则该属性将被忽略。

以下是特殊序列的示例：

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

文档字符串中的文本还有其他特殊约定——例如，您可以参考本手册的函数、变量和部分。 有关详细信息，请参阅文档字符串提示。

25.4 文本引用样式

通常，重音和撇号在文档字符串和诊断消息中被特殊处理，并转换为匹配的单引号（也称为“弯引号”）。 例如，文档字符串“’foo’ 的别名”。 和函数调用（消息“’foo’ 的别名。”）都转换为“’foo’ 的别名。”。 不太常见的是，Emacs 将重音符号和撇号显示为本身，或仅显示为撇号（例如，“’foo’ 的别名。”）。 应该编写文档字符串和消息格式，以便它们与这些样式中的任何一种都很好地显示。 例如，文档字符串“’foo’ 的别名”。 可能不是您想要的，因为它可以显示为“’foo’ 的别名。”，这是一种不寻常的英文风格。

有时您可能需要在不翻译的情况下显示重音或撇号，无论文本引用样式如何。 在文档字符串中，您可以使用转义符来做到这一点。 例如，在文档字符串 “\=`(a ,(sin 0)) ==> (a 0.0)” 中，重音符号旨在表示 Lisp 代码，因此无论引用样式如何，它都会被转义并显示为自身. 在对消息或错误的调用中，您可以通过使用格式“%s”和调用格式的参数来避免转换。 例如， (message “%s” (format “`(a ,(sin %S)) ==> (a %S)” x (sin x))) 显示以重音开头的消息，无论文本引用如何风格。

User Option: text-quoting-style ¶

这个用户选项的值是一个符号，它指定 Emacs 应该在帮助和消息的措辞中为单引号使用的样式。 如果选项的值为curve，则样式为带有弯曲单引号的“like this”。 如果值为直，则样式为带有直撇号的“like this”。 如果值是严重的，则不翻译引号，并且样式是带有重音和撇号的“like this”，这是 Emacs 版本 25 之前的标准样式。如果弯曲的单引号似乎是可显示的，则默认值 nil 的作用类似于曲线，并且喜欢否则严重。

此选项在存在弯引号问题的平台上很有用。 您可以根据个人喜好自由定制。

25.5 描述帮助信息的字符

这些函数将事件、按键序列或字符转换为文本描述。 这些描述对于在消息中包含任意文本字符或键序列很有用，因为它们将非打印字符和空白字符转换为打印字符序列。 非空白打印字符的描述是字符本身。

Function: key-description sequence &optional prefix ¶

此函数返回一个字符串，其中包含按顺序输入事件的 Emacs 标准表示法。 如果前缀是非零，它是导致序列的输入事件序列，并包含在返回值中。 两个参数都可以是字符串、向量或列表。 有关有效事件的更多信息，请参阅输入事件。

  (key-description [?\M-3 delete])
	   ⇒ "M-3 <delete>"

  (key-description [delete] "\M-3")
	   ⇒ "M-3 <delete>"

另请参阅下面的单键描述示例。

Function: single-key-description event &optional no-angles ¶

此函数以标准 Emacs 表示法返回一个描述事件的字符串，用于键盘输入。 正常的打印字符显示为自身，但控制字符变为以’C-‘开头的字符串，元字符变为以’M-‘开头的字符串，空格、制表符等显示为’SPC’ , ‘TAB’ 等。功能键符号出现在尖括号 ‘<…>’ 内。 作为列表的事件显示为列表的 CAR 中尖括号内的符号名称。

如果可选参数 no-angles 不为 nil，则省略功能键和事件符号周围的尖括号； 这是为了与不使用括号的旧版本的 Emacs 兼容。

  (single-key-description ?\C-x)
	   ⇒ "C-x"

  (key-description "\C-x \M-y \n \t \r \f123")
	   ⇒ "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"

  (single-key-description 'delete)
	   ⇒ "<delete>"

  (single-key-description 'C-mouse-1)
	   ⇒ "C-<mouse-1>"

  (single-key-description 'C-mouse-1 t)
	   ⇒ "C-mouse-1"

Function: text-char-description character ¶

这个函数返回一个字符串，以标准 Emacs 表示法描述可以出现在文本中的字符——类似于单键描述，除了参数必须是通过 characterp 测试的有效字符代码（请参阅字符代码）。 该函数生成带有前导插入符号的控制字符的描述（这是 Emacs 通常在缓冲区中显示控制字符的方式）。 带有修饰位的字符将导致该函数发出错误信号（带有 Control 修饰符的 ASCII 字符是一个例外，它们表示为控制字符）。

  (text-char-description ?\C-c)
	   ⇒ "^C"

  (text-char-description ?\M-m)
	   error→ Wrong type argument: characterp, 134217837

Command: read-kbd-macro string &optional need-vector ¶

该函数主要用于对键盘宏进行操作，但也可以作为按键描述的粗略逆向使用。 你用一个包含键描述的字符串来调用它，用空格分隔； 它返回一个包含相应事件的字符串或向量。 （这可能是也可能不是单个有效键序列，具体取决于您使用的事件；请参阅键序列。）如果需要向量不为零，则返回值始终是向量。

25.6 帮助功能

Emacs 提供了各种内置的帮助功能，用户可以作为前缀 Ch 的子命令访问所有这些功能。 有关它们的更多信息，请参阅 GNU Emacs 手册中的帮助。 在这里，我们描述了相同信息的一些程序级接口。

Command: apropos pattern &optional do-all ¶

此函数查找名称包含与 apropos 模式模式匹配的所有有意义的符号。 apropos 模式要么是要匹配的单词，要么是空格分隔的单词列表，其中至少有两个必须匹配，要么是正则表达式（如果出现任何特殊的正则表达式字符）。 如果符号具有函数、变量或面的定义，或者具有属性，则它是有意义的。

该函数返回一个元素列表，如下所示：

(symbol score function-doc variable-doc
 plist-doc widget-doc face-doc group-doc)

在这里，score 是一个整数度量，用于衡量符号作为匹配项的重要性。 剩下的每个元素都是一个文档字符串，或 nil，用于符号作为函数、变量等。

它还在一个名为 Apropos 的缓冲区中显示符号，每个符号都有一个从其文档字符串开头获取的单行描述。

如果 do-all 不是 nil，或者如果用户选项 apropos-do-all 是 non-nil，那么 apropos 还会显示找到的函数的键绑定； 它还显示了所有的实习符号，而不仅仅是有意义的符号（它也在返回值中列出了它们）。

Variable: help-map ¶

此变量的值是帮助键 Ch 之后字符的本地键映射。

Prefix Command: help-command ¶

这个符号不是函数； 它的函数定义单元包含称为帮助映射的键映射。 它在 help.el 中定义如下：

(define-key global-map (string help-char) 'help-command)
(fset 'help-command help-map)

User Option: help-char ¶

这个变量的值是帮助字符——Emacs 识别为帮助的字符。 默认情况下，它的值为 8，代表 Ch。 当 Emacs 读取这个字符时，如果 help-form 是一个非 nil Lisp 表达式，它会计算那个表达式，如果它是一个字符串，它会在一个窗口中显示结果。

通常 help-form 的值为 nil。 那么帮助字符在命令输入层面没有特殊意义，它以正常方式成为键序列的一部分。 Ch 的标准键绑定是几个通用帮助功能的前缀键。

前缀键之后的帮助字符也是特殊的。 如果它没有绑定作为前缀键的子命令，它将运行 describe-prefix-bindings，它显示前缀键的所有子命令的列表。

User Option: help-event-list ¶

此变量的值是用作替代帮助字符的事件类型列表。 这些事件的处理方式与 help-char 指定的事件一样。

Variable: help-form ¶

如果此变量不为 nil，则它的值是每当读取字符 help-char 时评估的形式。 如果评估表单产生一个字符串，则显示该字符串。

调用 read-event、read-char-choice、read-char、read-char-from-minibuffer 或 y-or-np 的命令可能应该在输入时将 help-form 绑定到非 nil 表达式。 （不应该这样做的时候是 Ch 有其他含义的时候。）评估这个表达式应该产生一个字符串，解释输入的用途以及如何正确输入它。

minibuffer 的入口将此变量绑定到 minibuffer-help-form 的值（参见 minibuffer-help-form 的定义）。

Variable: prefix-help-command ¶

该变量包含一个打印前缀键帮助的函数。 当用户键入前缀键后跟帮助字符时调用该函数，并且帮助字符在该前缀之后没有绑定。 该变量的默认值为 describe-prefix-bindings。

Command: describe-prefix-bindings ¶

此函数调用 describe-bindings 以显示最近键序列的前缀键的所有子命令的列表。 所描述的前缀包含除该键序列的最后一个事件之外的所有事件。 （最后一个事件大概是帮助角色。）

以下两个功能适用于希望在不放弃控制的情况下提供帮助的模式，例如电动模式。 它们的名称以“Helper”开头，以区别于普通的帮助功能。

Command: Helper-describe-bindings ¶

此命令弹出一个窗口，显示一个帮助缓冲区，其中包含来自本地和全局键映射的所有键绑定的列表。 它通过调用 describe-bindings 来工作。

Command: Helper-help ¶

该命令为当前模式提供帮助。 它在 minibuffer 中向用户提示消息“帮助（类型？获取更多选项）”，然后帮助找出键绑定是什么，以及模式的用途。 它返回零。

这可以通过更改地图 Helper-help-map 来定制。

Variable: data-directory ¶

此变量保存 Emacs 找到 Emacs 附带的某些文档和文本文件的目录的名称。

Function: help-buffer ¶

该函数返回帮助缓冲区的名称，通常为*Help*； 如果这样的缓冲区不存在，则首先创建它。

Macro: with-help-window buffer-or-name body… ¶

这个宏像 with-output-to-temp-buffer 一样评估 body（参见 Temporary Displays），将由其形式产生的任何输出插入到由 buffer-or-name 指定的缓冲区中，该缓冲区可以是缓冲区或缓冲区的名称。 （通常，buffer-or-name 是函数 help-buffer 返回的值。）该宏将指定的缓冲区置于帮助模式并显示一条消息，告诉用户如何退出和滚动帮助窗口。 如果用户选项 help-window-select 的当前值已相应设置，则选择帮助窗口。 它返回正文中的最后一个值。

Function: help-setup-xref item interactive-p ¶

此函数更新 Help 缓冲区中的交叉引用数据，该缓冲区用于在用户单击“后退”或“前进”按钮时重新生成帮助信息。 大多数使用 Help 缓冲区的命令应该在清除缓冲区之前调用此函数。 item 参数应具有 (function . args) 形式，其中 function 是要调用的函数，带有参数列表 args，以重新生成帮助缓冲区。 如果调用命令是交互式调用的，则 interactive-p 参数不为零； 在这种情况下，*Help* 缓冲区的“后退”按钮的项目堆栈将被清除。

有关使用 help-buffer、with-help-window 和 help-setup-xref 的示例，请参见 describe-symbols 示例。

Macro: make-help-screen fname help-line help-text help-map ¶

该宏定义了一个名为 fname 的帮助命令，它的作用类似于显示它提供的子命令列表的前缀键。

调用时，fname 在窗口中显示帮助文本，然后根据帮助图读取并执行键序列。 字符串 help-text 应该描述 help-map 中可用的绑定。

命令 fname 被定义为通过滚动帮助文本的显示来处理一些事件本身。 当 fname 读取其中一个特殊事件时，它会进行滚动，然后读取另一个事件。 当它读取一个不是少数事件之一并且在帮助映射中具有绑定的事件时，它会执行该键的绑定然后返回。

参数 help-line 应该是 help-map 中备选方案的单行摘要。 在当前版本的 Emacs 中，仅当您将选项三步帮助设置为 t 时才使用此参数。

此宏用于命令 help-for-help，它是 Ch Ch 的绑定。

User Option: three-step-help ¶

如果该变量不为 nil，则使用 make-help-screen 定义的命令首先在回显区域中显示其帮助行字符串，并且仅当用户再次键入帮助字符时才显示较长的帮助文本字符串。

25.7 文档组

Emacs 可以根据各种分组列出函数。 例如，string-trim 和 mapconcat 是“字符串”函数，因此 Mx shortdoc-display-group RET string RET 将概述对字符串进行操作的函数。

文档组是使用 define-short-documentation-group 宏创建的。

Macro: define-short-documentation-group group &rest functions ¶

将 group 定义为一组函数，并提供使用这些函数的简短摘要。 可选参数函数是一个列表，其元素具有以下形式：

(func [keyword val]…)

可识别以下关键字：

:eval

该值应该是在评估时没有副作用的形式。 该表单将通过使用 prin1 打印在文档中使用（请参阅输出函数）。 但是，如果表单是字符串，它将按原样插入，然后读取字符串以生成表单。 在任何情况下，都会对表单进行评估，并使用结果。 例如：

	   :eval (concat "foo" "bar" "zot")
	   :eval "(make-string 5 ?x)"

将导致：

	   (concat "foo" "bar" "zot")
	   ⇒ "foobarzot"
	   (make-string 5 ?x)
	   ⇒ "xxxxx"

（这里允许同时使用 Lisp 表单和字符串的原因是，在少数需要某种形式呈现的情况下，可以控制打印。在示例中，“？x”将被打印为“120”如果它没有包含在字符串中。）

:no-eval

这类似于 :eval，只是不会评估表单。 在这些情况下，应该包含某种类型的 :result 元素（见下文）。

	   :no-eval (file-symlink-p "/tmp/foo")
	   :eg-result t

:no-eval*

像 :no-eval 一样，但总是插入 ‘[it depends]’ 作为结果。 例如：

	   :no-eval* (buffer-string)

将导致：

	   (buffer-string)
	   → [it depends]

:no-value

与 :no-eval 类似，但在所讨论的函数没有明确定义的返回值时使用，并且仅用于副作用。

:result

用于输出非评估示例表单的结果。

	   :no-eval (setcar list 'c)
	   :result c

:eg-result

用于从非评估示例表单输出示例结果。 例如：

	   :no-eval (looking-at "f[0-9]")
	   :eg-result t

将导致：

	   (looking-at "f[0-9]")
	   eg. → t

:result-string
:eg-result-string

这两个分别与 :result 和 :eg-result 相同，但按原样插入。 当结果不可读或应为特定形式时，这很有用：

	   :no-eval (find-file "/tmp/foo")
	   :eg-result-string "#<buffer foo>"
	   :no-eval (default-file-modes)
	   :eg-result-string "#o755"

:no-manual

表示该功能未在手册中记录。

:args

默认情况下，会显示函数的实际参数列表。 如果 :args 存在，则使用它们。

	   :args (regexp string)

这是一个非常简短的示例：

     (define-short-documentation-group string
	"Creating Strings"
	(substring
	 :eval (substring "foobar" 0 3)
	 :eval (substring "foobar" 3))
	(concat
	 :eval (concat "foo" "bar" "zot")))

第一个参数是要定义的组的名称，然后是任意数量的函数描述。

一个函数可以属于任意数量的文档组。

除了功能描述外，列表还可以有字符串元素，用于将文档组划分为多个部分。

Function: shortdoc-add-function shortdoc-add-function group section elem ¶

Lisp 包可以使用此命令将函数添加到组中。 每个元素都应该是一个函数描述，如上所述。 group 是功能组，section 是将功能插入到功能组中的哪个部分。

如果组不存在，它将被创建。 如果部分不存在，它将被添加到功能组的末尾。