翻译: GNU Texinfo 7.2

我们欢迎大家针对 Texinfo 系统的任意方面提交问题反馈与改进建议，涵盖程序运行、文档内容、安装部署等相关问题。请将反馈内容发送至邮箱：bug-texinfo@gnu.org。你可通过 Texinfo 官方主页获取其最新版本，网址为：https://www.gnu.org/software/texinfo。

提交问题反馈时，请提供足够信息，确保维护者能够复现相关问题。一般来说，需包含以下内容：

• Texinfo 的版本号，以及涉事的程序和手册版本
• 复现问题所需的所有输入文件内容
• 涉事程序的具体运行步骤
• 问题现象描述，以及所有错误输出的样本
• 所用的硬件设备、操作系统名称及版本
• 你认为有帮助的其他相关信息

若不确定某项信息是否需要提供，建议一并附上。提供的信息宁多勿少，避免遗漏关键内容。

务必附上能复现问题的实际输入文件，这一点至关重要。

若 GNU Emacs 中的 Info 阅读器出现问题，需向 Emacs 开发团队提交反馈，具体可参阅《GNU Emacs 手册》中的 “问题反馈” 章节。

我们同样欢迎大家提交程序补丁。若有相关提交，建议使用 'diff -c'、 'diff -u' （详见《文件的比较与合并》）或 'git diff' 命令生成补丁，并附上 ChangeLog 变更记录（详见《GNU 编码标准》中的 “变更日志” 章节），同时遵循项目现有的编码规范。

下文为 Texinfo 目前支持的输出格式总览。

Info

信息文档格式。 （通过 texi2any 生成）该格式基本是 Texinfo 源文件的纯文本转写形式，仅添加少量控制字符，为交叉引用、索引等功能提供导航信息。GNU Emacs 的信息文档子系统（参见《信息文档》）、独立的 info 程序（参见《GNU 信息文档程序》）等工具均可读取此类文件。相关详情参见《Info 文件》与《创建并安装 Info 文件》章节。

Plain text

纯文本格式。 （通过 texi2any --plaintext 生成）该格式与 Info 格式输出几乎一致，仅剔除了用于导航的控制字符。

HTML

超文本标记语言。 （通过 texi2any --html 生成）HTML 是超文本标记语言的缩写，为 World Wide Web万维网 文档的编写标准，可由网页浏览器在线渲染展示。HTML 拥有多个版本，既包含不同的官方标准，也存在各浏览器专属的扩展规范。 texi2any 工具仅使用该语言的通用子集，可被所有主流浏览器解析，且刻意避免使用大量较新或支持度较低的标签。因此其原生输出样式虽较为简洁，但可根据需求在多个层级进行自定义配置。相关详情参见《生成 HTML 文档》章节。

EPUB 3

电子出版格式。 （通过 texi2any --epub3 生成）EPUB 是专为便携式设备阅读电子书设计的格式，由 HTML 衍生而来。该格式最初由国际数字出版论坛（IDPF）开发，目前该组织已并入万维网联盟（W3C）。其最新主要修订版本 EPUB 3 于 2011 年发布。

DVI

设备无关格式。 （通过 texi2dvi 生成）设备无关二进制格式是 TeX 排版程序（官网：http://tug.org）的输出格式，需由 DVI 驱动程序解析后，转换为适配具体设备的显示或打印指令。常用的 DVI 驱动程序包括：将格式转换为 PostScript 格式的 Dvips（参见《Dvips 工具》）、用于 X 窗口系统显示的 Xdvi（下载地址：http://sourceforge.net/projects/xdvi/）。相关详情参见《使用 TeX 进行排版与打印》章节。（请注意：Texinfo 语言与 TeX 系列常用语言差异显著，包括纯 TeX、LaTeX、ConTeXt 等。）

PostScript

页面描述语言。 （通过 texi2dvi --ps 生成）PostScript 是一种页面描述语言，自 1985 年起被广泛应用，至今仍在使用。其基础介绍及更多相关参考可参见：https://en.wikipedia.org/wiki/PostScript。Texinfo 默认识别 dvips 程序，将 TeX 生成的 DVI 格式转换为 PostScript 格式。相关详情参见《Dvips 工具》章节。

PDF

便携式文档格式。 （通过 texi2dvi --pdf 或 texi2pdf 生成）该格式由 Adobe 系统公司基于其早前的 PostScript 语言开发，专为便携式文档交换设计。该格式可精准还原文档的原始外观，包括字体、图形等元素，且支持任意比例缩放。其设计目标包括跨平台兼容、易于查看等；相关背景知识可参见：https://en.wikipedia.org/wiki/Portable_Document_Format 与 http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf。Texinfo 默认使用 pdftex 程序（TeX 的扩展工具）生成 PDF 格式，工具详情参见：http://tug.org/applications/pdftex。相关使用方法参见《PDF 格式输出》章节。

LaTeX

拉泰赫格式。 （通过 texi2any --latex 生成）该格式是基于 TeX 构建的排版系统，最初由莱斯利・兰波特于 1984 年发布。LaTeX 在 TeX 的基础上扩充了大量定义，且拥有丰富的第三方扩展包，是学术文献领域的通用排版格式。目前 LaTeX 仍在持续开发更新，更多信息可参见其官方网站：https://www.latex-project.org/。

LaTeX 格式的输出文件可进一步转换为 DVI、PostScript 或 PDF 格式。从理论上讲，相较于基于纯 TeX 实现的 Texinfo，LaTeX 格式支持更高程度的输出自定义配置。

DocBook

文本书籍格式。 （通过 texi2any --docbook 生成）该格式是基于 XML 的标记语言，主要用于编写技术文档，因此在整体框架上与 Texinfo 存在一定相似性。官方详情参见：http://www.docbook.org。目前已有多款将 DocBook 格式转换为 Texinfo 格式的工具，相关信息可参见 Texinfo 官方网页。

XML

可扩展标记语言。 （通过 texi2any --xml 生成）与上述所有输出格式不同， texi2any 生成的 XML 格式并非最终可使用的文档，而是 Texinfo 源文件的转写形式，无法直接通过网页浏览器或其他常规程序查看。

XML 是一种通用的语法规范，可适用于各类内容的标记（参考标准：http://www.w3.org/XML）。Texinfo 生成 XML 格式的核心目的，是为了通过各类 XML 工具进行后续的二次处理。其输出语法由 XML 文档类型定义（DTD）规范，相关定义文件 texinfo.dtd 已包含在 Texinfo 源程序发布包中。

Texinfo 源程序发布包中还包含一个实用脚本 txixml2texi ，可将 XML 格式反向转换为原始的 Texinfo 内容（Texinfo 宏定义与条件语句除外）。

如前文所述，Info 格式基本是 Texinfo 源文件的纯文本转写形式，仅添加少量控制字符用于分隔节点并提供导航信息，供 Info 阅读程序解析运行。

Info 文件几乎均由处理 Texinfo 源文档生成， texi2any （也称作 makeinfo ）是将 Texinfo 文件转换为 Info 文件的核心命令，相关说明参见《texi2any：Texinfo 转换工具》章节。

通常情况下，用户会通过一个约定命名为 'Top' 的节点进入 Info 文件。该节点一般仅包含文件用途的简要说明，以及一个可访问文件其余内容的大型菜单。从该节点开始，你既可以按节点依次浏览整个文件，也可以直接跳转到主菜单中列出的指定节点，还可以检索索引菜单并直接定位到包含所需信息的节点。此外，使用独立的 Info 程序时，你还能在命令行中指定具体的菜单项（参见《Info 程序》章节）。

若你希望像阅读印刷版手册一样按顺序浏览 Info 文件，可反复按下空格键（SPC），也可使用 Info 高级命令 g * 调出整个文件的内容（参见《Info 程序中的高级命令》章节）。

info 目录下的 dir 文件 是整个 Info 系统的入口，通过该文件可访问完整 Info 系统中各文档的 'Top' 节点。

若你希望通过统一资源标识符（URI）引用 Info 文件，可使用以下示例中的非官方语法，该语法可在 Emacs/W3 等工具中正常使用：

info:emacs#Dissociated%20Press
info:///usr/info/emacs#Dissociated%20Press
info://localhost/usr/info/emacs#Dissociated%20Press

需要注意的是，info 程序本身并不支持解析任何形式的 URI。

Texinfo 文件可以被格式化并排版成印刷书籍或手册。要实现这一点，你需要使用 TeX—— 这是由斯坦福大学的高德纳（Donald Knuth）编写的一款专业排版程序，它并不包含在 Texinfo 发行包中。

Texinfo 提供了一个 texinfo.tex 文件，其中包含 TeX 在排版 Texinfo 文件时所需的定义。你可以从 Texinfo 官网获取最新版的 texinfo.tex：https://www.gnu.org/software/texinfo/。

基于 Texinfo 制作的书籍与其他排版印刷品类似：可以包含标题页、版权页、目录、前言，以及章节、带编号或无编号的小节与子小节、页眉、交叉引用、脚注和索引等。

TeX 功能非常强大，特性极多。但由于 Texinfo 文件必须既能以 Info 形式在纯字符终端上展示信息，又能排版成印刷书籍，因此 Texinfo 所支持的格式化命令会受到一定限制。

有关使用 TeX 处理手册的更多信息，请参见《使用 TeX 进行格式化与印刷》。

前面几节介绍的输出格式已经能满足非常广泛的使用场景，但显然仍有扩展空间。

如果你是程序员，并希望通过为 Texinfo 实现更多输出格式来为 GNU 项目贡献代码，那将非常有价值。最实用的实现方式是为 texi2any 编写一个新的后端 —— 它是我们的 Texinfo 解析器参考实现，会将 Texinfo 输入转换成树形结构，你可以直接基于该结构进行格式转换。源码文件 tp/Texinfo/Convert/Converter.pm 中的文档是很好的起点（详见 Texinfo 模块文档中的 Texinfo::Convert::Converter）。参见：texi2any：Texinfo 翻译器。

另一种可行的方式是使用 texi2any 输出的 Texinfo XML 作为输入。如上所述，这种 XML 基本完整表示了原输入内容，且不含 Texinfo 本身的语法与选项特性。

如果你仍然忍不住想直接编写一个读取 Texinfo 源码的新程序，我们再多提醒一句：请不要低估所需工作量。Texinfo 绝非易于正确解析的简单语言，且仍在持续开发中，这意味着你需要承担长期维护工作。建议你确保 texi2any 附带的语言测试用例在你的新程序中都能正确运行。

不时有人提议从 Texinfo 源码生成传统 Unix man 手册页。但由于 man 手册页有严格的约定格式，编写一份优质的 man 手册所需的源码，与用于编写优质用户教程 / 参考手册的典型 Texinfo 源码完全不同。这使得生成 man 手册与 Texinfo 的设计目标相冲突 ——Texinfo 的设计初衷就是 不必为不同输出格式用不同方式重复编写同一份文档 。你不如直接编写 man 手册。

作为支持 man 手册的替代方案，你可能会发现 help2man 工具很有用。它从程序的 '--help' 输出生成传统格式的 man 手册页。事实上，Texinfo 发行版中自带程序的 man 手册页就是用它生成的。这是由 Brendan O’Dea 开发的 GNU 软件，可从 http://www.gnu.org/software/help2man 获取。

理查德・M・斯托曼（Richard M. Stallman）发明了 Texinfo 格式，编写了最初的处理程序，并创建了本手册的 1.0 版。罗伯特・J・查塞尔（Robert J. Chassell）从 1.1 版开始，对手册进行了大量修订与扩充。布莱恩・福克斯（Brian Fox）负责 Texinfo 的独立发行版直至 3.8 版本。卡尔・贝里（Karl Berry）从 Texinfo 3.8（手册 2.22 版）开始继续维护，加文・史密斯（Gavin Smith）则从 Texinfo 6.0 起接手维护工作。

起源

理查德・斯托曼在 1975/1976 年的 Emacs 最初实现中，加入了一个名为 Info 的在线超文本帮助系统。几年前，他观看了道格拉斯・恩格尔巴特（Douglas Engelbart）的「NLS」超文本系统演示后深受启发。

另一方面，20 世纪 70 年代，卡内基梅隆大学（CMU）的布莱恩・里德（Brian Reid）开发了名为 Scribe 的程序与格式，用于标记文档以便打印输出。它和 Texinfo 一样，使用 @ 符号开头表示命令。更重要的是，Scribe 致力于描述文档内容而非排版样式，这一理念被 Texinfo 完全继承。

与此同时，麻省理工学院（MIT）的人员开发了另一种格式 Bolio。理查德・斯托曼（RMS）将 Bolio 改造为使用 TeX 作为排版语言，形成了 BoTeX。已知最早的 BoTeX 版本是 1984 年 10 月 31 日的 0.02 版。

BoTeX 仅能作为打印文档的标记语言，无法用于在线文档。RMS 将 BoTeX 与 Info 结合，创造了 Texinfo—— 一种既可在线阅读、也可打印成书的文本标记语言。

最初用于生成 Info 格式的转换器（主要由 RMS 与 Bob Chassell 完成）是用 Emacs Lisp 编写的，即 texinfo-format-buffer 等函数。20 世纪 90 年代初，Brian Fox(布莱恩・福克斯)用 C 语言重新实现了转换程序，即现在的 makeinfo ，同时也实现了独立的 info 阅读器。

用 Perl 重新实现

2012 年，C 语言版的 makeinfo 被一个 Perl 实现版本取代，该版本统称为 texi2any 。此版本支持与 texi2html 同等程度的输出定制能力。 texi2html 最初由 Lionel Cons 编写，后来由众多开发者共同完善。为让 texi2html 能替代 makeinfo 所需的大量新特性，由 Patrice Dumas 实现。 texi2any 的第一个从未发布的版本基于 texi2html 代码。

不过，该实现后来被废弃，转而使用当前程序（同样由 Patrice Dumas 编写），它会将 Texinfo 输入解析为树形结构再进行处理。它继承了 texi2html 的定制设计与其他特性（关于 texi2html 兼容性，详见 texi2html：texi2any 的前身）。但 texi2any 是完全重新实现：它为所有后端生成基于树结构的输入文档表示，供各后端使用。

这个新的 Perl 程序比旧的 C 程序慢很多。尽管自首次发布以来速度差距有所缩小，但可能永远无法完全匹敌。那我们为何还要切换？简而言之：我们希望并相信，当前程序会比之前 C 版的 makeinfo 更容易扩展，以支持不同输出样式、后端格式及各类定制。具体原因如下：

• HTML 定制：多年来，许多 GNU 及其他自由软件项目都在顺畅使用 texi2html 的 HTML 定制功能。实际上当时已存在两套独立的 Texinfo 语言实现，保持同步十分困难。把 texi2html 中的 HTML 定制能力加入 C 程序工作量巨大。
• Unicode 与多语言支持，尤其是东亚语言。当时若用 C 实现几乎等于重写整个程序。虽然后来解析器和部分转换后端改用 C 编写，但转换后端主体仍为 Perl，其内置了良好的多语言支持。
• 新增后端： makeinfo 代码已变得十分复杂，新增后端极为繁琐，需要与现有后端进行复杂交互。相比之下，新实现提供清晰的树结构表示，供所有后端使用。用户已提出多种后端需求（LaTeX、最新 (X) HTML 等），此次改造让这些后端更易实现。
• 降低贡献门槛：整体上，更清晰的结构、分离的解析器 / 后端设计，会让任何人都更容易阅读代码并参与贡献，带来显而易见的好处。尽管十年过去，社区贡献的后端仍未出现，但理论上这种结构更利于协作贡献。

texi2any 旨在成为参考实现，用于定义手册中未完全规范的语言细节。若无这样的参考实现，其他实现很可能出现或明显或细微的行为差异，进而导致 Texinfo 文档与特定处理器绑定。同时，为所有处理器提供一致的命令行选项也很重要。与 texi2any 同步开发了大量语言与处理器测试用例；我们鼓励所有打算编写 Texinfo 解析程序的人使用这些测试。

随着 texi2any 作为参考实现发布，C 语言版 makeinfo 与 texi2html 的开发均已停止。今后，我们建议 Texinfo 文档作者仅使用 texi2any 。

本节描述所有 Texinfo 文档通用的语法约定。

• 除 ‘@’、‘{’ 和 ‘}’ 之外，所有可打印 ASCII 字符均可直接出现在 Texinfo 文件中，并表示自身。‘@’ 是转义字符，用于标记命令开头；‘{’ 和 ‘}’ 则用于包裹部分命令的参数。若要在文档中插入这些特殊字符，需在其前面加一个 ‘@’：即 ‘@@’、‘@{’ 和 ‘@}’。

• 在 Texinfo 文件中，用于描述手册内容的命令均以 ‘@’ 开头，这类命令称为 ‘@-commands’。（Texinfo 中的 ‘@’ 作用与纯 TeX 中的 ‘\’ 相同。）

  根据功能与参数形式的不同，部分 @-commands 需要单独成行书写，部分可直接写在句子中。通用规则：如果命令嵌入在普通文本中，则需要用大括号包裹参数；如果命令单独成行，则通常不需要大括号。关于 Texinfo 命令语法的更多细节，参见 @-Command 语法。

• @-command 名称后的空格是可选的，即使存在通常也会被忽略。例外情况是空格具有实际意义的环境，例如 @example 环境。
• Texinfo 支持英文及其他语言中常用的引号格式，详见插入引号。
• 连续三个连字符 --- 会生成长破折号（em dash），用于句子中的标点分隔。两个连字符 -- 生成中破折号（en dash），主要用于表示数值范围，例如 “6 月 25–26 日”。单个连字符 - 生成普通连字符，用于复合词。在 Info 格式屏幕显示时，三个连字符会被简化为两个，两个连字符会被简化为一个（注意不是传递性缩减）。当然，在 @code 、 @example 等字面量环境中，源码中的任意数量连字符都会原样保留。
• 空白符：Texinfo 文件是纯文本文件，每行以常规换行符（换行符）结束。Texinfo 处理器逐行读取输入。段落以空行或仅包含空格的行作为结束标志。文本中连续的多个空格通常等价于单个空格（ verbatim 模式除外）。

换页符（CTRL-l）会结束当前未闭合的段落。其他换页符以及其他 ASCII 空白符（制表符、回车符）均按普通空格处理（尽管最终效果可能因输出格式而异）。因此，在文档中使用这类空白符意义不大。非 ASCII 空格（如 Unicode 全角空格等）完全不被识别为空白符，会被当作普通非空白字符处理。

但在 verbatim 模式下（例如代码示例中），制表符可以在输出中产生正确的排版效果。

你可以在 Texinfo 文件中使用 @comment 命令书写注释，该命令可简写为 @c 。这类注释是给阅读 Texinfo 源码的人看的。一行中跟在 @comment 或 @c 之后的所有内容都属于注释；这一行的剩余部分 不会出现在最终输出内容中 。（准确地说： @c 或 @comment 后面的字符不能是连字符或字母 / 数字，否则会被当作命令的一部分。）

通常，你可以在一行的中间使用 @comment 或 @c ，只有该命令之后的文本不会被输出；但某些命令（如 @settitle ）会处理整行内容。不能在这类命令开头的行内使用 @comment 或 @c 。

在嵌套命令、复杂宏定义等场景下， @c 和 @comment 在 TeX 处理时可能会引发错误。因此，你也可以使用 DEL 字符（十进制 ASCII 127，十六进制 0x7f，八进制 0177）作为真正的 TeX 注释符（在 TeX 内部为 catcode 14）。 DEL 字符之后该行的所有内容都会被忽略，并且会与下一行合并。

你还可以使用 @ignore 和 @end ignore 命令让一大段文本被 Texinfo 处理器忽略。这两个命令都要 单独成行 ，并且从行首开始写。两个命令之间的文本不会出现在处理后的输出中。你可以用 @ignore … @end ignore 来书写多行注释。（关于此类命令嵌套的注意事项，参见「条件嵌套」。）

按照惯例，Texinfo 文件的文件名后缀为 .texi 、 .texinfo 、 .txi 或 .tex 之一。不建议使用 .tex ，因为该后缀已被 TeX 和 LaTeX 输入文件占用。最常用且推荐的后缀是 .texi 。Texinfo 文件名应 只包含 ASCII 字符 。

默认情况下，输出文件名以输入文件名为基础生成：首先从输入文件名中去掉 .texi 、 .tex 、=.txi= 或 .texinfo 后缀；然后加上对应输出格式的专属后缀 —— 生成 HTML 时为 .html ，生成 Info 时为 .info ，依此类推。输出文件名也应只包含 ASCII 字符¹。

若要生成可打印的手册，Texinfo 文件 必须 以如下一行开头：

\input texinfo

文件内容写在这一行之后，并且必须用如下一行结束 Texinfo 源码：

@bye

文件末尾单独一行的 @bye 用于告知 TeX 文件已结束，停止排版。如果省略这一行，程序运行结束后会停留在 TeX 的交互提示符界面。

此外，你通常还会为 Texinfo 文件配置标题、标题页、索引等内容，这些都在本手册中有详细说明。但对于简短文档而言， 最简结构 只需要开头一行和结尾一行即可。

若无额外指定，输入与输出编码默认采用 UTF-8，这是一种兼容 7 位 ASCII 的通用编码。

下面是一个简短的 Texinfo 示例文件。

\input texinfo
@settitle 示例手册 1.0

@copying
这是一个完整 Texinfo 文件的简短示例。

版权所有 @copyright{} 2016 Free Software Foundation, Inc.
@end copying

@titlepage
@title 示例标题
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@node Top
@top GNU 示例

本手册适用于 GNU Sample
（版本 @value{VERSION}，@value{UPDATED}）。

@menu
* 第一章::    第一章是本示例
              中唯一的一章。
* 索引::      完整索引。
@end menu


@node 第一章
@chapter 第一章

@cindex 章，第一章
这是第一章。
@cindex 索引项，另一个

下面是一个有序列表。

@enumerate
@item
这是第一项。

@item
这是第二项。
@end enumerate


@node 第一节
@section 第一节

第一章的第一节。


@node 第二节
@section 第二节

第一章的第二节。


@node 索引
@unnumbered 索引

@printindex cp

@bye

Texinfo 文件以这一行开头：

\input texinfo

'\input texinfo' 这一行告诉 TeX 使用 texinfo.tex 文件，该文件定义了如何将 Texinfo 的 @-commands 转换成 TeX 的排版命令。（注意这里使用的是反斜杠 \ ；对 TeX 来说这是正确写法。）

将所有影响 整篇文档格式 的命令放在文件头里是合理的。 @settitle 行通常出现在文件头的开头：

@settitle Sample Manual 1.0

@settitle 用于指定印刷版手册的页面页眉（或页脚）标题，以及 HTML 中 ‘<head>’ 部分的默认标题和文档描述。例如 @synindex （参见 @synindex：合并索引）也是常放在文件头中的命令。

Texinfo 文件中，直到输出为文档主体内容之前的部分，统称为 序言 （preamble）。它包含文件头、文档权限声明、标题与版权页说明。这对 LaTeX 输出格式尤为重要，因为序言结束的位置会输出 \begin{document} 这一行。在其他输出格式中，序言可用于决定某些特殊内容的排版方式，例如：将 @copying（声明复制权限）的输出作为注释放在输出文件开头，或设置文件头中使用的语言。

• Texinfo 文件的第一行
• @setfilename: 设置输出文件名
• @settitle: 设置文档标题
• 序言
• Emacs 所用文件头的开始与结束

使用 @dircategory 命令为手册指定一个类别。下面是一些类别名称示例：

Basics                         # 基础
Text creation and manipulation # 文本创建与处理
Archiving                      # 归档
Compression                    # 压缩
Database                       # 数据库
Editors                        # 编辑器
Emacs
Email                          # 电子邮件
Graphics                       # 图形
Localization                   # 本地化
Network applications           # 网络应用
Printing                       # 打印
Science                        # 科学
Software development           # 软件开发
Software libraries             # 软件库
Version control                # 版本控制

@dircategory 命令之后通常会紧跟 @direntry 块，供 install-info 工具使用。详情参见《安装 Info 目录文件》。

手册中第一个 @dircategory 命令作用于整个手册。后续出现的 @dircategory 仅对紧跟在它之后的 @direntry 块生效。

这部分用于描述文档，并包含 copyright notice版权声明 和 copying permissions复制授权信息 ，通过 @copying 命令实现。一份正式的手册会根据其发布的许可证，在这里包含更多内容。

@copying
这是一个完整 Texinfo 文件的简短示例，版本 1.0。

Copyright @copyright{} 2016 Free Software Foundation, Inc.
@end copying

在 Texinfo 生成的各种输出格式中， copyright notice版权声明 和 copying permissions复制授权信息 需要出现在多个位置。因此，Texinfo 提供了两个命令： @copying 用于 一次性声明 这段文本， @insertcopying 用于在合适的位置 插入 这段文本。

如果文档是软件手册，软件本身通常采用不同的许可证 —— 对于 GNU 及其他许多自由软件包，软件一般以 GNU GPL 发布，而手册以 GNU FDL 发布。注明手册所对应软件的许可证是有益的，但不一定需要附上软件许可证的完整文本。

• @copying: 声明复制授权信息
• @insertcopying: 插入授权文本

在硬拷贝（印刷版）输出中，手册名称与作者通常会印在标题页上。版权信息通常印在标题页的背面（扉页）。这部分内容必须包裹在 @titlepage 和 @end titlepage 命令之间：

@titlepage
@title Sample Title

@c 下面两条命令用于开启版权页
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

我们使用 @insertcopying 命令来引入上一节定义的权限文本，而不是重复书写。

title标题 页与 copyright版权 页只出现在印刷版手册中，在大多数其他输出格式中不会显示。在 HTML 中，想要得到接近印刷版的标题页效果，最佳方式是设置自定义变量 NO_TOP_NODE_OUTPUT （参见 NO_TOP_NODE_OUTPUT）。

• @titlepage: 标题页
• @title, @subtitle, @author: 标题、副标题与作者
• @titlefont, @center, @sp: 标题字体、居中与空行
• Copyright Page: 版权页
• 标题生成规则

@chapter 、 @section 及其他结构化命令（参见章节结构化）会提供用于生成目录的信息，但这些命令本身不会让手册中出现实际的目录。要生成目录，你必须使用 @contents 或 @summarycontents 命令。

@contents

在打印版手册中生成完整目录，包含所有 chapters章节 、 sections节 、 subsections小节 等，以及附录和无编号章节。由 @majorheading 、 @chapheading 及其他 @…heading 命令生成的标题不会出现在目录中（参见结构化命令类型）。

@shortcontents

@summarycontents

（ @summarycontents 是 @shortcontents 的同义命令。）

生成简明目录或概要目录，仅列出 chapters章 。 appendices附录 和 unnumbered chapters无编号章节 ， sections节 、 subsections小节 与次次节均被省略。只有篇幅很长的手册，才需要在完整目录之外再附带一份简明目录。

这两个目录命令都应单独占一行，放在文件开头附近、 @end titlepage 之后（参见 @titlepage ）、任何结构化命令之前。目录命令会在目录首页顶部自动生成类似章节的标题，因此无需在其前面添加 @unnumbered 等结构化命令。

由于 Info 文件使用菜单而非目录，Info 格式化命令会忽略目录命令。但目录会被包含在纯文本输出及其他输出格式（如 HTML）中。

在 HTML 输出中，简明目录里的链接指向完整目录中的对应条目，而非文档正文；完整目录中的链接则直接指向文档正文。

@shortcontents 暂不支持 LaTeX 输出格式。

‘Top’ 节点是读者进入 Info 手册时最先到达的节点。因此，它应当包含对本手册的极简短说明（含版本号）。‘Top’ 节点里的内容 不会 出现在打印版或 DocBook 输出中。

惯例写法是：在 @node Top 这一行后面，紧接着写一行 @top 命令，并在其中填入文档标题（参见 @top 章节结构化命令）。

我们可以重复 @copying 文本开头的简短说明，但不必重复版权信息，因此这里 不使用 @insertcopying 。

‘Top’ 节点中包含一个 top-level menu顶层菜单 ，列出所有章节；也可以包含一个 detailed menu详细主菜单 ，列出整个文档里的所有节点。

@node Top
@top Short Sample

This is a short sample Texinfo file.

@menu
* First Chapter::    The first chapter is the
                       only chapter in this sample.
* Index::            Complete index.
@end menu

• 主菜单的组成部分

文档主体包含文档的全部文本。一本手册会被划分为一个或多个 nodes节点 （见节点）。下面的示例展示了一个由三个节点组成的章节：一个节点用于存放章节的引言内容，另外两个节点对应小节。引言部分中包含一个有序列表。

@node First Chapter
@chapter First Chapter

@cindex chapter, first
This is the first chapter.
@cindex index entry, another

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate


@node First Section
@section First Section

First section of first chapter.


@node Second Section
@section Second Section

Second section of first chapter.

在 Info 输出中，「First Chapter」节点会包含一个菜单，列出该章节下的两个小节。同样地，当该节点输出为独立的 HTML 文件时，文件中会包含本章的目录。

本章内容最终呈现效果如下：

1. First Chapter ¶

This is the first chapter.

Here is a numbered list.

1. This is the first item.
2. This is the second item.

1.1 First Section ¶

First section of first chapter.

1.2 Second Section ¶

Second section of first chapter.

（在 Info 和 HTML 输出中，本章内容同样会按节点进行拆分。）

Texinfo 文件的末尾应当包含用于生成索引的命令（参见《打印索引与菜单》），以及用于标记最后一行待处理内容的 @bye 命令。例如：

@node Index
@unnumbered Index

@printindex cp

@bye

@bye 命令会终止 Texinfo 的处理流程。它必须单独占一行。 @bye 之后的所有内容都会被完全忽略。

在一行开头书写 @node ，后面跟上 node-name节点名称 ，如下所示：

@node node-name

插入 @node 行之后，应紧接着书写对应的章节或小节相关 @-command （如果有）并写上名称。

你可以在 @node 的节点名称参数之后， 在同一行的剩余位置最多再写三个可选参数 ，参数之间用逗号分隔。它们依次是： ‘Next’（下一个）、‘Previous’（上一个）、‘Up’（上级） 指针 的名称。因此，完整写出 ‘Next’、‘Previous’、‘Up’ 指针的节点行模板如下：

@node node-name, next, previous, up

node-name 参数必须存在，其他参数可选。如果你只想指定部分指针，只需按需保留逗号即可，例如： @node mynode,,,uppernode 。 @node 行中每个名称前后的空格都会被忽略。但是，如果你的 Texinfo 文档是 层级结构 （几乎所有文档都是），我们建议 省略所有指针 ，让 texi2any 自动计算。

texi2any 工具会为层级结构的文档 自动生成节点指针 。要让它正常工作，每个 @node 命令后面应 紧跟 一个章节结构化命令（如 @chapter 或 @section ），中间可以穿插注释行。最后，你必须在 Top 节点行后面，紧跟一行以 @top 开头的内容，用来标记文件的顶层节点。参见 @top 章节结构化命令。

即使你显式指定了所有指针，也 不能 在 Texinfo 源文件中随意打乱节点顺序。节点必须按照你希望在输出中显示的顺序书写。虽然对 Info 格式来说顺序看似无关紧要，但对其他输出格式非常重要。

在大多数情况下，你应该利用 自动生成指针 的功能，不要重复书写程序可以自动确定的节点指针。不过，Texinfo 文档 不强制 必须是层级结构，甚至完全可以不包含章节结构化命令（例如你永远不打算打印该文档），因此在通用场景下，仍然可以显式指定节点指针。

如果你使用 GNU Emacs，并且希望显式写出指针，可以使用 Texinfo 模式提供的 更新节点命令 来自动插入指针名称。（参见：更新节点与菜单）

你也可以手动填写 ‘Next’、‘Previous’、‘Up’ 指针。在 Emacs 中这样做时，使用 Texinfo 模式的快捷键 C-c C-c n 会很方便。该命令会插入 @node 和一行注释，按正确顺序列出指针名称，帮助你区分每个参数对应哪个指针。

节点名称用于标识节点。关于节点名称的全部细节，参见「 @node 行格式要求」。

以下是关于节点命名的建议：

• 尽量选择 信息明确且简短 的节点名称。

  在 Info 文件中，文件名、节点名和指针名都会写在同一行，可能会超出窗口右边界（这对 Info 本身没有影响，但不够美观）。

• 尽量让节点名称 开头部分就互不相同 。这样便于在 Info 中使用 自动补全 功能。
• 按照惯例，节点名称的大小写规则与章节、小节标题一致。本手册中，首词和重要单词大写，其余小写；有些手册只大写首词和专有名词。两种方式均可，建议保持统一即可。
• 在 HTML 输出中，节点名称里除了纯 ASCII 字母、数字和空格之外的字符，都会在文件名中被转换。（参见 HTML 交叉引用节点名扩展规则。）这会让手册页面的 URL 变得不友好；例如，本手册中的 @dots 节点会被生成为 __0040dots.html 。
• 由于节点名会被用于 交叉引用 ，一旦文档发布后， 不建议 随意修改节点名。当你删除或重命名节点时，最好用旧名称定义一个 @anchor 。这样，来自其他手册、邮件归档等的引用就不会失效。参见 @anchor: 定义任意交叉引用目标。

给定节点的指针用于跳转到其他节点，指针内容就是这些目标节点的名称。

通常：

• 节点的 ‘Up’ 指针指向在其菜单中列出该节点的那个上级节点。
• 节点的 ‘Next’ 指针指向同一菜单中当前节点的下一个节点。
• 节点的 ‘Previous’ 指针指向同一菜单中当前节点的上一个节点。 如果一个节点的上一节点与上级节点是同一个，则两个指针指向同一节点。

通常，Texinfo 文件的第一个节点是 ‘Top’ 节点，它的 ‘Up’ 指针指向 dir 文件，该文件包含整个 Info 系统的主菜单。

与 @node 一起使用的名称有多项要求：

• 同一个 Texinfo 文件中的所有 node names节点名称 必须唯一。

  例如，如果你每章末尾都有一个小结，必须给每个小结节点起不同的名字，不能都叫 “Summary”。但 chapters章节 、 sections小节 等的标题可以重复。因此你可以每章都用一个名为 “Summary” 的小节，只要这些小节对应的节点名称各不相同即可。

  Node names节点名称 、 anchor names锚点名称 （见 @anchor: 定义任意交叉引用目标）和 float labels浮动标签 （见 @float [type][,label]: 浮动内容）必须全部唯一。

• 节点名称中可以包含 @-commands³。例如，在节点名中使用 @TeX{} 会输出 TeX 标志，和普通文本一样。交叉引用中也应使用和节点名中相同的 @TeX{} 。

  但有些命令不适合用在节点名里，比如环境命令（如 @quotation ）、整行作为参数的命令（如 @sp ）等。允许使用的命令完整列表，以及它们在 HTML 标识符和文件名中的展开规则，参见《HTML 交叉引用命令展开》。

• 节点名称不能以形如 (内容) 这样左括号开头、右括号结尾，因为这种语法用于指定外部手册。

• 不建议在节点名中可靠地使用句号、逗号或冒号，这些符号可能会让部分 Info 阅读器出错。 texi2any 默认会对有问题的节点名和标签进行转义，但部分 Info 阅读器不识别这种语法。转义会使名称周围出现 DEL 字符（‘CTRL-?’，字符码 127，常显示为 ^? ）。若要关闭转义，可将自定义变量 INFO_SPECIAL_CHARS_QUOTE 设为 ‘0’（见 Info 与纯文本自定义变量）。

  texi2any 会对节点名、菜单项和交叉引用中的这类问题发出警告。若不想显示警告，可将自定义变量 INFO_SPECIAL_CHARS_WARNING 设为 ‘0’（见 Info 与纯文本自定义变量）。

  如果你坚持在节点名中使用这些特殊字符，为了不混淆 Texinfo 处理器，仍必须对其进行转义：使用专用插入命令（见用 @comma{} 插入逗号 ‘,’）或 @asis (见 @asis )。示例：

  @node foo@asis{::}bar@comma{} baz
  

  下面是一个避免使用特殊字符的示例，本手册中有这样一节标题：

  @section @code{@@unnumbered}, @code{@@appendix}: Chapters with...
  

  但对应的节点名会去掉逗号和小标题：

  @node @code{@@unnumbered @@appendix}
  

• 节点名称区分大小写。

• ‘@node’ 行中名称前后的空格会被忽略；名称内部的多个空白符会合并为一个空格。例如：

  @node foo bar
  @node  foo bar,
  @node foo bar ,
  @node foo  bar,
  @node  foo  bar ,
  

  这些写法都定义同一个节点，即 ‘foo bar’。在菜单项中，节点名称内部应当只使用一个空格，否则某些版本的 Info 阅读器将无法找到该节点。

Texinfo 文件的第一个节点是 Top 节点，被包含的子文件除外（参见「包含文件」）。Top 节点应当包含一段简短的摘要和一个主菜单。关于 Top 节点的内容与示例，详见「‘Top’ 节点与主菜单」。应避免在 Top 节点之前、不属于任何节点的纯文本内容。如果存在这类文本，在 DocBook 输出中不会被生成。

下面是 Top 节点中应使用的节点指针说明：

• Top 节点（名称必须是 ‘top’ 或 ‘Top’）的 ‘Up’ 节点，应设为另一个文件中的某个节点名，该文件里有一个菜单能指向本文件。文件名写在括号内。

  通常，所有 Info 文件都通过一棵由多个目录构成的虚拟 Info 树提供访问。这种情况下，应使用 ‘(dir)’ 作为 Top 节点的上级；它指向 dir 文件中的顶层节点，该文件包含整个 Info 系统的主菜单。（每个存放 Info 文件的目录都应包含一个名为 dir 的文件。）

  这对 Info 格式没问题，但在 HTML 输出中，你可能希望 Top 节点的 Up 链接指向某个具体地址。例如，对 GNU 项目来说，合适的地址是 http://www.gnu.org/manual/（汇总大多数 GNU 手册链接的页面）；如果手册部署在 www.gnu.org 上，写成 /manual/ 会更好。这可以通过自定义变量 TOP_NODE_UP_URL 来指定（参见「HTML 文件名与链接自定义」），例如：

  $ texi2any --html -c TOP_NODE_UP_URL=/manual/ ...
  

• Top 节点的 ‘Prev’（上一节点）通常省略。
• Top 节点的 ‘Next’（下一节点）应设为文档的第一章。

关于如何在 Info 目录中安装 Info 文件的更多信息，参见「安装 Info 文件」。

通常最好 完全不写指针 ，让工具自动隐式定义，最终只需这样写：

@node Top

@top 是一个专用的章节结构化命令，你 只能 在 Texinfo 文件开头的 @node Top 行之后使用。

它的输出效果与 @unnumbered 相同（参见 @unnumbered, @appendix: 其他标记类型的章节）。在 LaTeX 中会使用 \part* 。

提升或降低章节层级时， @top 会被忽略。也就是说，它永远不会被降级，也没有内容可以被提升到它这一级（参见提升/降低节: @raisesections 和 @lowersections ）。

过去的惯例是将 ‘Top’ 节点用 @ifnottex 条件命令包裹，使其不会出现在打印版输出中（参见条件可见文本）。因此，以前的 ‘Top’ 节点通常这样写：

@ifnottex
@node Top
@top your-manual-title

very-high-level-summary
@end ifnottex

现在这已经 不再需要 了，因为目前 ‘Top’ 节点 永远不会 在打印版中输出，在 DocBook 格式中也不会输出。

节点可以包含 menus菜单 ，菜单里列出父节点下的 child nodes子节点 名称；例如，对应某一章的节点会包含该章下各小节的菜单。菜单让用户可以在 Info 输出中跳转到子节点。

此外，节点还包含指向其他节点的 node pointers节点指针 。‘Next’（下一）和 ‘Previous’（上一）指针将同一层级的节点连成一条链。顾名思义，‘Next’ 指向下一个节点，‘Previous’ 指向上一个节点。

一般来说，‘Next’ 和 ‘Previous’ 指向手册中 same hierarchical level同一层级 的节点，而不一定是 Texinfo 文件里物理上紧邻的下一个节点。在 Texinfo 文件中，紧跟在后面的节点往往是更低层级的节点 —— 例如，章节节点之后通常紧跟着小节节点。因此，同一章内所有同级小节节点会被链接在一起，链中的顺序与父章节菜单里子节点的顺序一致。每个子节点都会将父节点名称作为其 ‘Up’（上级）指针。

由于 ‘Top’ 节点是其所在层级的唯一节点，它的 ‘Next’ 指向紧随其后的第一个节点，这个节点几乎总是章节或同层级节点。这是 ‘Next’ 必须指向同层级节点规则的一个例外。

每个节点的 Info 和 HTML 输出都会包含指向 ‘Next’、‘Previous’、‘Up’ 节点的链接。HTML 输出还会分别使用 accesskey 属性，值为 ‘n’、‘p’、‘u’。这让浏览器用户可以使用快捷键（通常是 M-字母 ）进行导航，例如在节点内任意位置按 M-n 跳转到 ‘Next’ 节点。节点指针与菜单为 Info 文件提供结构，就像 chapters章节 、 sections小节 、 subsections子小节 为打印书籍提供结构一样。这两种结构在理论上是独立的；但在实际使用中，打印书籍的树形结构几乎总是同时用作节点与菜单结构，这样文档更容易阅读。

通常， 章节结构与节点结构是完全平行的 ：每一章、每一小节等都对应一个节点，并且节点的层级关系与章节结构完全一致。因此，如果一个节点是章节层级，它的子节点就是小节层级；同理，小节的子节点是子小节层级。

从技术上讲，是可以创建只包含其中一种结构、两种结构不平行，或其中某一种结构不符合常规的 Texinfo 文档的。但据我们所知，目前广泛使用的所有 Texinfo 手册都遵循这种常规的平行结构。

下图展示了一个包含三章的 Texinfo 文件，每章各包含两节。

图中 “root根节点” 位于顶部，“leaves叶子节点” 位于底部。这是此类结构图的常规绘制方式，呈现一棵倒置的树。正因如此，根节点被称为 ‘Top’（顶层）节点，而‘Up’（上级）节点指针会将你导向更靠近根节点的位置。

                         Top
                          |
        -------------------------------------
       |                  |                  |
    Chapter 1          Chapter 2          Chapter 3
       |                  |                  |
    --------           --------           --------
   |        |         |        |         |        |
Section  Section   Section  Section   Section  Section
  1.1      1.2       2.1      2.2       3.1      3.2

若使用显式指针（不推荐如此编写，此处仅作示例），用于开启第 2 章的完整命令如下：

@node     Chapter 2,  Chapter 3, Chapter 1, Top
@comment  node-name,  next,      previous,  up

该行 @node 指令表明：当前节点名为 “Chapter 2”， ‘Next’（下一个）节点为 “Chapter 3”，‘Previous’（上一个）节点为 “Chapter 1”，‘Up’（上级）节点为 “Top”。如果文档按层级结构组织，你可以（且应当）省略这些节点名称，但指针关联关系依然生效。

要在 Info 中跳转到 2.1 节和 2.2 节，需要在第 2 章内部定义菜单（详见菜单相关说明）。你应在 2.1 节开头前编写菜单，示例如下：

@menu
* Sect. 2.1::    本节描述。
* Sect. 2.2::    描述。
@end menu

2.1 节节点的自动指针对应写法：

@node     Sect. 2.1, Sect. 2.2, ,         Chapter 2
@comment  node-name, next,      previous, up

注意：此处不会生成 ‘Prev’（上一个）指针，因为在 2.1 节之前，同一层级不存在其他节点。

若使用显式指针，2.1 节节点可写作：

@node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
@comment  node-name, next,      previous,  up

在自动指针模式下，节点的 ‘Next’ 和 ‘Previous’ 指针会指向 同一层级 的其他节点（章与章、节与节之间）。如示例所示，使用显式指针时，指针也可指向其他位置 —— 本例中 ‘Previous’ 指针即指向上级。‘Up’ 指针通常指向上一层级节点（更靠近 ‘Top’ 节点）；‘Menu’（菜单）则指向下一层级节点（更靠近叶节点）。（ cross-reference交叉引用 可指向任意层级节点，详见交叉引用相关说明。）

从技术上讲，显式节点指针可跳转到任意节点，不受文档结构限制，甚至可跳转到其他 Info 文件中的节点。但如果 ‘Next’、‘Previous’、‘Up’ 指针指向的节点与逻辑上的下一个、上一个、上级节点不对应，会给读者带来极大困惑。

按照惯例， @node 指令与章节结构化指令会按此顺序配合使用，其后常紧跟索引指令。（如上例所示，可在 @node 行后添加注释行，用于标注显式指针各自的含义。）Texinfo 处理器会通过这一结构，识别节点与分节指令之间的关联关系。

下面是本手册中 “结束 Texinfo 文件” 一章的开头部分，展示了 @node 行、 @chapter 行与索引行的连用格式：

@node Ending a File
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

你可以在 @node 行之后使用 @nodedescription 命令，为节点的用途提供一段简短描述。这类描述可用于对节点名称本身的信息进行补充或扩展。

你也可以使用 @nodedescriptionblock 环境来编写节点描述，这对于篇幅较长的描述会更方便。

texi2any 工具在为 Info 格式（以及可选的 HTML 格式）输出菜单时，会使用你通过这些命令提供的内容。如果 texi2any 是 自动生成菜单 ，或者在显式的 @menu 块中没有为菜单项提供描述，它就会使用节点对应的这段描述。（见「菜单」章节）

以下是这些命令的使用示例：

@node Tools
@chapter 工具

本章介绍你可以使用的各种工具。

@node Screwdrivers
@nodedescription 一字头与十字头螺丝刀。
@section 螺丝刀

本节介绍螺丝刀。

@node Drills
@nodedescriptionblock
使用电动螺丝刀、手电钻、组合电钻、冲击起子、锤钻、破碎机和拆除钻在物体上打孔。
@end nodedescriptionblock
@section 电钻

本节介绍电钻。

在 Info 输出中， texi2any 会为 ‘Tools’节点生成如下菜单：

* Menu:

* 螺丝刀::            一字头与十字头螺丝刀。
* 电钻::              使用电动螺丝刀、手电钻、组合电钻、冲击起子、
                      锤钻、破碎机和拆除钻在物体上打孔。

Menus菜单 包含指向 子节点 的指针。在 Info 输出中，你通过菜单跳转到这些子节点。 texi2any 可以在 HTML 输出中生成菜单，但默认不开启（详见《HTML 输出结构定制》， FORMAT_MENU ）。菜单在印刷版手册或其他输出格式中不起作用。

当节点后跟随分节指令、未使用显式的 @menu 块、且使用自动指针时， texi2any 在输出 Info 或带菜单的 HTML 时会 自动生成菜单 。

通常让 texi2any 自动生成菜单会更方便，这样在你添加、删除或移动节点时，就不需要手动维护 Texinfo 源码中的菜单块。对于常见的、按层级组织的手册（节点对应分节指令、且省略节点指针），只有当你需要精确控制 Info 中菜单的内容与格式时，才需要手动编写菜单。

• 编写菜单
• 菜单示例
• 菜单位置
• 菜单的组成部分
• 简洁化菜单项
• 引用其他 Info 文件

一个 Texinfo 文件通常像书籍一样被组织为 chapters章 、 sections节 、 subsections子节 等层级。这种结构可以可视化为一棵树（更准确地说是一棵 倒置的树 ）：根在顶部，各个层级分别对应章、节、子节、子子节。

下图展示了一个包含三章、每章各含两节的 Texinfo 文件结构：

                         Top
                          |
        -------------------------------------
       |                  |                  |
    Chapter 1          Chapter 2          Chapter 3
       |                  |                  |
    --------           --------           --------
   |        |         |        |         |        |
Section  Section   Section  Section   Section  Section
  1.1      1.2       2.1      2.2       3.1      3.2

在具有这种结构的 Texinfo 文件中，第 2 章的开头写法如下：

@node    Chapter 2
@chapter Chapter 2

为便于举例，下面是 使用显式节点指针 时的写法：

@node    Chapter 2,  Chapter 3, Chapter 1, Top
@chapter Chapter 2

章节结构化命令将在后续小节中介绍； @node 命令已在前一章说明（见节点）。

章节结构化命令分为四组，每组都包含对应 chapters章 、 sections节 、 subsections子节 、 subsubsections子子节 层级的结构化命令：

• 类 @chapter 命令与类 @appendix 命令：在文档正文和目录中均生成带编号或字母标识的条目。
• 类 @unnumbered 命令：在文档正文和目录中均生成无编号的条目。 @top 命令属于本组，有特殊用途（参见 @top 分节命令）。无编号节是文档结构的正常组成部分。
• 类 @heading 命令：生成简单的无编号标题，不出现在目录中，不与节点关联，也无法被交叉引用。这类标题命令不会另起一页。

在印刷版输出中，章节结构化命令会在文档中生成标题。如果使用了 @setchapternewpage 命令， @chapter 、 @unnumbered 和 @appendix 命令会在印刷手册中另起一页；而 @heading 类命令则不会。参见 @setchapternewpage: 章节前的空白页。

在 Info 和纯文本输出中，这类命令会让标题单独占一行，并在下方用一行 ASCII 字符（‘*’、‘=’ 等）下划线。例如：

5 Chapter Structuring
*********************

同一层级的所有命令使用相同的下划线字符。例如，章级命令 @chapter 、 @appendix 、 @unnumbered 和 @chapheading 使用相同的下划线。

在 HTML 中，章级命令默认生成 <h2> 级标题（可通过 CHAPTER_HEADER_LEVEL 自定义变量控制，参见特定输出的 HTML 自定义）。其他层级命令对应的标题元素级别也会相应调整。

在 DocBook 输出中，会使用对应层级的元素。生成的元素会包含其后所有同级或更高级别命令之前的所有节。例如， @chapter 会生成 <chapter> 元素，并包含该章内所有节与子节。

下表为汇总：

                                                          No new page
Numbered        Unnumbered            Lettered/numbered   Unnumbered
In contents     In contents           In contents         Not in contents
                @top                                      @majorheading
@chapter        @unnumbered           @appendix           @chapheading
@section        @unnumberedsec        @appendixsec        @heading
@subsection     @unnumberedsubsec     @appendixsubsec     @subheading
@subsubsection  @unnumberedsubsubsec  @appendixsubsubsec  @subsubheading

@chapter 用于标识文档中的 章节 —— 它是常规文档结构层级中的最高级别。将该命令写在行首，并在同一行后跟章节标题。章节会 自动编号 ，从 1 开始。

例如，本手册当前这一章的标题为 “Chapter Structuring”(章节结构化)，对应的 @chapter 行如下所示

@chapter Chapter Structuring

使用 @unnumbered 命令开始一个 章级元素 ，使其显示时不带任何形式的章节编号。使用 @appendix 命令开始一个附录，附录以字母（‘A’、‘B’……）而非数字标识；附录同样属于章级结构。

与 @chapter 一样，将 @appendix 或 @unnumbered 命令写在行首，并在同一行跟上标题。

Texinfo 还提供了一个 @centerchap 命令，用法与 @unnumbered 类似，但会在印刷版和 HTML 输出中将参数 居中显示 。Texinfo 通常不提供这类排版选择， 建议不要使用该命令 ，因为它可能在后续版本中被移除。

对于 @unnumbered ，如果其关联节点的名称是以下英文单词之一（不区分大小写）：

Acknowledgements  Colophon  Dedication  Preface
致谢、出版声明、献词、前言

则 DocBook 输出会使用对应的专用标签（如 <preface> ），而非默认的 <chapter> 。 @unnumbered 自身的参数可以是任意内容，并会照常作为元素标题输出。

@majorheading 和 @chapheading 命令会在文档正文中生成 类似章节的标题 。

但是，这两个命令 都不会在目录中生成条目 ，并且都不会让 TeX 在印刷版手册中另起新页。

在 TeX 中， @majorheading 命令在标题前生成的垂直空白比 @chapheading 更大，除此之外两者效果相同。

在其他输出格式中， @majorheading 和 @chapheading 生成的效果与 @chapter 类似。区别在于它们 没有编号 ，也 不与节点关联 。参见 @chapter: 章节结构化。

@section 命令用于标识 section within a chapter unit章内部的节 ，无论该章是由 @chapter 、 @unnumbered 还是 @appendix 创建，都会遵循对应章级命令的编号规则。因此：

• 在编号为「1」的 @chapter 章节中， sections节 会编号为「1.1」「1.2」等；
• 在标识为「A」的 @appendix 附录章中， sections节 会编号为「A.1」「A.2」等；
• 在 @unnumbered 无编号章中， sections节 不会编号 。

创建 section节 的方式：将 @section 命令写在行首，并在同一行后面写上节的标题。例如：

@section This is a section

节标题会出现在目录中。

@unnumberedsec 、 @appendixsec 和 @heading 命令分别是 @section 命令对应的无编号版、附录版、标题版（见上一节）。

在普通情况下，并不需要使用 @unnumberedsec 和 @appendixsec ，因为在 @unnumbered 和 @appendix 章节内部，直接使用 @section 即可；同样可参见上一节。

@unnumberedsec

@unnumberedsec 命令可用于无编号章节、普通章节或附录内部，用来生成 无编号的节 。

@appendixsec

@appendixsection

@appendixsection 是 @appendixsec 命令的完整拼写形式，二者是 同义词 。

按照惯例， @appendixsec 或 @appendixsection 命令只在附录内部使用。

@heading

你几乎可以在任何位置使用 @heading 命令，生成节级别的标题，且不会出现在目录中。 @heading 系列命令可以出现在大多数环境内部，但不允许放在另一个命令的参数中等无效位置。

subsections子节 与 sections节 的关系，就如同 sections节 与 chapters章 的关系（参见 @section: 章节之下的节）。示例：

@subsection This is a subsection

子节标题会被列入目录。

@unnumberedsubsec 、 @appendixsubsec 和 @subheading 命令分别是 @subsection 命令对应的无编号版、附录版、标题版。（参见 @subsection: 节之下的子节。）

在普通情况下，并不需要使用 @unnumberedsubsec 和 @appendixsubsec ，因为在 @unnumbered 和 @appendix 章节的节内部，直接使用 @subsection 即可。（参见 @section: 章节之下的节。）

@subheading 命令生成类似子节的标题，但 不带编号，且不出现在目录中 。

同样地， @unnumberedsubsec 生成无编号的子节式标题， @appendixsubsec 生成带字母与数字编号的子节式标题；这两个命令生成的标题都会出现在目录中。

Texinfo 中第四级、也是最低一级的分节命令是 ‘subsub’ 系列命令。它们包括：

@subsubsection

子子节与子节的关系，如同子节与节的关系。（参见 @subsection: 节之下的子节。）子子节标题会出现在目录中。

@unnumberedsubsubsec

无编号子子节的标题会出现在目录中，但不带编号。除此之外，与普通子子节相同。

@appendixsubsubsec

按照惯例，附录系列命令仅用于附录中，并会自动使用合适的字母与数字编号。它们也会出现在目录中。

@subsubheading

@subsubheading 命令可用于任何需要一个小型标题、且该标题 不出现在目录中 的位置。

与子节的用法一样，通常情况下不需要使用 @unnumberedsubsubsec 和 @appendixsubsubsec ，因为在无编号章节和附录章节的子节内部，直接使用 @subsubsection 即可。（参见 @section: 章节之下的节。）

最后一个分节命令是 @part ，用于标记手册中的 part部分 ，也就是一组章节或（较少见的）附录。它的行为与其他分节命令差异很大，以适配书籍中 “parts”(部分) 的常规用法。

@part 不与 @node 命令关联。只需在文档中需要标记该部分开始的位置，将命令单独写在一行，并带上部分标题即可。例如：

@part Part I:@* The beginning

从示例可以看出， @part 的内容 不会自动编号或标注 ，文本会原样输出。

由于部分不与节点关联， @part 行后 不能跟随普通文本 。要得到正确输出，其后必须紧跟 章级命令 （及其节点）。延续上面的示例：

@part Part I:@* The beginning

@node Introduction
@chapter Introduction
...

在 TeX 输出中：

• @part 的内容会出现在普通目录和简目里，但不带页码（符合常规排版惯例）。
• 文档正文中会输出一张部分页，只显示 @part 内容。
• 示例中的 @* 会在部分页产生换行，但在目录里会替换为空格。
• 无论章节分页如何设置，部分页总会强制出现在奇数页（右侧页）。

在 LaTeX 输出中，@part 会被转换为 \part。

在 TeX 输出中:

• @part 的内容会同时出现在常规目录和简缩目录中（参见「生成目录」），但不显示页码（这是常规排版惯例）。
• 此外，文档正文中会输出一张 “part page部分页”，页面上只显示 @part 的内容。
• 在上面的示例里， @* 会在部分页中产生换行（但在目录中会被替换为空格）。
• 无论章节分页如何设置，这张部分页都会被强制放在奇数页（右侧页）。参见 @setchapternewpage: 章节前的空白页。
• 在 LaTeX 输出中，@part 会被输出为 \part 。

在 HTML 输出中， @part 内容同样会出现在目录里。标题会作为后续章节或附录节点的一部分，出现在正文里。

在 DocBook 输出中， <part> 元素会包含其后所有章节，直到下一个 <part> 。包含章节的 <part> 在遇到附录时也会自动结束。

在 Info 和纯文本输出中， @part 不起作用。

在提升或降低节级别时， @part 会被忽略（见下一节）。也就是说，它永远不会被降级，也没有内容可以升级到它这一级。

@raisesections 和 @lowersections 命令会 隐式地提升或降低 后续章节、节以及其他分节命令的层级（部分 @part 除外）。

也就是说：

• @raisesections 命令会将 */sections节/ 变成 chapters章 、 subsections子节 变成 sections节 * ，依此类推。
• 反之， @lowersections 命令会将 章变成节、节变成子节 ，依此类推。

因此， @lowersections 可以抵消 @raisesections 的效果，反之亦然。

在实际使用中，通常只对 大块内容 提升或降低层级，一般用于外部文件。你可以用 @lowersections ，把一个独立完整的 Texinfo 文件，作为 内部被包含文件 嵌入到另一个 Texinfo 文件中（参见「包含文件」）。典型用法如下：

@lowersections
@include somefile.texi
@raisesections

（如果不加最后的 @raisesections ，主文件中 所有后续的节都会被降级 。）

如果被降级的包含文件中有 @top 节点，你需要用标记做 条件包含 （参见 @set 和 @value ）。

最终生成的菜单 必须考虑层级升降 ，因此在文档中随意到处使用 @raisesections 和 @lowersections 很可能导致错误（除非文档中的菜单全部是自动生成的）。

重复使用这些命令会逐级继续提升或降低层级。如果试图提升到比章（chapter）更高的级别，效果仍等同于章命令；如果试图降低到比子子节（subsubsection） 更低的级别，效果仍等同于子子节命令。此外，被降级的子子节与被提升的章，无法与 texi2any 的隐式节点指针自动判定功能兼容，因为菜单结构无法被正确表示。

@raisesections 和 @lowersections 命令 各占一行 书写。

共有三种不同的交叉引用命令：

@xref

用于以 Info 格式交叉引用 开头 一个句子，在 Info 中显示为‘*Note name: node.’，在其他输出格式中显示为 ‘See …’。

@ref

常用于句子 内部 或更常见的是句子 末尾 ；在 Info 中生成 ‘*note name: node.’，在其他格式中只显示引用内容， 不带前面的 ‘See’。

@pxref

用于括号内、句子末尾，或在标点符号之前做补充引用。在 Info 中输出以小写 ‘*note’ 开头，在其他格式中以小写 ‘see’ 开头。（这里的 ‘p’ 代表 ‘parenthesis’，即 “括号”。）

此外，还有一些用于引用 Texinfo 系统 外部文档 的命令：

• @cite 命令用于引用书籍和手册。
• @url 用于生成 URL，例如引用万维网上的某个页面。

交叉引用命令只需要 一个必选参数 ，即它所指向的节点名称。一条交叉引用命令最多还可以包含 四个额外参数 。完整的五参数交叉引用模板如下：

@xref{node-name, online-label, printed-label, manual-name, printed-manual-title}

交叉引用的五个可能参数分别是：

• node-name节点 或 anchor-name锚点名称 。 这是交叉引用跳转的目标位置。在印刷版文档中，只有 同一文档内 的引用才会根据节点位置给出页码。使用 @node 定义节点（参见 编写 @node 行）、 @anchor （参见 @anchor: 定义任意交叉引用目标）或带标签的 @float （参见 @float [type][,label]: 浮动内容）来指定目标。该参数为 必选 （引用整本手册时除外）。

  交叉引用中书写的节点名称，必须与 @node 行 完全一致 （包括大小写），否则处理工具可能无法找到该引用。

• 在线输出标签。通常省略。若省略，则优先使用第三参数（主题描述）；若该参数也省略，则直接使用节点名称。
• 印刷输出标签。通常为章节标题或主题名称，在印刷版手册中作为引用名称。若省略，则使用节点名称。
• 被引用手册名称。当引用目标位于 当前手册之外 、属于另一个 Texinfo 文件时使用。
• 被引用印刷版手册标题。对应另一个 Texinfo 文件中被引用手册的印刷版标题。

分隔参数的逗号 前后的空白会被忽略 。如果需要在参数内部使用逗号，需用 @comma{} （参见 用 @comma{} 插入逗号‘,’）。

后续章节将分别介绍一参数、二参数、三参数、四参数、五参数的交叉引用用法。

使用 TeX 处理时，对于 同一手册内 的交叉引用，页码后会 自动添加逗号 ，除非参数的右花括号后面紧跟非空白字符（如逗号或句号）。这样你可以控制在其他输出格式中是否显示该逗号。例如：

@xref{Another Section} for more info

• TeX 输出：‘See Another Section, page ppp, for more info’
• Info 输出：‘*Note Another Section:: for more info’

如果不希望自动生成逗号，可以在参数后使用 ‘@:’ 等命令。例如：‘ @xref{Hurricanes}@: --- for the details ’会生成：

See Hurricanes, page ppp —- for the details

而不是：

See Hurricanes, page ppp, —- for the details

当交叉引用文本（以及节点名、菜单项）中存在可能干扰 Info 格式解析的可疑结构时， texi2any 会给出警告并保护相关名称。参见 Info 节点名称约束。

@xref 最简单的形式只接受一个参数，即同一个 Texinfo 文件中另一个节点的名称。

例如：

@xref{Tropical Storms}.

在 Info 格式中生成：

*Note Tropical Storms::.

在印刷版手册中生成：

See Section 3.1 [Tropical Storms], page 24.

在印刷版手册中。

使用两个参数时，第二个参数会作为 online-label在线输出 的显示标签。

格式如下：

@xref{node-name, online-label}.

示例：

@xref{Electrical Effects, Lightning}.

在 Info 格式中会生成：

*Note Lightning: Electrical Effects.

在印刷版手册中会生成，其中会显示节点名称：

See Section 5.2 [Electrical Effects], page 57.

交叉引用的第二个参数与节点名称遵循相同的约束条件。在此场景中可能引发问题的字符是 冒号 。详见《Info 节点名称约束》。

第三个参数会 替换印刷版输出中的节点名称 。第三个参数应当是印刷版中章节的名称，或是该章节所讨论主题的表述。

格式如下：

@xref{node-name, online-label, printed-label}.

示例：

@xref{Electrical Effects, Lightning, Thunder and Lightning}, for details.

在 Info 格式中生成：

*Note Lightning: Electrical Effects, for details.

在印刷版手册中生成：

See Section 5.2 [Thunder and Lightning], page 57, for details.

如果提供了第三个参数，而第二个参数为空，那么第三个参数会 同时充当在线标签和印刷标签 。（注意：两个连续的逗号用于标记第二个参数为空。）

@xref{Electrical Effects, , Thunder and Lightning}, for details.

在 Info 格式中生成：

*Note Thunder and Lightning: Electrical Effects, for details.

在印刷版手册中生成：

See Section 5.2 [Thunder and Lightning], page 57, for details.

交叉引用的第三个参数与节点名称遵循相同的约束条件。在此场景中可能引发问题的字符是 冒号 。详见《Info 节点名称约束》。

实际使用建议：

• 如果节点名称与章节标题相同（或基本相同），通常只写第一个参数即可。
• 如果节点名称与标题不同，则只需要写第一个和第三个参数。

Texinfo 提供了一个设置，可以让交叉引用 默认使用章节标题而非节点名称 （显式指定的第三个参数仍然优先）：

@xrefautomaticsectiontitle on

通常这行代码会写在文档开头，作用于整个手册。但你也可以按需关闭（ @xrefautomaticsectiontitle off ），例如当你引入其他没有合适章节名称的子文档时。

该设置同样适用于 HTML 中的节点标题：如果开启 @xrefautomaticsectiontitle ，在可能的情况下，节点标题会使用 章节名称 而非节点名称。

在交叉引用中，第四个参数用于指定 另一本手册 的名称（与当前引用所在文件不同），第五个参数则指定该手册作为印刷版时的标题。

完整模板为：

@xref{node-name, online-label, printed-label, manual-name, printed-manual-title}

@xref {节点名，在线标签，印刷标签，手册名，印刷手册标题}

例如：

@xref{Electrical Effects, Lightning, Thunder and Lightning, weather, An Introduction to Meteorology}.

在 Info 格式中会生成如下输出：

*Note Lightning: (weather)Electrical Effects.

可以看到，手册名被放在圆括号内，并置于节点名之前。在 HTML 中，手册名和节点名用于构造超链接 URL（参见 HTML 交叉引用），而链接文本则基于标签生成。

在印刷版手册中，该引用效果如下：

See section “Thunder and Lightning” in An Introduction to Meteorology.

印刷手册的标题会以 @cite 格式排版；由于引用另一本手册时无法预知页码，因此引用中不包含页码。

下一种情况：使用长格式 @xref 时，你常常会省略第二个参数。此时，第三个参数（主题描述）会作为在线格式中的交叉引用名称。

例如：

@xref{Electrical Effects, , Thunder and Lightning, weather, An Introduction to Meteorology}.

在 Info 中生成：

*Note Thunder and Lightning: (weather)Electrical Effects.

在印刷版手册中生成：

See section “Thunder and Lightning” in An Introduction to Meteorology.

下一种情况：如果另一本手册中的 节点名与章节标题相同 ，你也可以省略章节标题。此时节点名将同时用于两处。

例如：

@xref{Electrical Effects,,, weather, An Introduction to Meteorology}.

在 Info 中生成：

*Note (weather)Electrical Effects::.

在印刷版手册中生成：

See section “Electrical Effects” in An Introduction to Meteorology.

一般来说，没有理由只提供手册名参数而不提供印刷手册标题参数，除非不生成印刷版手册。你也可能需要引用 同一本印刷手册内 的另一手册文件 —— 当多个 Texinfo 文件被合并到同一本印刷手册，但在其他输出格式中可生成独立文件时。这种情况下，只需指定第四个参数，无需第五个。如果缺少印刷手册标题参数，印刷输出中将直接使用手册名代替。

只提供印刷手册标题参数而不提供在线手册名参数，基本没有意义，除非该 Texinfo 源文件 只用于生成印刷版手册 。在线格式中的结果取决于具体格式，可能会出现空手册名，或以类似印刷版的格式引用该手册。

最后，也允许只保留第四、第五个参数，省略其余所有参数，用于整体引用另一本手册。详见下一节。

通常情况下，交叉引用 必须指定一个节点 。但你经常会需要 整体引用另一本手册 ，而不是其中某个特定章节。这种情况下，指定章节名是多余且分散注意力的。

因此，在对其他手册进行交叉引用时（参见 带四个和五个参数的 @xref ），如果第一个参数是 ‘Top’（必须这样大写）或者完全省略，并且第三个参数也省略，那么印刷版输出中将 不包含节点或章节名称 。（如果显式写了‘Top’，Info 格式输出会包含它。）例如：

@xref{Top,,, make, The GNU Make Manual}.

会生成：

*Note (make)Top::.

以及印刷版：

See The GNU Make Manual.

无论是否显式指定‘Top’节点，Info 阅读器都会跳转到该手册的顶层节点。

另外一种（也是历史上常用的）写法是：指定‘Top’节点，并为 @xref 的第三个参数提供合适的内容，以此来引用整本手册。用这种写法引用《GNU Make 手册》可以这样写：

@xref{Top,, Overview, make, The GNU Make Manual}.

它在 Info 中生成：

*Note Overview: (make)Top.

在印刷手册中生成：

See section “Overview” in The GNU Make Manual.

在这个例子里，Top 是第一个节点的名称，Overview 是手册第一章的名称。印刷手册中第一章并没有通用的命名规范，这只是 Make 手册恰好使用的名称。正是因为首节名称不统一，所以 在整体引用手册时，省略第三个参数是更推荐的做法 。

@xref 命令用于在句子开头生成交叉引用。有关 @xref 的使用示例，请参见前面的章节。

@ref 与 @xref 几乎完全相同，唯一区别是： @ref 不会在输出中生成 ‘See’ 字样，只输出引用本身。这使得它适合用在句子末尾。

例如：

For more information, @pxref{This}, and @ref{That}.

在 Info 格式中生成：

For more information, *note This::, and *note That::.

在印刷版中生成：

For more information, see Section 1.1 [This], page 1, and Section 1.2 [That], page 2.

使用 @ref 命令时，作者可能会写出适合印刷手册、但在 Info 格式中显得生硬的句子。请记住，你的读者可能同时使用印刷版和 Info 等其他格式。例如：

Sea surges are described in @ref{Hurricanes}.

在印刷版中显示正常：

Sea surges are described in Section 6.7 [Hurricanes], page 72.

但在 Info 中读起来会很别扭，因为 “note” 在这里会被当作动词理解：

Sea surges are described in *note Hurricanes::.

括号内引用命令 @pxref 与 @xref 几乎完全相同，但它 最适合用在括号内部 。该命令与 @xref 的区别在于：输出的引用词是小写的 ‘see’（参见），而不是大写的 ‘See’（参见）。在 Info 格式中则输出 ‘*note’。

当只带一个参数时，括号内的交叉引用示例如下：

... storms cause flooding (@pxref{Hurricanes}) ...

在 Info 中生成：

... storms cause flooding (*note Hurricanes::) ...

在印刷手册中生成：

… storms cause flooding (see Section 6.7 [Hurricanes], page 72) …

在旧版 Texinfo 中，不允许在 @pxref 后面直接加标点，因此它只能用在右括号之前。现在这一限制已取消。 @pxref{节点名} 的效果等价于 ‘see @ref{node-name}’。不过在很多场景下， 后者更推荐 ，因为这样能让 Info 格式的输出里清晰地显示出 “see” 一词。

@anchor 用于在文档中标记一个 anchor锚点 ，使其可以像节点一样被交叉引用。你可以使用 @anchor 命令创建锚点，并将标签名放在大括号内作为参数。例如：

This marks the @anchor{x-spot}spot.
...
@xref{x-spot,,the spot}.

会生成：

This marks the spot.
...
See [the spot], page 1.

可以看到， @anchor 命令 本身不会产生任何输出 。上面的例子在单词 ‘spot’ 之前定义了一个名为 ‘x-spot’ 的锚点，之后可以用 @xref 或其他交叉引用命令来指向它，如下所示（参见 “交叉引用”）

最佳实践 ：将 @anchor 命令放在 你希望引用的位置之前 ，这样读者跳转到锚点时，视线能直接落在正确内容上。为了源码可读性，你也可以把 @anchor 单独放在一行。 @anchor 之后的空白（包括换行）会被忽略。

命名与使用约束

• 锚点名、节点名、浮动体标签 不能冲突 。
• 锚点、节点、浮动体标签在某些处理中是类似的：例如 goto-node 命令既可以接受节点名，也可以接受锚点名。（参见 Info 中的 “跳转到节点”。）
• 锚点名和浮动体标签也可能出现在菜单（参见 “菜单”）和节点方向指针（参见 “编写 @node 行”）中，但 不推荐这样使用 。

锚点名在可包含的字符方面，与节点名遵循相同的约束规则（参见 Info 节点名称约束）。

兼容建议

由于锚点和节点在功能上是等效的，当你 删除或重命名某个节点 时，最好用旧名称定义一个 @anchor 。这样一来，其他 Texinfo 手册或外部网页指向该旧节点的链接仍然可以正常工作

@link 会在支持的输出格式中生成一个纯超链接，包括 HTML、DocBook、LaTeX 以及在线版 PDF。其格式模板为：

@link{node-name, label, manual-name}

node‑name 是目标节点或锚点的名称。 label 和 manual‑name 可以省略其中一个，也可以两个都省略。如果提供了 label ，则它会作为链接显示文本。 manual‑name 是目标所在的外部手册名称；如果未提供，则引用指向当前手册。

@link 的输出与 @ref 类似，区别在于：它 不会在 Info 或印刷版输出中为链接文字添加额外标记 ，不会显示为典型的交叉引用样式。

使用 @link 时需要注意：不要用它生成读者浏览手册所 必需 的导航链接，因为在某些输出格式中这类链接不会生效。 @link 最适合用于添加 非必需、但更方便 的辅助链接。例如，可在代码示例中用 @link 引用程序库中某个符号的文档。

@inforef 用于创建指向 Info 文档的交叉引用 —— 即使是从印刷版手册中引用。该命令最初用于并非由 Texinfo 源码生成的 Info 文件。

此命令现已废弃，不应再使用 。它除了几乎没有实际用途外，类似的输出效果完全可以通过 @xref 、 @ref 或 @pxref 实现：只需将 Info 文件名作为第四个参数，且不提供第五个参数即可。

该命令接受两个或三个参数，顺序如下：

• 节点名
• 交叉引用名称（可选）
• Info 文件名

模板为：

@inforef{node-name, cross-reference-name, info-file-name}

@url 用于生成对统一资源定位符（URL）的引用。它有一个必选参数，即 URL 本身，以及两个可选参数，用于控制显示的文本。在 HTML 和 PDF 输出中， @url 会生成可点击的链接。（若仅需标注 URL 而不生成可点击链接，请使用 @indicateurl ，参见 @indicateurl {uniform-resource-locator}。）

@uref 是 @url 的同义词。（最初， @url 的作用等同于 @indicateurl ，而必须使用 @uref 才能生成有效链接；但实际使用中 @url 几乎总是被误用，因此我们修改了它的含义。）

如果指定第二个参数，该参数将作为显示文本（默认为 URL 本身）；在 HTML 以外的输出格式中，除了这段文本外，还会额外输出 URL。

如果指定第三个参数，则使用该参数作为显示文本，且在任何格式中都不再输出 URL。这在文本本身已具备足够引用信息时非常有用，例如在手册页中。另外，如果提供了第三个参数，第二个参数会被忽略。

• @url 示例
• URL 换行
• @url 的 PDF 输出格式

@cite 命令用于标注 没有配套 Info 文件的书籍 名称。例如，我们可以这样引用： 一本书 。

该命令在印刷版手册中会使用 斜体 ，在 Info 文件中会生成 引号 。

如果一本书是用 Texinfo 编写的， 更推荐使用交叉引用命令 ，因为读者在 Info 中可以直接点击跳转。参见 @xref 。

默认情况下，PDF 输出中的 URL 和交叉引用链接以 黑色 显示。但在极少数情况下，你可能想像网页一样，用不同颜色突出显示这类 “可点击” 链接。Texinfo 提供了专用于 PDF 的颜色设置选项， 必须 在 @tex 内部使用：

@tex
\global\def\linkcolor{1 0 0}  % 红色
\global\def\urlcolor{0 1 0}   % 绿色
@end tex

\urlcolor 用于修改 @url 输出内容的颜色（包括实际 URL 与任何文本标签）。 \linkcolor 用于修改指向节点等交叉引用的颜色。两者相互独立。

给出的三个数值必须是 0 到 1 之间的数字，分别表示红、绿、蓝的分量。

这些定义只在使用 pdfTeX 生成 PDF 时生效，通过其他方式（如 TeX→DVI→PDF）从 Texinfo 生成 PDF 时无效。因此，你可以像上面那样在 @tex 中无条件设置，生成 DVI 时这些命令会被自动忽略。

我们 不建议为了好看而随意加颜色 ；除非有明确需求，否则最好不使用。

Texinfo 提供了多种命令，用于明确一段文本所指代的对象类型。例如，电子邮件地址使用 @email 标记；这样一来，在支持的输出格式中，就可以生成可直接发送邮件的活跃链接。如果电子邮件地址仅被标记为 “以打字机字体显示”，就无法实现这一功能。

• 高亮命令的实用价值
• @code {spmle-code}: 代码示例
• @kbd {keyboard-characters}: 键盘输入内容
• @key {key-name}: 按键名称
• @samp {text}: 示例文本
• verb {chartextchar}: 原样文本
• @var {metasyntactic-variable}: 元语法变量
• @env {environment-variabl}: 环境变量
• @file {file-name}: 文件名
• @command {command-name}: 命令名称
• @option {option-name}: 命令行选项
• @dfn {term}: 被定义的术语
• @abbr {abbreviation [, meaning ]}: 缩写
• @acronym {acronym [, meaning ]}: 大写缩写词
• @indicateurl {{uniform-resource-locator}: 无功能的URL
• @email {email-address [, displayed-text ]}: 邮箱地址

通常，Texinfo 会通过切换字体，来根据文本所属类别标记文字，例如 @code 命令。大多数情况下，这是标记文字的最佳方式。但有时，你只想 强调文本 ，而不指明其类别。为此，Texinfo 提供了两个命令。

此外，Texinfo 还有若干用于指定输出字体的命令。这些命令在 Info 格式中无效，且其中只有 @r 命令有常规用途。

• @emph {text} 与 @strong {text}：斜体强调 / 粗体强调
• @sc {text}: 小型大写字体
• 印刷用字体设置

以下是用于包裹文本块（也称为环境）的命令汇总。后续章节会对它们做更详细的说明。

@quotation

标记需要引用的文本。文本会自动换行、两侧缩进，默认以罗马字体显示。

@indentedblock

与 @quotation 类似，但文本仅左侧缩进。

@example

用于展示代码、命令等内容。文本以等宽字体显示，会缩进但不会自动换行。

@lisp

与 @example 类似，专门用于展示 Lisp 代码。文本以等宽字体显示，会缩进但不会自动换行。

@verbatim

标记需要原样输出的文本；不进行任何字符替换，所有命令均失效，直到遇到 @end verbatim 。文本以等宽字体显示，不缩进、不自动换行。多余空格与空行有效，制表符会展开。

@display

展示说明性文本。文本会缩进但不自动换行，不指定字体（默认使用罗马字体）。

@format

与 @display 类似（文本不自动换行、不指定字体），但不缩进。

@smallquotation

@smallindentedblock

@smallexample

@smalllisp

@smalldisplay

@smallformat

这些 @small... 系列命令与普通版功能一致，仅在支持的环境中以更小字号输出文本。

@flushleft

@flushright

文本不自动换行，分别左对齐或右对齐。

@raggedright

文本会自动换行，但仅左对齐，右侧边缘不齐。

@cartouche

通过绘制圆角方框高亮文本，常用于示例或引用。

@exdent 命令用于在上述结构中取消当前行的缩进。

@noindent 命令可用于上述结构之后（或任意段落开头），避免后续文本作为新段落自动缩进

引用文本的处理方式与普通文本相同（常规字体、自动换行），但有以下区别：

• 左页边距向页面中心靠近，使整个引用块缩进；右页边距也可能向中心靠近
• 段落首行缩进不超过其他行

• 可使用 @author 命令指定引用的作者

  这是写在 @quotation 命令与 @end quotation 命令之间的文本示例。 @quotation 命令通常用于标记从其他（真实或假设的）印刷作品中摘录的文本。

@quotation 命令需单独占一行，该行不会出现在最终输出中。使用单独一行、仅包含 @end quotation 的语句标记引用结束，该行同样不会出现在输出中。

@quotation 接受一个可选参数，写在命令所在行的剩余部分。如果存在该参数，会以粗体或其他强调样式显示在引用开头，并后跟冒号 ‘:’ 。示例：

@quotation Note
This is
a foo.
@end quotation

输出效果：

Note: This is a foo.

如果 @quotation 的参数是以下英文单词（不区分大小写）：Caution、Important、Note、Tip、Warning

则 DocBook 输出会使用对应的特殊标签（如 <note> ），而非默认的 <blockquote> 。

如果在 @quotation 块内使用 @author 命令指定了引用作者，会在引用末尾单独一行显示作者名：

@quotation
People sometimes ask me if it is a sin in the Church of Emacs to use
vi.  Using a free version of vi is not a sin; it is a penance.  So happy
hacking.

@author Richard Stallman
@end quotation

输出效果：

People sometimes ask me if it is a sin in the Church of Emacs to use vi. Using a free version of vi is not a sin; it is a penance. So happy hacking.

@indentedblock 环境与 @quotation 类似，区别在于：文本 仅在左侧缩进 （且没有用于标注作者的可选参数）。因此，文本字体保持不变，内容会照常自动换行，但 左侧页边距会向内缩进 。

示例：这是一段写在 @indentedblock 命令与 @end indentedblock 命令之间的文本示例。 @indentedblock 环境中可以包含任意文本或其他所需命令。

其在 Texinfo 源文件中的写法如下：

@indentedblock
This is an example ...
@end indentedblock

@example 环境用于标明不属于正文的 计算机输入或输出内容 。如果需要在句子中嵌入代码片段，请改用 @code 命令或同类命令（参见 @code {sample-code}）。

@example 命令需单独占一行，使用 @end example 标记块结束。例如：

@example
cp foo @var{dest1}; \
 cp foo @var{dest2}
@end example

会生成：

cp foo dest1; \
 cp foo dest2

输出采用 等宽字体 并 缩进 。输入文件中的每一行对应输出中的一行；也就是说，源文本 不会自动换行 。多余的空格和空行 有效 。Texinfo 命令会被展开；如果希望输出 完全原样 ，请改用 @verbatim 环境（参见 @verbatim: 原样文本块）。

从逻辑上讲，示例通常位于段落 “中间”，后续接续的文本不应缩进，如上例所示。 @noindent 命令可避免文本像新段落一样被缩进（参见 @noindent: 省略缩进）。

如果希望代码注释使用普通罗马字体，可以使用 @r 命令（参见 打印用字体）。

可以为 @example 命令指定可选参数，多个参数用逗号分隔。在 HTML 输出中，这些参数会作为类名输出，前缀为字符串 ‘user-’。这可用于为手册中的代码示例添加语法高亮。

我们建议：为 @example 指定多个参数时， 第一个参数用来指明代码语言 （如 C、lisp、Cplusplus）。你也可以用其他参数实现格式提示、标记代码样例以便提取和处理等用途，但目前暂无明确统一的建议。这一点或许会在未来的 Texinfo 版本中改变。

注意： 不要在示例内容的行中使用制表符！（在 Texinfo 的其他位置也不要用，verbatim 环境除外。）TeX 会把制表符当作单个空格处理，和它们实际显示的效果不一致。

@verbatim 环境用于输出可能包含 特殊字符或不应被解析的命令 的文本，比如计算机输入或输出内容（ @example 会将其中文本当作普通 Texinfo 命令解析）。在 Texinfo 手册中嵌入自动生成的文件内容时，该环境尤其有用。

一般情况下，输出与输入完全一致。不会进行任何字符替换，例如：所有空格、空行（包括制表符）都有效。文本以 等宽字体 排版， 不缩进、不自动换行 。

@verbatim 命令需单独一行开头书写，该行不会出现在输出中。使用 @end verbatim 命令标记原样块结束，同样单独一行开头书写，该行也不会出现在输出中。

示例：

@verbatim
{
<tab>@command with strange characters: @'e
expand<tab>me
}
@end verbatim

（其中 <tab> 代表一个实际的制表符）。将会输出：

{
        @command with strange characters: @'e
expand  me
}

由于包含 @verbatim 和 @end verbatim 的行不产生输出，通常应在 @verbatim 前、 @end verbatim 后各加一个空行。 @verbatim 起始与 @end verbatim 结束之间的空行会保留在输出中。

可以通过将 @verbatim 放入 @smallformat 环境中来得到小号的原样文本，如下所示：

@smallformat
@verbatim
... 仍然是原样输出，但字号更小 ...
@end verbatim
@end smallformat

最后提醒一句：在其他 Texinfo 结构内部使用 @verbatim 是不可靠的。

另见： @verbatiminclude file: 原样包含文件

@lisp 命令用于书写 Lisp 代码：

@lisp
Example lisp code
@end lisp

该命令现在与以下写法完全等效：

@example lisp
Example lisp code
@end example

建议使用 @lisp ，以保留示例类型相关的信息。例如，当你编写一个函数，仅处理且完整处理 Texinfo 文件中的所有 Lisp 代码时，这会很有用。这样你就可以把 Texinfo 文件当作 Lisp 库来使用

@display 命令用于开启另一类环境，该环境中 字体保持不变 ，不会像 @example 那样切换为等宽字体。输入的每一行仍会对应输出一行，且输出内容仍会缩进。

这是一段写在 @display 命令
和 @end display 命令的文本示例。@display 命令
会对文本进行缩进，但不会自动换行重排

@format 命令与 @display 类似，区别在于 文本不缩进 。与 @display 一样，它不会使用等宽字体。因此：

@format
This is an example of text written between a @code{@@format} command
and an @code{@@end format} command.  As you can see
from this example,
the @code{@@format} command does not fill the text.
@end format

会输出：

This is an example of text written between a @format command
and an @end format command.  As you can see
from this example,
the @format command does not fill the text.

@exdent 命令用于移除一行可能存在的所有缩进。该命令需写在 行首 ，且仅对 同一行内 命令之后的文本生效。不要在文本两侧加大括号。在输出格式允许的情况下， @exdent 所在行的文本会以罗马字体显示。

@exdent 通常用于示例内部。例如：

@example
This line follows an @@example command.
@exdent This line is exdented.
This line follows the exdented line.
The @@end example comes on the next line.
@end example

会输出：

This line follows an @example command.

This line is exdented.

This line follows the exdented line.
The @end example comes on the next line.

在实际使用中， @exdent 命令很少用到。通常，你可以通过结束示例环境、让页面恢复正常宽度来取消文本缩进。

@exdent 并非在所有输出格式中都生效。

@flushleft 和 @flushright 命令分别使文本行 靠左对齐、靠右对齐，但不会自动换行重排 。这些命令单独成行，不使用大括号。 @flushleft 和 @flushright 分别由单独成行的 @end flushleft 和 @end flushright 结束。

示例：

@flushleft
This text is
written flushleft.
@end flushleft

输出：

This text is written flushleft.

@flushright 产生的对齐效果常用于信件的回信地址。例如：

@flushright
Here is an example of text written
flushright.  The @code{@flushright} command
right justifies every line but leaves the
left end ragged.
@end flushright

输出：

@raggedright 会像平常一样对文本进行自动换行，但只在 左侧对齐 ，右侧边缘保持不齐平。该命令单独占一行，不使用大括号，以单独一行的 @end raggedright 结束。此命令仅在默认两端对齐的输出格式中生效；在默认就是右不齐平的格式（如 Info 或 HTML）中无效。

当段落里包含一长串命令名，且预先知道两端对齐会让排版很难看时， @raggedright 会很有用。

示例（摘自本手册其他部分）：

@raggedright
Commands for double and single angle quotation marks:
@code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}},
@code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}},
@code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}.
@end raggedright

输出效果：

Commands for double and single angle quotation marks: @guillemetleft{}, @guillemetright{}, @guillemotleft{}, @guillemotright{}, @guilsinglleft{}, @guilsinglright{}.

示例或其他插入内容可能会把段落分成几段。通常情况下，格式化工具会把示例后面的文本当作新段落来缩进。你可以在行首、接续文本之前写上 @noindent ， 逐个取消 这种缩进。也可以用 @paragraphindent 全局取消所有段落的缩进（参见 @paragraphindent: 控制段落缩进）。

下面示例展示了如何取消 @example 之后文本的默认缩进，这是很常见的场景：

@example
This is an example
@end example

@noindent
This line is not indented.  As you can see, the
beginning of the line is fully flush left with the
line that follows after it.

输出效果：

This is an example

This line is not indented.  As you can see, the
beginning of the line is fully flush left with the
line that follows after it.

@noindent 的标准用法如上所示：在本应成为段落的开头，取消该处的默认缩进。它可以紧跟文本，也可以单独占一行。 不应该 在其他场景使用，比如段落中间或某个环境内部（参见 引用与示例）。

你可以通过修改输入来控制 Info 文件输出中的空行数量：只包含 @noindent 的行不会生成空行，环境的 @end 行也不会。

不要在 @noindent 命令后加大括号；不需要使用大括号，因为 @noindent 是用在段落之外的命令（参见 @-Command 语法）。

作为对 @noindent 命令的补充（见上一节），Texinfo 提供了 @indent 命令，用于 强制让段落缩进 。例如，本节的第一段就是使用 @indent 命令进行缩进的。

实际上， @indent 最常用于 章节的第一段 ，用来覆盖该处默认不缩进的行为（参见 @paragraphindent: 控制段落缩进）。它可以紧跟文本，也可以单独占一行。

作为一种特殊情况，当在 不自动换行 的环境中使用 @indent 时，它会在 TeX 输出中生成一个段落缩进空格。（这类环境中输入的一行对应输出的一行，例如 @example 和 @display ；所有环境的汇总，参见 块包裹命令。）

不要在 @indent 命令后加大括号；该命令不需要大括号，因为 @indent 是用在段落之外的命令（参见 @-Command 语法）。

在输出格式支持的情况下， @cartouche 命令会为其内容绘制一个 圆角方框 。你可以使用该命令将手册中的一部分内容与正文分隔开，也可以用它进一步突出示例或引用。

例如，你可以在手册中用圆角框包裹某类示例以强调。示例：

@cartouche
@example
% pwd
/usr/local/share/emacs
@end example
@end cartouche

在印刷版手册中，会为这两行示例添加一个圆角方框。

示例的输出效果如下（如果你在 Info 中阅读， @cartouche 不会生效）：

% pwd
/usr/local/share/emacs

@cartouche 接受一个可选参数，写在命令所在行的剩余部分。如果提供该文本，它会作为圆角框的标题，以粗体或其他强调样式显示在框的开头，在部分输出格式中会居中。

下面示例演示带标题的圆角框：

@cartouche Important
Text explaining something important out of the main
flow of the text.
@end cartouche

带标题的圆角框效果如下：

在印刷输出中，圆角框内容会保持在同一页内，与 @group 类似（参见 @group: 防止分页）。

除了常规的 @example 及类似命令外，Texinfo 还提供了 “小型” 示例风格命令，包括： @smallquotation 、 @smallindentedblock 、 @smalldisplay 、 @smallexample 、 @smallformat 和 @smalllisp 。

在大多数输出格式中， @small… 系列命令与其对应的普通命令效果相同。

但在 印刷输出 中， @small… 命令会使用比普通示例命令 更小的字号 排版文本。例如，代码示例可以容纳更长的行，且无需重写就能适配页面宽度。

使用对应的 @end small… 标记 @small… 块的结束。例如， @smallexample 需与 @end smallexample 配对使用。

下面是 @smallexample 命令所用字体的示例（在大多数输出格式中，效果与普通写法一致）：

... to make sure that you have the freedom to
distribute copies of free software (and charge for
this service if you wish), that you receive source
code or can get it if you want it, that you can
change the software or use pieces of it in new free
programs; and that you know you can do these things.

@small… 命令与其普通版本使用 相同的字体样式 ： @smallexample 和 @smalllisp 使用等宽字体，其余命令使用常规字体。它们在其他方面的行为也保持一致 —— 是否自动换行、是否缩小页边距等。不过，即使普通版本命令支持参数， @small… 系列命令 也不接受任何参数 。

通用原则 ：若无特殊需求，建议直接使用常规命令（例如用 @example 而非 @smallexample ）。仅使用 texinfo.tex 处理时，可通过 ‘ @set dispenvsize small ’ 实现类似效果，该指令会为 @example 等环境统一使用更小字号。在 HTML 输出中，如需调整环境的字号，可通过 CSS 设置；详见 HTML CSS。

Texinfo 会自动对列表或表格中的文本进行缩进，并为 有序列表 自动编号。如果你修改了列表，这个自动编号功能会非常实用，因为你 不需要手动重新编号 。

编号列表和表格以行首对应的 @-command 开始，以单独一行的对应 @end 命令结束。表格和项目符号列表命令还要求，在起始 @-command 的同一行上书写格式控制信息。

例如：

• 使用 @enumerate 命令开始有序列表，用 @end enumerate 结束。
• 使用 @itemize 命令开始项目符号列表，并在同一行后跟格式命令（如 @bullet ），用 @end itemize 结束。

列表中的每一项，都要以 @item 或 @itemx 命令开头。

下面是不同类型列表与表格的项目符号列表示例：

• 带或不带项目符号的无序列表。
• 使用数字或字母的有序列表。
• 带高亮效果的双列表格。

下面是包含相同内容的有序列表示例：

1. 带或不带项目符号的无序列表。
2. 使用数字或字母的有序列表。
3. 带高亮效果的双列表格。

下面是包含相同内容及其对应 @-command 的双列表格：

@itemize

带或不带项目符号的无序列表。

@enumerate

使用数字或字母的有序列表。

@table

@ftable

@vtable

可选择建立索引的双列表格。

@itemize 命令用于生成一组 “items”(项目)，每个项目在左侧边距内以项目符号或其他标记开头，并且通常会缩进。

在行首写 @itemize 来开始一个项目符号列表。在该命令的 同一行 后面，跟上一个 Texinfo 命令或字符来生成项目标记。通常会在 @itemize 后使用 @bullet （实心圆点），但你也可以使用 @minus （减号）或其他任意 Texinfo 命令或字符。如果不指定标记命令，默认使用 @bullet 。

在 @itemize 之后编写你的项目，每个项目以 @item 开头。文本可以跟在 @item 同一行。一个项目的文本可以跨多个段落。

下面是 @itemize 的使用示例：

@itemize @bullet{}
@item
Some text for foo.

@item
Some text
for bar.
@end itemize

效果如下：

• Some text for foo.
• Some text for bar.

当你把 @bullet 这类标记命令作为 @itemize 的参数时，通常可以省略命令后面的 ‘{}’。

如果你完全不想要任何标记，但仍需要逻辑上的项目，可以使用 @w{} （这种情况下 必须写大括号 ）。

@itemize 环境内部至少要有一个 @item 。如果一个都没有， texi2any 会给出警告。如果你只想要缩进文本而不是项目列表，请使用 @indentedblock ；详见 @indentedblock: 缩进文本块。

出现在 @item 紧前方的索引条目，会与该 @item 关联。

通常你应该在项目之间留一个空行，这会在 Info 文件中产生空行（TeX 无论如何都会自动插入合适的垂直间距）。除非条目非常简短，否则这些空行会让列表更美观。

项目符号列表可以 嵌套 在其他项目符号列表中。下面是一个用减号标记的列表嵌套在圆点标记的列表中的示例：

@itemize @bullet{}
@item
First item.

@itemize @minus{}
@item
Inner item.

@item
Second inner item.
@end itemize

@item
Second outer item.
@end itemize

效果如下：

• First item.
  • Inner item.
  • Second inner item.
• Second outer item.

@enumerate 与 @itemize 用法类似（参见 @itemize: 创建项目符号列表），区别在于：项目的标记是连续的数字或字母，而非项目符号。

在行首书写 @enumerate 命令。该命令 不需要必选参数 ，但可以接受一个数字或字母作为可选参数。

• 不带参数时，@enumerate 从数字 ‘1’ 开始编号。
• 带数字参数（如 ‘3’）时，从该数字开始编号。
• 带大写或小写字母参数（如 ‘a’ 或 ‘A’）时，从该字母开始编号。

编号列表的文本写法与项目符号列表相同：每个项目开头用一行 @item 起始。文本可以紧跟在 @item 同一行，单个项目的文本也可以跨多个段落。

建议在列表条目之间空一行，这通常能让 Info 文档更易读。

下面是不带参数的 @enumerate 示例：

@enumerate
@item
Underlying causes.

@item
Proximate causes.
@end enumerate

效果如下：

1. Underlying causes.
2. Proximate causes.

下面是带参数 3 的示例：

@enumerate 3
@item
Predisposing causes.

@item
Precipitating causes.

@item
Perpetuating causes.
@end enumerate

效果如下：

3. Predisposing causes.
4. Precipitating causes.
5. Perpetuating causes.

用法总结：

@enumerate

不带参数：生成数字列表，第一项从 1 开始。

@enumerate unsigned-integer

无符号整数带（无符号）数字参数：从该数字开始生成编号列表，可用于接续被其他文本打断的列表。

@enumerate upper-case-letter

大写字母带大写字母参数：生成字母编号列表，从该大写字母开始。

@enumerate lower-case-letter

小写字母带小写字母参数：生成字母编号列表，从该小写字母开始。

你也可以像大纲一样 嵌套 使用编号列表。

@table 与 @itemize 用法类似（参见 @itemize: 创建项目符号列表），但允许你为每个项目指定名称或标题行。 @table 命令用于生成双列表格，特别适用于术语表、说明性示例和命令行选项汇总。

• 使用 @table 命令
• @ftable 与 @vtable
• @itemx: 第二个及后续表项

@multitable 用于创建任意列数的表格，每一列均可自定义宽度。

在 @multitable 所在行定义列宽，表格中每一行实际内容以 @item 命令开头，列与列之间用 @tab 命令分隔。最后以 @end multitable 结束表格。具体用法见后续小节。

• 多列表格列宽
• 多列表格行

浮动元素（float）是与正文分隔开的显示块，通常会标注为 “Figure”（图）、“Table”（表）、“Example”（示例） 或类似类型。

它之所以被称为 “float(浮动)”，是因为在打印输出时，理论上可以被移动到当前页的顶部、底部或后续页面（在其他输出格式中浮动并无意义）。但遗憾的是，除 LaTeX 外，其他所有输出格式目前均未实现浮动功能，浮动内容只会在当前位置输出，效果近似于 @group 命令（参见 @group: 防止分页）。

• @float [ 类型 ][, 标签 ]: 浮动内容
• @caption & @shortcaption: 标题与短标题
• @listoffloats: 浮动元素目录

你可以使用 @image 命令插入外部文件中的图片。尽管图片可以用在任何位置（包括段落中间），但我们放在本章介绍，因为它们最常作为显示图表或示例的一部分出现。

• 图片语法
• 图片缩放

脚注用于对正文进行 佐证或解释说明 。⁵

脚注会分散读者注意力，应尽量少用，最好完全避免。标准的文献引用通常更适合放在文档末尾的参考文献列表中，而不是分散在各处脚注里。

• 脚注命令
• 脚注样式

Texinfo 提供六种预定义索引。下面是它们的标准含义、缩写及对应的索引条目命令：

‘cp’

(@cindex) 概念索引，用于通用概念。

‘fn’

(@findex) 函数索引，用于函数及类函数名称（如库的入口点）。

‘ky’

(@kindex) 按键索引，用于键盘命令。

‘pg’

(@pindex) 程序索引，用于程序名称。

‘tp’

(@tindex) 数据类型索引，用于类型名称（如头文件中定义的结构体）。

‘vr’

(@vindex) 变量索引，用于变量名称（如库全局变量）。

并非每本手册都需要全部这些索引，大多数手册最多只使用两到三种。例如本手册就包含三种索引：概念索引、变量索引和 @-command 索引。（最后一种实际使用的是函数索引，但在章节标题中称作命令索引。）

你 不必严格按照预设用途 使用预定义索引。例如，若你想为某些 C 预处理器宏建立索引，可以直接为它们写 @findex 命令，将其与普通函数一同放入函数索引；之后在将 “函数索引” 作为无编号章节输出时，可将标题改为「函数与宏索引」，这样对读者而言结构依然清晰一致。

但另一方面，最好 不要过度偏离 预定义索引的原本含义。否则，一旦你的文档与其他手册的内容合并，索引条目就会无法对应。这种情况下，建议你 自定义新索引 （见 “定义新索引” 一节）。

我们建议：无论源文件中使用多少种索引，最终文档里 尽量只保留一个总索引 ，这样读者只需查阅一处即可。使用 @synindex 或 @syncodeindex 命令，可以将两个或多个源索引合并为一个输出索引（见 “合并索引” 一节）。

基于双字母索引名扩展而来的索引命令同样有效，例如可用 @cpindex 代替 @cindex 。

生成索引所需的数据，来自分散在整个 Texinfo 源文件中的众多独立索引命令。每条命令表示向某个指定索引添加一个条目；格式化之后，索引会以当前页码或节点名称作为引用标注。

索引条目由行首的一条索引命令，以及该行剩余部分的条目内容组成。

例如，本节开头为概念索引定义了以下五个条目：

@cindex Defining indexing entries
@cindex Index entries, defining
@cindex Entries for an index
@cindex Specifying index entries
@cindex Creating index entries

每个预定义索引都有自己对应的索引命令 —— @cindex 用于概念索引， @findex 用于函数索引，依此类推，具体可参见上一节。

索引条目应 位于 被索引的可见内容 之前 。例如：

@cindex hello
Hello, there!

原因之一是，这样索引链接（无论在何种环境下）会出现在内容前面，更符合读者的阅读习惯，而不是在内容之后。

在 Info 格式中，索引通常会被格式化为菜单。应尽量避免在索引条目中使用冒号，这可能会使部分 Info 阅读器产生混淆。有关菜单项结构的更多信息，请参见「菜单的组成部分」。

默认情况下，概念索引的条目使用罗马字体（正体）打印，其他索引的条目使用等宽字体打印。你可以使用常规 Texinfo 命令修改条目中部分内容的显示样式，例如用 @file 标记文件名（参见「标记文本、单词与短语」），用 @r 表示标准罗马字体（参见「打印用字体」）。

你可以在索引命令或条目文本后使用 @sortas 为索引条目显式指定排序键。

• 例如：‘ @findex @sortas{\} \ @r{(literal \ in @code{@@math}) ’，这会将生成的索引条目按反斜杠进行排序。

你可以选择在排序时忽略索引条目中的某些字符。目前可选择忽略的字符包括： \ 、 - 、=<= 和 @ ，分别通过向 @set 命令提供以下参数实现： txiindexbackslashignore 、 txiindexhyphenignore 、 txiindexlessthanignore 和 txiindexatsignignore 。例如，指定： @set txiindexbackslashignore 会使本手册索引中的 ‘ \mathopsup ’ 条目按 ‘mathopsup’ 排序，从而使其出现在其他以 ‘M’ 开头的条目之中。这样就不必为包含这些字符的索引条目手动指定显式排序键。

使用这些选项时，可能会出现索引条目排序键为空的情况。为避免此问题，可在索引条目中指定 @sortas 指令。例如：

@set txiindexbackslashignore
@findex @sortas{\} \

Texinfo 提供了更多用于索引的命令。

首先，你可以创建 multilevel 多级 索引条目 ，将多个相关子主题归类到同一个上层主题下。实现方法是使用 @subentry 命令分隔条目中的各个部分。示例如下：

@cindex Superhumans @subentry villains
@cindex Superhumans @subentry heroes

一个条目最多可以有三级：

@cindex coffee makers @subentry electric @subentry pink
@cindex coffee makers @subentry electric @subentry blue

你可以对条目的三级内容中的任意一部分或全部使用前面提到的 @sortas 命令，使其排序方式与默认不同。

其次，你可以使用 @seeentry (“see entry”) 命令，让一个索引条目指向另一个条目。例如：

@cindex Indexes @seeentry{Indices}

这类条目在文档中应当是唯一的，目的是将读者引导到包含所需全部信息的目标条目。

最后，你可以使用 @seealso 命令提供 “see also” 条目。这类条目会与普通条目一同出现在最终打印的索引中。例如：

@cindex Coffee
@cindex Coffee @subentry With milk and sugar
@cindex Coffee @subentry With doughnuts
@cindex Coffee @subentry Decaffeinated
@cindex Coffee @seealso{Tea}

使用这三种高级命令时， 不要在索引文本的不同部分之间加逗号 。负责对索引条目排序并生成索引格式化命令的 texindex 程序会自动在正确位置添加逗号。

不要用花括号将 @sortas 或高级命令插入到索引或 @subentry 条目中间；包含花括号的命令应放在条目 开头或末尾 。

这些功能在打印文档以及将 Texinfo 转换为 DocBook 时最为实用

概念索引条目由文本构成。编写索引的最佳方式是设计出 简洁又清晰 的条目。如果能做到这一点，索引通常会更美观：条目写法就像它们出现在句子中间一样，即 只对专有名词和始终需要大写的缩写进行大写 。这也是大多数 GNU 手册索引所采用的大小写规范。

如果你不知道如何让条目既简洁又清晰，那就写得 长一点但清晰 —— 不要为了简洁而变得晦涩。如果很多条目都由多个单词构成，换一种规范可能会更好： 每个条目的首单词大写 。无论使用哪种大小写规范，都要 保持一致 。

在任何情况下， 绝对不要 对区分大小写的名称（如 C 或 Lisp 函数名、Shell 命令名）进行大写改写，否则会成为拼写错误。概念索引之外的其他索引条目，通常是编程语言中的符号名或程序名，这些名称一般区分大小写，因此同样要按要求正确使用大小写。

在可行的情况下，让索引条目 保持唯一 是个好习惯。这样一来，使用打印版文档或在线索引补全功能的用户就不会看到无法区分的列表。可以借此机会让原本相同的索引条目更具体，方便读者快速找到确切位置。前面 “高级索引命令” 一节介绍的高级索引功能对此也有帮助。

制作索引条目时，良好的做法是 考虑人们可能用来查找的不同方式 。不同的人查找内容时想到的词汇并不相同。一份实用的索引会把内容放在人们可能用到的 所有不同关键词下 。例如，有的读者会自然认为索引的双字母名称应归类在 “索引，双字母名称” 下，因为 “索引” 是总体概念；但另一位读者可能只记得 “双字母名称” 这个具体概念，而去查找 “索引的双字母名称”。一份好的索引会同时包含这两种条目，从而帮助到两类读者。

和排版一样，编制索引也是一门 需要技巧的艺术 ，其中的精妙之处往往要亲自实践过才能体会。

@printindex 接收一个参数： 双字母的索引缩写 。你必须在文档中希望索引出现的位置写上 @printindex 命令。仅仅在 Texinfo 文件中使用 @cindex 或其他生成索引条目的命令是 不会自动生成索引 的 —— 这些命令只是用来 收集索引原始数据 。

你应当在 @printindex 命令前加上合适的节或章命令（通常是 @appendix 或 @unnumbered ），以提供章节标题，并把索引加入目录。和往常一样，在章节标题前写上 @node 行。

示例：

@node Variable Index
@unnumbered Variable Index

@printindex vr

@node Concept Index
@unnumbered Concept Index

@printindex cp

节点名中必须包含 Index（索引）字样，这样 Info 阅读器才能找到对应的索引。

如果文档中有多个索引，建议把 概念索引放在最后 。

不同输出格式下的索引细节

• 在使用 TeX 生成打印版手册的流程中，你需要运行 texindex 程序（见《用 TeX 排版与打印》）对原始数据排序，生成 已排序的索引文件 ，最终打印时使用的就是这个文件。

  @printindex 读取对应的已排序索引文件，生成传统的 双栏索引 ，包含索引术语和页码。

• 在 Info 输出中： @printindex 生成一个特殊菜单，显示条目相对于节点开头的 行号 。Info 阅读器可直接跳转到条目所在行，而不只是节点（旧版 Info 只会跳转到节点）。示例：

  * First index entry:   Top.   (line  7)
  

• 在 plain text(纯文本) 输出中： @printindex 格式通常与 Info 菜单类似，显示条目相对于文件开头的行号。
• 在 HTML 输出中： @printindex 生成指向索引条目的 链接 。
• 在 DocBook 和 LaTeX 输出中：仅记录待打印的索引信息。

有时你会希望把两个不同的索引（例如函数索引和概念索引）合并在一起，可能是因为条目数量很少，单独列出一个索引会显得单薄。

你可以改用 @cindex 命令而非 @findex 命令，把函数条目写入概念索引，然后将概念索引的标题设为 ‘Function and Concept Index’ 并完全不打印 ‘Function Index’ ，以此生成风格统一的手册。但这种做法 不够稳健 。它只适用于你的文档 永远不会 被并入另一个原本就设有独立函数索引的文档的情况；如果你的文档被并入那样的文档，你文档里的函数和另一文档里的函数就无法合并到一起。此外，要让函数名在概念索引中以正确的字体显示，你还必须把每个函数名都用 @code 花括号括起来。

@syncodeindex：使用 @code 合并索引@synindex：合并索引

• @syncodeindex: 通过 @code 字体合并索引
• @synindex: 合并索引

除了预定义索引（见预定义索引），你还可以使用 @defindex 和 @defcodeindex 命令来 定义新索引 。这些命令会创建新的索引 @‑命令 ，用于标记索引条目。 @defindex 命令的用法如下：

@defindex name

新索引的名称通常是 双字母 ，例如 ‘au’ 。示例：

@defindex au

这会定义一个名为 ‘au’ 的新索引，同时自动创建新的索引命令 @auindex ，你可以用它来生成索引条目。这个新命令的用法与预定义的索引命令完全相同。

例如，下面是一个节标题，后面跟着一个概念索引条目和两个 au 索引条目：

@section Cognitive Semantics
@cindex kinesthetic image schemas
@auindex Johnson, Mark
@auindex Lakoff, George

（显然，这里的 ‘au’ 是 “author（作者）” 的缩写。）

Texinfo 会通过 将索引名 与 ‘index’ 拼接来构造新的索引命令。因此，定义一个名为 ‘xy’ 的索引会自动生成命令 @xyindex 。

使用 @printindex 命令打印新索引，用法与预定义索引一致。例如：

@node Author Index
@unnumbered Author Index

@printindex au

@defcodeindex 命令与 @defindex 类似，区别在于：在打印输出中，它的条目 默认 使用 @code 等宽字体，而不是罗马正体。

你应当在 Texinfo 文件的 文件头结束行之前 定义新索引，并且（当然）要在任何 @synindex 或 @syncodeindex 命令之前定义（见 Texinfo 文件头）。

如前所述（见预定义索引），我们建议最终文档里 尽量只保留一个索引 （无论源文件里用了多少个索引），这样读者只需在一处查找内容。

创建索引时，TeX 会生成以 索引名作为后缀 的文件（见索引文件名）。因此应避免使用与其他用途后缀冲突的索引名，例如 .aux 或 .xml 。如果新索引与已知后缀冲突， texi2any 会自动报错

‘@’ 和大括号是 Texinfo 中的基础特殊字符。若要在文档中正常显示这些字符，必须在字符前加上 ‘@’，避免 Texinfo 对其进行错误解析。同时也提供了对应的命名命令。

其他字符（逗号、反斜杠、井号、与号）仅在特定场景下为特殊字符，具体说明见对应章节。

• 插入 ‘@’ 使用 @@ 与 @atchar{}
• 插入 ‘{}’ 使用 @{ @} 与 @l rbracechar{}
• 插入 ‘,’ 使用 @comma{}
• 插入 ‘\’ 使用 @backslashchar{}
• 插入 ‘#’ 使用 @hashchar{}
• 插入 ‘&’ 使用 @& 与 @ampchar{}

正如前面关于 Texinfo 通用输入约定的章节所述（见通用语法约定），Texinfo 源文件使用 ASCII 字符 ` （十进制 96）生成左单引号 ‘ ，使用 ASCII 字符 ' （十进制 39）生成右单引号 ’ 。将这些输入字符成对使用（ `` 和 '' ）会生成双引号 “ 和 ” 。这是 TeX 所采用的约定。

但在计算机代码示例中， ` 和 ' 会分别显示为这些 ASCII 字符的常规样式：单独的反引号（重音符）和无方向单引号。在过去，TeX 输出默认使用带方向的字形。Texinfo 提供了以下命令，用于在这两种显示样式之间切换：

@codequoteundirected on-off

设为 off 时，代码环境中的 ' 字符将输出为右弯单引号。

@codequotebacktick on-off

设为 off 时，代码环境中的 ` 字符将输出为左弯单引号。

如果只想在文档的部分内容中使用这些设置，可以用 @codequote... on 恢复默认行为，例如： @codequoteundirected on 。

这些设置会影响： @code 、 @example 、 @kbd 、 @samp 、 @verb 和 @verbatim 。详见高亮命令的用途。

遗憾的是，部分文档阅读器在复制粘贴时，会破坏带方向的引号字符。（免费 PDF 阅读器 xpdf 可以正常使用，但其他免费与非免费 PDF 阅读器均存在此问题。）

也可以通过 @set 和 @clear 命令，对对应的变量 txicodequoteundirected 和 txicodequotebacktick 进行操作，来控制该功能。

以下章节介绍用于控制句子内部及句后各类间距的命令。

• 多个空格
• 非句尾空格
• 句尾空格
• @frenchspacing val: 控制句子间距
• @dmn {dimension}: 格式化尺寸

下表列出了 Texinfo 中用于插入 浮动重音符号 的命令。它们都需要一个参数，即要添加重音的字符：

• 可以像普通命令一样放在花括号里（ @'{e} ）；
• 也可以作为特例省略花括号，直接将紧跟的字符作为参数（ @'e ）。这样做是为了让源码更便于输入和阅读，因为重音字符在部分语言中非常常见。

如果是字母形式的命令（如 @dotaccent ），不使用花括号时，命令名与参数之间必须加空格。如果是非字母形式的命令（如 @' ），不能加空格，参数就是紧跟的下一个字符。

例外： @tieaccent 的参数必须放在花括号里（因为它作用于两个字符，而非一个）。

在 Info 与纯文本输出中：

• 如果文档编码支持，重音结构会输出为真实的重音字符；
• 若给 texi2any 指定了 --disable-encoding 选项则除外（参见 @documentencoding enc: 设置输入编码）；
• 若无法输出对应编码字符，则使用 ASCII 转写形式。

重音命令表

下表列出了用于插入英语以外语言常用字符的 Texinfo 命令：

使用成对的单引号字符来开始和结束引用： ``…'' 。两个单引号会被转换为左、右双引号，“像这样”。

你偶尔可能需要输出 连续两个单引号 ；例如，在编写 Maxima 这类计算机语言的文档时， '' 是一个合法命令。这时可以使用输入 '@w{}' 实现；空的 @w 命令会阻止字符被合并成双引号。

Texinfo 中使用的左引号字符（ ` ，ASCII 码 96）在 ANSI 和 ISO 字符集标准中是 重音符 。我们将它用作引号字符，是因为 TeX 默认就是这样配置的。

Texinfo 支持英语以外其他语言中使用的多种引号。下表列出了 Texinfo 提供的用于插入各类引号的命令。

对于双角引号，同时也支持 Adobe 和 LaTeX 中的字形名称： @guillemotleft 和 @guillemotright 。 这些名称并不准确 ：“guillemot” 实际上是一种鸟类（海雀的一种）。

标准 TeX 字体支持英语中常用的引号（即由 ASCII 单引号与成对单引号生成的那些）。对于其他引号，TeX 使用 European Computer Modern（EC） 字体（如 ecrm1000 及其他变体）。这些字体当然是免费的，你可以从 http://ctan.org/pkg/ec 等站点下载。

免费的 EC 字体是使用 Metafont 生成的 位图字体 。尤其对于在线查看，字体的 Type 1（矢量）版本更为合适；这类字体可在 CM-Super 字体包中获取（http://ctan.org/pkg/cm-super）。

这两个发行版都包含安装说明。

引号的使用惯例在不同语言间存在极大差异（参见维基百科 “引号” 词条：https://en.wikipedia.org/wiki/Quotation_mark）。Texinfo 并未提供相关命令或配置，用于按照各类繁多的惯例排版引号。因此，你需要为手册所使用的语言选择适配的命令。有时可通过别名（参见 @alias new=existing ）简化使用方式，同时提升源代码的可读性。例如在德语中，左双引号需使用 @quotedblbase 命令，而右双引号则由本应表示左双引号的 @quotedblleft 命令生成，这一用法有违直觉。因此在这种情况下，定义以下别名会更为便捷：

@alias lgqq = quotedblbase
@alias rgqq = quotedblleft

你可以使用 @sub 和 @sup 命令插入下标与上标。例如：

here@sub{below}@sup{above}

会生成：

here_{below}^{ᵃᵇᵒᵛᵉ}

在 Info 格式与纯文本中， @sub{text} 目前会输出为 _{text} ， @sup{text} 会输出为 ^{text} ，包含字面意义上的花括号（用于向读者标记 “script” 文本的起止）。

当输出格式（及显示程序）支持时（如打印输出、HTML），若两个命令连续使用，上标会显示在下标上方。

对于数学表达式中的下标与上标，建议优先使用 TeX 的 _ 和 ^ 符号。参见下一节。

你可以使用 @math 命令编写数学表达式、方程式或公式。将 TeX 数学标记法写在花括号内，示例如下：

@math{\partial_\alpha \partial^\alpha A^\beta = \mu_0 J^\beta}

当 @math 用于段落内时，会以 行内形式 排版，就像本示例中这样 \(\partial_\alpha \partial^\alpha A^\beta = \mu_0 J^\beta\) 。该命令对 Info 格式输出无特殊作用，仅会原样输出其内容。

对于打印输出， @math 会切换至 TeX 的 “math mode”。在此场景下，纯 TeX 中用于符号、函数等的数学控制序列需使用 ‘\’ 而非 ‘@’。

默认情况下，HTML 输出仅会对数学公式做 强调处理 。 texi2any 提供了三种选项，用于在 HTML 中正确排版数学公式。你可通过 HTML_MATH 变量选择这些选项（参见 “数学公式的 HTML 自定义配置”）：

• 若将 HTML_MATH 设为 ‘l2h’， texi2any 会尝试调用 latex2html 程序为数学内容生成图片文件；
• 设为 ‘t4h’ 时，会尝试调用 tex4ht 程序；
• 设为 ‘mathjax’ 时，会在输出文件中插入 MathJax 脚本引用以排版数学内容（该选项需浏览器启用 JavaScript 才能生效）。

相关配置可参见：MathJax 自定义变量、 latex2html 自定义变量、 tex4ht 自定义变量。

对于 显示型方程式 （独行展示的公式），可使用 @displaymath 命令。示例：

@displaymath
f(x) = {1\over\sigma\sqrt{2\pi}}
e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2}
@end displaymath

该代码会生成：（注：此处对应公式排版效果为正态分布概率密度函数：

\[ f(x) = {1\over\sigma\sqrt{2\pi}} e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2} \]

通常， @math 或 @displaymath 的内容应仅包含纯 TeX 代码，不可穿插 Texinfo 命令。若确需使用 Texinfo 命令，需按常规方式加 ‘@’ 前缀（如 ‘@var’ 而非 ‘\var’），但我们不保证所有 Texinfo 命令均可生效。

尽管 @sub 和 @sup 在某些场景下可在数学模式中使用，但建议在数学表达式中优先使用 TeX 的 ‘_’（下标）和 ‘^’（上标）符号。

仅当输出格式为 LaTeX，或启用 HTML_MATH 相关选项时（其中 tex4ht 需将 T4H_MATH_CONVERSION 设为 ‘latex’；参见 tex4ht 自定义变量），LaTeX 专用代码才能生效。

由于 Texinfo 的 @sup 命令存在命名冲突，若你确需使用纯 TeX 命令 \sup （这种情况极少出现），可改用 \mathopsup 替代 —— 但该写法仅在通过 TeX 处理时生效，输出 LaTeX 或使用任何 HTML_MATH 选项时均不适用。

Texinfo 支持一些印刷文本中常用、但 ASCII 中没有的额外符号。当然，这类符号还有成千上万种。就 texi2any 而言，直接使用 Unicode 字符是可行的，但 TeX 则没这么方便。

• @TeX{} （TeX）与 @LaTeX{} （LaTeX）
• @copyright{} （©）: 版权符号
• @registeredsymbol{} （®）: 注册商标符号
• @dots （…）与 @enddots （…）: 省略号
• @bullet （•）: 项目符号
• @euro （€）: 欧元符号
• @pounds （£）: 英镑符号
• @textdegree （°）: 度符号
• @minus （−）: 减号
• @geq （≥）与 @leq （≤）: 大于等于/小于等于符号

在 Texinfo 中，代码常通过 @example 和 @end example 包裹的示例进行展示。在这类示例里，你可以使用 ‘⇒’ 或 ‘→’ 表示求值结果或展开效果。同样，也有对应的命令可插入符号，用来表示打印输出、错误信息、表达式等价、编辑器中点的位置，以及图形界面操作序列。

这些符号插入命令并非必须在示例中使用，但 绝大多数情况下都用于示例中 。所有符号插入命令后面都带有空花括号。

• 符号汇总
• @result{} （⇒）：表达式结果
• @expansion{} （→）：展开标识
• @print{} (-|)：生成输出标识
• @error{} (error→)：错误信息标识
• @equiv{} (≡)：等价标识
• @point{} (*)：缓冲区光标位置标识
• 点击序列

命令 @U{hex} 用于插入 Unicode 字符 U+ hex 的表示形式。例如， @U{0132} 会插入荷兰语合字 ‘IJ’（即 ‘IJ’）。

hex 必须是 至少四位 的十六进制数，不会自动补前导零。通常， hex 必须指定一个合法的常规 Unicode 字符；例如， U+10FFFF（最后一个码位）本身就是非法码点，因此不能通过该命令插入。

@U 适用于插入 Texinfo 没有提供专用命令的少量符号，同时能让 Texinfo 源码保持纯 7 位 ASCII 编码，以实现最大可移植性。

该命令存在诸多限制 —— 与以 UTF‑8 或其他二进制形式直接插入 Unicode 字符的限制相同。首先也是最重要的一点：TeX 并不支持绝大多数 Unicode 字符。虽然可以按需支持特定的额外符号，但让 texinfo.tex 完整支持整套文字体系（如日文、乌尔都文等）并不现实。 @U 命令并不会改变这一点。如果指定的字符在 TeX 中不被支持，将会报错。LaTeX 输出对 UTF‑8 的支持相对更好，但可能需要额外代码来加载字体并声明 UTF‑8 字符的输出方式。（参见 @documentencoding enc: Set Input Encoding。）

在 HTML 和 DocBook 格式中， @U 的输出始终是形如 ‘ &#x hex; ’ 的实体引用，例如上面的例子会输出 ‘&#x0132;’ 。即使 HTML 文档使用其他编码（如 Latin 1）且该字符不在此编码中，通常也能正常显示。

在 Info 和纯文本格式中，如果输出编码不是 UTF‑8，则会输出 ASCII 序列 ‘ U+ hex ’，例如上面的例子会显示为 6 个 ASCII 字符：‘U+0132’

换行命令用于创建或允许换行与分段：

@*

强制换行。

@sp n

跳过 n 行空行。

@-

插入可选连字符。

@hyphenation {hy-phen-a-ted words}

在 hy-phen-a-ted 单词中定义连字符位置。

以下命令可将文本保持在同一行：

@w{text}

禁止 text文本 被拆分并跨两行加连字符。

@tie{}

插入普通单词间空格，且此处不允许换行。

分页命令仅适用于印刷版输出，因为其他输出格式没有页面概念。

@page

开始新页面。

@group

将必须在同一页显示的文本绑定在一起。

@need mils

若当前页面剩余空间不足，则新建一页。

@* 命令在所有输出格式中强制换行。 @/ 命令仅在印刷版手册中允许自动换行。

下面是使用 @* 的示例：

This sentence is broken @*into two lines.

会生成：

This sentence is broken
into two lines.

@=/= 命令在长 URL 或其他 TeX 无法自动找到合适换行位置的标识符中很有用。TeX 会在 URL 的自然位置自动换行（参见 URL 换行），因此只在需要时才使用 @/ 。 @/ 对其他输出格式无效果

尽管 TeX 的断字算法通常效果很好，但它偶尔还是会漏掉合适的断字位置。（或者，更少见的情况是，插入错误的断字。）因此，对于包含生僻词汇的文档，或是为印刷版进行精细排版时，你可能需要显式指定断字位置。Texinfo 提供了两个相关命令：

@-

插入 可选连字符 ，即在单词中可以跨行断开并显示连字符的位置。当你发现因 TeX 未自动断字而导致 “行溢出”（overfull hbox）时，这个命令尤其有用（参见行溢出）。如果一个单词中包含 @- ，TeX 将不会再自动添加其他断字位置。

@hyphenation {hy-phen-a-ted words}

为指定单词设置断字位置。例如：

@hyphenation{man-u-script man-u-scripts}

如示例所示，你需要在每个希望断字的位置加上 ‘-’ 。TeX 只会在单词 完全匹配 时使用指定的断字规则，因此需要给出所有必要的变形形式，比如复数形式。

非印刷格式的输出不会进行连字符断字，因此这些命令在其他输出格式中 均无效 。

通常情况下，TeX 会在 @code 及相关命令内的字符 ‘-’ 和 ‘_’ 处考虑换行（参见 @code {sample-code}），大致相当于把这些符号当作 “空” 断词点处理。

这一点是必要的，因为很多手册（尤其是 Lisp 家族语言的手册）需要描述非常长的标识符。但另一方面，有些手册不存在这类问题，你可能不希望在某些标识符的下划线处换行，例如 SIZE_MAX ，更不希望在 __typeof__ 这类四个下划线中的任意一处后换行。

因此 Texinfo 提供了这条命令：

@allowcodebreaks false

用于禁止在 @code 内的 ‘-’ 或 ‘_’ 处断行。使用 @allowcodebreaks true 可以恢复允许此类断行。这些命令需单独写在一行。

这些命令可在文档任意位置使用。例如，你可能只需要在某一段有问题的段落中关闭断行，而其他地方保持默认开启，或者反过来。

该命令只对 TeX 输出生效，对其他输出格式无影响。

@w{text} 输出文本内容，同时 禁止在内容内部自动换行 。

因此，你可以使用 @w 生成 不可换行的空格 ，其宽度固定为普通单词间空格的宽度：

@w{ } @w{ } @w{ } indentation.

将输出：

indentation.

由 @w{ } 产生的空格不仅不可断开，而且 不会被拉伸或压缩 。有时这正是你需要的效果，例如在进行手动缩进时。但通常情况下，你会希望使用可拉伸、可压缩的普通单词间空格（用于印刷输出）；相关用法请参见下一节的 @tie 命令。

在印刷输出中，你还可以使用 @w 命令避免长名称或短语被自动断词连字符拆分，例如当它们恰好出现在行尾时。

你也可以使用 @w 避免源码控制系统中出现意外的关键字展开。例如，要在文档中原样写出 $Id$ ，可写作 @w{$}Id$ 。不过这个技巧在某些输出格式的文件中无效。

@tie{} 命令生成一个普通单词间距，且不允许在此处换行。该命令后面必须紧跟一对空的大括号，与段落内其他命令的写法一致。示例：

@TeX{} was written by Donald E.@tie{}Knuth.

输出效果：

TeX was written by Donald E. Knuth.

@tie{} 与 @w{} 有两个重要区别：

• @tie{} 生成的空格会随段落中普通单词间距一起 轻微拉伸或压缩 ；而 @w{ } 生成的空格 宽度固定不变 。
• @tie{} 允许两侧单词正常断词连字符；而 @w{ } 会 禁止两侧单词断词 （出于 TeX 技术原因，即它会生成一个 ‘\hbox’）。

以 @sp n 开头且整行仅包含该命令时，会生成 n 行空白行。 @sp 同时会强制分段。

例如：

@sp 2

会生成两行空白行。

@sp 命令最常用于标题页

一行中只包含 @page 时，会在印刷版手册中 开始新的一页 。在没有 “页面” 概念的其他输出格式中，它会 开始一个新段落 。 @page 命令常用于 Texinfo 文件的 @titlepage 区域，用来 开启版权页 。

@group 命令用于将一段示例内容 保持在同一页 。在 @example 或类似环境中使用它，可以开始一个 不可拆分的垂直块 ，使其在印刷输出中完整出现在同一页。使用仅包含 @end group 的一行来结束该块。该命令 仅对 TeX 输出 生效。

@group 和 @end group 命令必须放在 @example 与 @end example 之间，格式如下：

@example
@group
...
@end group
@end example

尽管从概念上讲， @group 可用于多种场景，但当前实现仅在以下环境中生效： @example 及其变体、 @display 、 @format 、 @flushleft 、 @flushright 。参见 “引用与示例” 一章。（这些命令的共同点是：输入的每一行都会直接对应输出的一行。）

如果一行中只包含 @need n ，那么在印刷版手册里，当当前页面剩余空间小于 n 密耳（千分之一英寸）时，就会 另起新页 。参数 n 外面不要加花括号。 @need 命令对其他输出格式没有效果，因为它们不进行分页。

本段前面就使用了 @need 命令：如果页面剩余空间不足 800 密耳（0.8 英寸），就会在印刷输出中另起一页。写法如下：

@need 800
This paragraph is preceded by ...

@need 命令常用于避免 孤行 ：即只有一行文字孤零零出现在印刷页底部的情况。

@deffn category类别 name名称 args参数…
定义主体内容
@end deffn

@deffn 命令用于定义 类似函数 、可接收参数的实体。在一行开头书写 @deffn 命令，同一行依次跟上： 实体类别、实体名称、参数（如有）。随后在后续行书写定义的主体内容，最后单独一行用 @end deffn 结束定义。

示例：

@deffn Command forward-word count
This command moves point forward @var{count} words
(or backward if @var{count} is negative). ...
@end deffn

渲染效果：

Command: forward-word count

This command moves point forward count words (or backward if count is negative). …

类别名称按 标题格式首字母大写 。如果类别名称含空格（如 ‘Interactive Command’），需用 大括号 包裹：

@deffn {Interactive Command} isearch-forward
...
@end deffn

否则第二个单词会被误识别为实体名称。通用规则：标题行中 除最后一个参数外 ，任何多单词内容都要用大括号包裹。文本中含特殊命令时也需如此（例如西语中的 ‘{declaraci@'on}’）。

不同输出格式中， 类别 的显示位置不同：

• Info 文件：显示在定义第一行开头
• TeX 输出：打印在右侧边栏旁

@deffn 会将名称加入函数索引。

@deffn 有三个预定义的专用变体（ @defun 、 @defmac 和 @defspec ），会分别为你指定类别：函数、宏和特殊形式。（在 Lisp 中，特殊形式是一种与函数类似的语法实体。）同样，通用命令 @defvr 也配有多个专用变体，用于描述特定类型的变量。

与之类似，通用变量命令 @defvr 也配有多个专用变体，用于描述不同类型的变量

定义命令的标题行可能会变得很长。因此，Texinfo 提供了一种特殊语法，允许它们在源文件中 跨多行续行 ：在需要续行的每一行末尾单独写一个 ‘@’。示例如下：

@defun fn-name @
  arg1 arg2 arg3
This is the basic continued defun.
@end defun

生成的效果为：

Function: fn-name arg1 arg2 arg3

This is the basic continued defun.

可以看到，续行的内容会被合并，就像在源文件中写在同一行一样。

虽然本例只展示了一行续行，但续行可以按同样方式 跨任意多行 ：只需在每个需要续行的行尾加上 @ 。

一般情况下，续行符 @ 前面的任意多个空格或制表符，都会被 压缩为单个空格 。但有一个例外：Texinfo 处理器不会完全压缩大括号内部续行周围的空白。例如：

@deffn {Category @
  Name} ...

输出结果中，“Category” 和 “Name” 之间会出现多余空格。要避免这一问题，请在输入时删去不必要的空白，或者把续行符 @ 放在大括号 外面 。

@ 在其他任何上下文里都 不作为续行符 使用。通常， @ 后面跟空白字符（空格、制表符、换行）会生成一个普通的单词间空格（参见 “多个空格”）

有些实体支持可选参数或重复参数。表示这类参数的通用约定是使用 方括号 和 省略号 ：

• 被方括号 [] 括起来的参数是可选参数；
• 后面跟省略号 … 的参数可以重复多次（也可省略）。

因此，[ optional-arg ] 表示 optional-arg 是可选参数， repeated-args… 表示零个或多个参数。在 Lisp 中，当多个参数需要组合成更深一层的列表结构时，会使用 圆括号 。

下面是一个虚构的（较复杂的）特殊形式的定义行示例：

Special Form: foobar (var [from to [inc]]) body…

在本例中：

• 参数 from 和 to 是可选的，但必须同时出现或同时省略；
• 如果提供了 from 和 to ，则 inc 也可以选择性给出；
• 这些参数与 var 组合成一个列表，以便和 body 区分开， body 包含该形式的所有剩余部分。

在 Texinfo 源文件中，这条 @defspec 语句写法如下：

@defspec foobar (var [from to [inc]]) body@dots{}

出于排版风格或编程语言语法的要求，你可能希望在定义中的名称 后面、左括号前面 不显示空格。要实现这一点，可以设置 ‘txidefnamenospace’ 标记（参见 @set 和 @value ）。

例如，如下输入：

@set txidefnamenospace
@deffn Builtin index (string, substring)
@dots{}
@end deffn

会生成如下输出：

Builtin: index (string, substring)

…

若要为一个定义编写 两条或更多首行 / 标题行 ，可在第一条 @deffn 行之后，使用以 @deffnx 开头的行。

示例：

@deffn {Interactive Command} isearch-forward
@deffnx {Interactive Command} isearch-backward
These two search commands are similar except ...
@end deffn

生成效果：

Interactive Command: isearch-forward

Interactive Command: isearch-backward

These two search commands are similar except …

所有定义命令都有对应的 ‘x’ 形式： @defunx 、 @defvrx 、 @deftypefunx 等。

这类带 ‘x’ 的命令用法与 @itemx 类似（参见 @itemx: 第二条及后续条目）。

本节介绍 Texinfo 中所有的定义命令。

• 函数及类似实体
• 强类型语言中的函数
• 变量及类似实体
• 强类型语言中的变量
• 数据类型
• 面向对象编程

Texinfo 提供了不会自动生成索引条目的定义类命令。

使用 @defblock 与 @end defblock 配对来创建一个 通用定义环境 。在该环境内部，对每个要编写文档的符号使用一行 @defline 或 @deftypeline 。示例：

@defblock
@defline Macro mac (arg1, arg2)
Description of mac.
@deftypeline Builtin int foo (int @var{bar})
Description of foo.
@end defblock

输出效果：

Macro: mac (arg1, arg2)

Description of mac.

Builtin: int foo (int bar)

Description of foo.

@defline 的语法与 @deffn 类似。第一个参数指定定义的 类别 ，后面依次是 符号名称 和 参数 （如有）。包含空格的参数需要用大括号括起来。

@deftypeline 的用法与 @deftypefn 类似：在类别之后指定 数据类型 ，并用 @var 标记参数（参见《强类型语言中的函数》一节）。

如果要让多个符号共用同一段描述，可以将多条 @defline 连续放在一起。示例：

@defblock
@defline Function set-var (value)
@defline {Settable Variable} var
Description of set-var and var.
@end defblock

输出效果：

Function: set-var (value)

Settable Variable: var

Description of set-var and var.

将 行宏 （参见行宏）与这些命令结合使用会很有用。

一份手册不应为同一个名称提供多个定义。用于汇总内容的附录应使用 @table ，而非各类定义命令。

使用 @deffn 、 @defun 或其他定义命令编写文档时，请尽量使用 能体现含义的参数名 ，例如 forward-word 函数的 count 参数。同时，如果参数名中包含类型名称（如 integer），请确保该参数确实属于此类型。

字体规范

由于 Texinfo 是 语义化标记语言 ，在定义中应 尽量避免 使用显式字体命令指定样式（参见 “打印用字体” 一节）。仅当需要解决特定输出格式或结构的问题时，才考虑使用。常见用法如下：

• 使用 @r{&keyword} 显式标记类似 ‘&keyword’ 这样的 Lisp 关键字，输出为： &keyword。

  注意：目前定义行中的这类关键字在 TeX 中会以罗马体显示，但其他输出格式不做此处理。

• 使用 ‘@r{@slanted{argument}}’，效果为： argument ，作用与 @var 类似，但可避免在 Info 格式中将内容转为大写。

  在以上两种用法中， @r 会将当前定义行的字体（斜体或等宽体）重置为 标准罗马正体 。

• 你可以使用 @t （甚至 ‘@r{@t{…’，用 @r 先重置字体）来标记定义行中的 字面语法 ，避免这些内容被显示为斜体罗马体。此处不宜使用 @code ，因为它会在 Info 输出中自动添加引号。

要得到理想效果，可能需要一定的尝试与调试。与往常一样，嵌套字体命令的效果取决于输出格式，因此应尽量避免。

建议尽量减少这类特殊字体用法。可行方案是：将它们封装在 @macro 中（参见 “定义新的 Texinfo 命令” 一节），方便日后统一修改。

下面是摘自《GNU Emacs Lisp 参考手册》中 “调用函数” 一节的定义，使用了 @defun 命令。函数名 apply 紧跟在 @defun 命令之后，同一行后面是参数列表。

Function: apply function &rest arguments ¶

apply calls function with arguments, just like funcall but with one difference: the last of arguments is a list of arguments to give to function, rather than a single argument. We also say that this list is appended to the other arguments.

apply returns the result of calling function. As with funcall, function must either be a Lisp function or a primitive function; special forms and macros do not make sense in apply.

(setq f 'list)
    ⇒ list
(apply f 'x 'y 'z)
error→ Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
    ⇒ 10
(apply '+ '(1 2 3 4))
    ⇒ 10

(apply 'append '((a b c) nil (x y z) nil))
    ⇒ (a b c x y z)

An interesting example of using apply is found in the description of mapcar.

在 Texinfo 源文件中，这个示例应写成如下形式：

@defun apply function @r{&rest} arguments
@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument.  We also say that this list is @dfn{appended}
to the other arguments.

@code{apply} returns the result of calling
@var{function}.  As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.

@example
(setq f 'list)
    @result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
    @result{} 10
(apply '+ '(1 2 3 4))
    @result{} 10

(apply 'append '((a b c) nil (x y z) nil))
    @result{} (a b c x y z)
@end example

An interesting example of using @code{apply} is found
in the description of @code{mapcar}.
@end defun

在本手册中，该函数在 命令与变量索引 中归类于 apply 条目下。

@documentlanguage 命令用于声明当前文档的语言区域。该命令需 单独成行 ，写在文件开头附近。

@documentlanguage ll[_cc]

在命令名后填写两位 ISO 639-2 语言代码 (ll)，可选择性地跟上一个下划线与两位 ISO 3166 国家代码 (cc)。若为多语言文档，可 多次使用 该命令，以声明每次语言切换。若完全不使用此命令，默认语言为 en_US （美式英语）。

与 GNU Gettext 类似（参见 Gettext ），若省略国家代码，会尽可能采用该语言的主流方言。例如： de 等价于 de_DE （德国使用的德语）。

此命令会更改各种 document strings文档字符串 的翻译，例如交叉引用中的 “see” （见Cross-references）、函数定义中的 “Function” （见定义命令）等。此外，该命令还可可选地影响 texi2any 对索引的排序方式（参见「全局自定义变量」中的 DOCUMENTLANGUAGE_COLLATION 部分）。

注意：在 Info 格式输出中，部分字符串属于关键字， 不会被翻译 ，例如 “Node:”、“Next:”、“Menu:” 等。

在 DocBook 输出中， @documentlanguage 用于设置后续章节的语言。

对于 LaTeX，该命令会在导言区生成加载 ‘babel’ 宏包的代码，并输出 \selectlanguage 。

对于 TeX，该命令会读取文件 txi-locale.tex （若存在）。如果 @documentlanguage 参数带有可选的 ‘_cc’ 后缀，会优先尝试该组合：例如使用 @documentlanguage de_DE 时，TeX 会先查找 txi-de_DE.tex ，再查找 txi-de.tex 。

这类以 txi-* 命名的文件，用于重新定义 TeX 输出中使用的各类英文词汇，例如 “Chapter”（章）、“See”（参见）等。我们知道，这类单独的词汇通常无法孤立地进行翻译，而对于表意文字（及其他文字体系）而言，还需要一套截然不同的实现方案。欢迎为改进 Texinfo 的语言支持提供帮助。

如果运行的 TeX 程序具备相应支持， @documentlanguage 还会切换 TeX 当前的 断字模式 。标准的 tex 程序通常不支持这一功能，但更新版的扩展 TeX 程序一般都已支持： etex （输出 DVI）、 pdftex （输出 PDF）。若系统中存在这些扩展版本， texi2dvi 会自动使用它们（参见 “使用 texi2dvi 格式化”）。

由于语言代码和国家代码的列表更新相对频繁，本文档不尝试在此罗列。有效的语言代码可参阅 ISO 639 官方主页：http://www.loc.gov/standards/iso639-2/。ISO 3166 对应的国家代码及官方相关信息可通过https://en.wikipedia.org/wiki/ISO_3166查询。

默认情况下，文档的输入与输出编码均采用 UTF-8—— 这是一种通用的 8 位全局字符编码，与 7 位 ASCII 兼容。建议为 Texinfo 手册统一使用 UTF-8 编码。

@documentencoding 命令用于声明 输入文档编码 ，同时也会影响输出编码。如果你的文档编码不是默认值，请在文件开头附近单独一行书写该命令，并跟上合法的编码名称：

@documentencoding enc

UTF-8 始终是编码的最佳选择。Texinfo 仍支持其他编码，主要是为了兼容旧版手册⁸：

US-ASCII

基于英文字母的字符编码。

ISO-8859-1

ISO-8859-15

ISO-8859-2

分别对应 UTF-8 之前西欧（前两种）与东欧（第三种）语言的标准编码。ISO-8859-15 将 8859-1 中部分少用字符（如预制分数符号）替换为更常用的符号，例如欧元符号 €。

编码的完整说明不在本文范围内，可参考：http://czyborra.com/charsets/iso8859.html

koi8-rUTF-8

之前俄语常用编码。

koi8-uUTF-8

之前乌克兰语常用编码。

输出格式中的编码处理

Info 格式输出，会生成一段 ‘Local Variables’ （参见《GNU Emacs 手册》中的文件变量），包含输出编码，方便 Info 阅读器正确设置。如：

Local Variables:
coding: UTF-8
End:

默认情况下，对于 Info 与纯文本输出， texi2any 会尽可能将重音符号、特殊字符（如 @'e ）直接输出为对应输出编码下的 UTF-8 序列或 8 位字符。若无法实现，或使用了 --disable-encoding 选项，则改用 ASCII 转写。

HTML 输出，会在 HTML 的 ‘<head>’ 部分输出 ‘<meta>’ 标签，声明输出编码，供服务器与浏览器正确解析页面：