|
doc 、ltxdoc 与
docstrip
编写宏包的目的是使用，为了能够广泛传播和正确使用并便于他人修改完善，宏包程序应当易于阅读，容易理解。所以，在编写宏包时，总要先说明编写的原因、目的和用途，然后开始编写具体宏命令程序；在一些繁琐复杂的内部命令处，附加详细的注释；专门提供给用户使用的命令或环境，都给出使用说明，或举例说明使用方法。这样，最终写成的宏包文件是宏命令程序+程序说明+使用说明合三为一的程序说明文件，这种编程方式被称作文学化编程。但在实际应用中，有些人出于研究借鉴的目的对这种合成文件很感兴趣，有些人只想看看该宏包的说明，更多的人只关心宏包的使用。
采用上列三个宏包来编写宏包文件就能很好地满足这些不同的需求。doc 是个编写宏包文件的宏包，它定义了一组宏包文件编辑环境和命令；ltxdoc 是用于排版 LaTeX 源文件的类型文件包；docstrip 是个文件分解工具，定义了一组文件输入和分类创建命令。下面举例说明它们的功能与用途。
首先，下载
iutheis.dtx，用 WinEdt 等编辑器打开，这是美国印第安纳州立大学博士论文样式类包的程序说明文件的源文件，它是按照 doc 格式要求编写的，在版本信息之后，有一段规定的驱动命令：
%<*driver>
\documentclass{ltxdoc}
导言区
\begin{document}
\DocInput{ltxdoc.dtx}
\end{document}
%</driver>，
当用 \documentclass 命令调用 ltxdoc 时，doc 宏包即被自动加载。导言区中的命令是用于设置所要创建的程序说明文件样式。
运行 PDFLaTeX 编译 iuthesis.dtx，得到 iuthesis.pdf，用
Adobe 打开，这是一篇包括
iuthesis 类包程序及其说明的程序说明文件，说明章节和每行命令都有分类序号，这既便于程序阅读又不影响日后程序或说明的修改升级。有些复杂的程序说明文件还有目录、索引和术语表等，也就是说 LaTeX 的所有功能都可以在此体现。
如果在导言区加入 \OnlyDescription 命令，再用 PDFLaTeX 编译 iuthesis.dtx，得到的 iuthesis.pdf 文件中就只有该类包的说明文字了。
如果只是要用其中的宏命令程序作为类包应用到论文写作，一般有两种方法：
方法一：调用 docstrip 工具，分解
iuthesis.dtx。运行
latex docstrip，出现设置对话窗口，见下图所示：
回答相关问题后，docstrip 自动从 iuthesis.dtx 剥离说明文字，摘取命令程序，创建类包文件 ltxdoc.cls。这种方法可举一反三，假如其中有宏包程序，可以将 cls 改为 sty，将class 改为 package，等等。
方法二：搜索并下载同名 .ins 安装文件，本例为
iuthesis.ins，这是个按照 docstrip 命令格式编写的文件，用于对程序说明文件（*.dtx）进行分类重建。用 PDFLaTeX
对其编译，就会自动创建类包文件 iuthesis.cls。
其实*.ins 安装文件的内容非常简单，主要就两句话：
第一句，\input docstrip.tex，调用 docstrip
工具；
第二句，\generateFile{*.cls}{f}{\from{*.dtx}{class}}，创建类包文件。
很多大型程序说明文件的源文件*.dtx 含有类包程序*.cls、宏包程序*.sty、说明或格式程序*.tex 和配置程序*.cfg 等多种程序，使用*.ins
安装文件的好处就在于它能够一次性自动地完成对*.dtx 文件的分类重建工作。本例就同时还分解出 iuthesis.tex，经编译后得到的 PDF
文件中只有该类包的说明。
很多数情况*.dtx 和*.ins
都是成对出现的；如果找不到*.ins，可以打开*.dtx 文件，根据里面的各种程序界定标记，使用第一种方法手工解包。现在有很多*.dtx 文件已将*.ins 的内容并入其中，这样用 PDFLaTeX
对其编译，就会自动同时创建出程序说明文件*.pdf 和宏包文件*.sty 或类包文件*.cls 等相关文件。
源文件
Frank Mittelbach et al
docmfp
它是对 doc 宏包功能的扩展，以适应编写含有非 LaTeX 命令程序的宏包程序说明文件，如 Metapost、C 或 Java 程序等。
源文件
Peter Wilson
hypdoc
使用该宏包可以为 doc 文件（*.dtx）添加书签和引用链接，书签的内容可以是章节目录、插图目录或表格目录等。在驱动程序段中使用 \usepackage{hypdoc}
命令时，doc 宏包便随之自动被加载。
源文件
Heiko Oberdiek
makedtx
编写宏包或类包文件时，一般都将各种类型的宏命令程序与其相关的说明和注释混合为一个*.dtx
文件，这样既便于传播下载，又能整体解包，一个不漏。然而，要对这种程序说明文件的源文件*.dtx 进行拼写检查或将其转换为 HTML
格式文件时就会出现问题。
makedtx 宏包套件可以帮助作者分别编写宏命令程序和程序说明，然后再将它们合为一个*.dtx 文件。
Nicola Talbot
|