LaTeX

文档
文档对于最终用户来说非常重要，能够帮助他们快速了解如何使用你的包。同时，文档对其他开发人员也有帮助，因为它们使阅读代码变得更加容易。每种编程语言都有其生成文档的方式。对于 LaTeX，我们通过 .dtx 文件生成 PDF 文档。

.dtx 后缀是 documentation TeX 的缩写。它有两种功能：

• 向用户解释如何使用包中的命令

• 格式化源代码以便于阅读

基本结构
假设你想为新创建的包（例如 mypackage）编写文档。基本的 .dtx 文件结构如下所示：

% \iffalse meta-comment
% 在此处添加版权、作者、版本等信息
% \fi
% \iffalse
%<*driver>
\ProvidesFile{mypackage.dtx}[1.0 My package]
\documentclass{ltxdoc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% 在此处编写常规的 LaTeX 文档内容
% \Finale
%
\endinput

当你运行 pdflatex mypackage.dtx 时，可以生成 mypackage.pdf，这是手册。在该 PDF 文件中，所有 \fi 和 \endinput 后的内容将被从注释中剥离，并插入到文档中。请注意，第一次 LaTeX 引擎遇到 \DocInput 时，它会再次读取相同的文件，但会去除所有以 % 开头的行。因此，它会忽略 \iffalse ... \fi 代码块。还应注意，同一文件的第二次运行也会忽略 %<driver> 和 %<*driver> 之间的魔法注释。driver 指示符表示内部内容是用于生成最终手册的包装器，你可以根据需要将它们替换为其他单词。

以下是一些需要进一步解释的宏：

• \ProvidesFile{<name>}[<version>] 类似于 \ProvidesPackage{<name>}[<version>]，它将方括号中的内容写入日志文件。

• meta-comment 用于提供 .dtx 文件本身的信息。由于不能使用正常的 TeX 注释（因为它们会被剥离），因此使用了这种方式。

• ltxdoc 类似于其他文档类，并提供一些易于使用的命令来编写包文档，下面将对此进行说明。

新宏描述
要描述你在包中定义的宏，可以使用以下方式：

% \begin{macro}{\mymacro}
% mymacro 的定义在这里
% \end{macro}

macro 环境接受一个强制参数，这是宏的名称，并且该名称会显示在左边的边距上。你还可以使用 \DescribeMacro{mymacro} 并将额外的解释放在普通文本中。对于新环境的描述，你可以使用 \DescribeEnv{mynewenv}。它们的区别在于索引条目的类型，下面将对此进行说明。

索引条目和变化
在包文档文件的前言中添加 \EnableCrossrefs（没有注释的行开头）。在你希望索引出现的位置添加 \PrintIndex。你描述的所有宏将被打印在文档的末尾。有关编制索引的一般介绍，请参见 编制索引。通常，下面的命令足够了：

makeindex -s gind.ist -o mypackage.ind mypackage.idx

ltxdoc 还提供记录包变化的功能。要启用此功能，请在前言中添加 \RecordChanges 并使用以下命令：

\changes{v1.0}{2017/01/01}{创建我的包。}

在你希望索引出现的位置添加 \PrintChanges。变化将使用术语表支持进行记录，从命令行调用 makeindex：

makeindex -s gglo.ist -o mypackage.gls mypackage.glo