翻译: GNU Texinfo 7.2

我们欢迎大家针对 Texinfo 系统的任意方面提交问题反馈与改进建议，涵盖程序运行、文档内容、安装部署等相关问题。请将反馈内容发送至邮箱：[email protected]。你可通过 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: 浮动元素目录