LaTeX/创建包文档
文档对于最终用户来说非常重要，可以让他们快速了解如何使用您的包。它们也对其他开发人员有帮助，因为它们可以使阅读您的代码更容易。每种编程语言都有自己的文档编写方式。对于 LaTeX，我们从.dtx文件生成 pdf 文档。
.dtx后缀是documentation TeX的缩写。它具有两种功能
- 向用户解释如何使用包中的命令
- 格式化源代码以方便阅读
假设您想要为新创建的包编写文档，该包名为mypackage例如。 的基本结构.dtx文件如下所示
% \iffalse meta-comment
% Add copyright,author,version information
% here for this documentation file
% \fi
% \iffalse
%<*driver>
\ProvidesFile{mypackage.dtx}[1.0 My package]
\documentclass{ltxdoc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% write normal LaTeX documentation content here
% \Finale
%
\endinput
|
当您运行pdflatex mypackage.dtx，您可以生成mypackage.pdf，即手册。在这个 pdf 文件中，\fi 和 \endinput 之后的全部内容都会从注释中剥离出来，并插入到文档之间。注意，当 LaTeX 引擎第一次遇到 \DocInput 时，它会再次读取同一个文件，但会剥离所有以 % 开头的行。结果是，它会忽略包含 \iffalse ...\fi 的代码块。还应注意，同一个文件的第二次传递也会忽略 %<driver> 和 %<*driver> 之间的魔法注释。指示符 **driver** 表明内部内容是生成最终手册的包装器，您可以根据需要用其他单词替换它们。
有一些宏需要进一步解释
\ProvidesFile{<name>}[<version>]的工作原理类似于\ProvidesPackage{<name>}[<version>]，它将方括号中的内容写入日志文件。- 元注释用于提供.dtx文件本身的信息。由于您不能使用正常的 TeX 注释，因为它们会被剥离。
- ltxdoc类似于其他文档类，并提供一些易于使用的命令来编写包文档，如下所示。
要描述在您的包中定义的宏，您可以使用
% \begin{macro}{\mymacro}
% mymacro definition goes here
% \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}{create my package.}
|
在您想要索引出现的位置添加 \PrintChanges。更改将使用术语表支持进行记录，调用makeindex从命令行
makeindex -s gglo.ist -o mypackage.gls mypackage.glo