伸脚地: 如何编写LaTeX宏包

看看别人怎么说

http://www.tex.ac.uk/cgi-bin/texfaq2html?label=writecls

什么是宏包

documentclass的参数和usepackage的参数可以概括的说都叫宏包，细分的话则分别称为class（如article, letter, book）和style（如graphicx, footmisc），其基本功能都是定义命令或者格式，没有明显的差别。在编写文档的时候，我们通常根据要求设置一些特殊的参数，比如页面高度，宽度，图形标题字体对齐方式等等。比较常见的办法就是把这些命令写在文档的导言区（preamble），宏包（或者模板）的作用就是把这些专门的配置单独写到一个文件里，方便用户的使用，也就是class和style存在的前提。

编写.cls/.sty

正如前面所说，class(.cls)和style(.sty) 就是命令和配置的集合，里面就是TeX和LaTeX 的语法。简单的说只要把原先导言区部分的内容转移到一个单独的文件（比如thuthesis.sty）再添加两个特殊的命令：

\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{thuthesis}[2005/07/06 0.1 Tsinghua University Thesis Template for Doctor and Master]
....

然后在源文件中就可以使用\usepackage{thuthesis}。唯一需要注意的就是不要再用 makeatletter / makeatother¹。如果需要添加高级功能，比如处理特殊选项，条件判断添加其它文件等等，细节可以参看clsguide。Latex Doc目录中其它的pdf也可以参看。这部分暂时就不再详述，因为有很多资料都有介绍，而且大家也用的多。

高级办法doc/docstrip

自己编写.cls/.sty完全没有问题，但如果文档比较复杂，用户需要维护独立的说明文档，这个文档需要对不同的宏定义、环境定义以及选项进行说明：这个任务可能比较复杂。为解决这个问题，LaTeX提供了更好的工具，能混合代码和说明文档，这就是doc和docstrip。

doc

一个特殊的宏包，将代码和注释混合在一起，即所谓的“literate programming”。阅读系统中的doc.dvi或者下载 doc.dtx，然后latex doc.dtx，得到doc.dvi。一般情况 documentclass选用ltxdoc，这个类会直接调用doc，并定义了一些方便的命令。

docstrip

专门处理doc类文档(.dtx)的工具，一方面可以清楚注释，解析有用部分，生成不同目标文件；另一方面可以直接根据.dtx文档生成目标文件的说明文档。这就是“literate programming” 的好处。²

文档同doc可以在自己的tex系统找到，或者下载docstrip.dtx，再编译得到docstrip.dvi。

等不急了

if(impatient)
read http://www.tug.org/tex-archive/info/dtxtut/dtxtut.pdf
else
go ahead

仔细看一看

后面涉及的内容全部来自于来自上面提到的三个文档以及LaTeX Companion 2nd Edition。

概况

使用docstrip编写宏包通常需要两个文件：mypcak.ins和mypack.dtx。其中mypack是宏包的名字（当然也可以起别的名字，这样做完全是为了一致方便），mypack.ins是install file ，里面指出如何根据mypack.dtx生成mypack.cls（或者mypack.sty或者其它文件），结构简单，变化不大。mypack.dtx则是核心代码文件，同时这个文件也包含了mypack document的内容，是一个混合体。

.ins 结构

文档开头注释
\input docstrip (\keepsilent, \usedir)
\preamble \endpreamble：加入所有文件的头部注释信息
\generatefile{\file{dest.sty}}{\from{src.dtx}{tag}}
\Msg
\endbatchfile

参见示例。

.ins里面的配置

docstrip执行时读取一个名为docstrip.cfg的配置文件，一个重要的参数是 \BaseDirectory{}，指明系统tex路径，比如\BaseDirectory{/usr/local/texmf}。然后声明使用目录\DeclareDir{name}{tex/latex}，那么在.dtx中使用\usedirectory{name}实际上就是将文件放在/usr/local/texmf/tex/latex。

\UseTDS 则在声明了BaseDirectory之后，不用再繁琐的进行DecoareDir，而直接useDir，规则就是按章TeX Directory System的命名方法。

需要注意 的是docstrip不会自己创建文件夹，所以如果目标文件夹不存在，则需要用户自己建立。

\endbatchfile：使用docstrip工具文件法定结尾，之后内容将被忽略。

\askforoverwritetrue \askforoverwirtefalse：如果文件存在是否询问覆盖

\askonceonly：统一回答一次

\preamble \endpreamble：加入到所有文件的头部信息，前缀为%%（准确的说是\MetaPrefix）

\postamble \endpostamble：对照preamble，加在文件尾部

\declarepreamble\somename：定义新的头部信息（不同文件可能使用不同的头部）

\usepreamble\somename：使用名为somename的preamble

\nopreamble：不用任何premable

这三个都有对应的postamble

当然这些选项配置也可以直接写在.ins文件里。

.dtx 结构

.dtx文件被处理两次，第一次只处理一小部分（文档中用户看到的没有注释掉的部分，标以 driver的块），得到必要的第二步处理信息。第二此处理将忽略开头的%，所以要适当的使用 \iffalse\fi来避免有些部分可能引起的问题。这样的话.dtx文档看起来可能有点别扭，真正想要的部分乍一看都被注释了。第二步的主要作用是用来生成目标文件（其实就是宏包的文档）。这一步也正是docstrip的关键所在，实际上就是一个文本过滤的过程。这也就是.dtx 文件中为什么要设置一些标记tag，就是为了区分不同目标文件的代码部分。

对tag有两点说明：

行首标有的，此行会写入参数为tag的目标文件中。比如：\generatefile{\file{mypack.sty}}{\from{mypack.dtx}{sty}} 那么mypack.dtx中所有以为标志的行都要写入mypack.sty。
<*tag> 和表示将中间的一块代码都标以tag。

.dtx的结构基本如下：

版权说明
包信息

伪正文（唯一不被注释的部分）

%\iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{hpackagei}
\EnableCrossrefs %\DisableCrossrefs
\CodelineIndex   %index points to line number otherwise \PageIndex
\RecordChanges   %version control
% \OnlyDescription: only user doc, without source code
% \CheckSum{number}: check number of backslashes. if 0, just warning.
% \CharacterTable: same as \CheckSum
% \changes{ver}{date}{des}
% \DoNotIndex{macro1, macro2,...}: macros will not be indexed
\begin{document}
\DocInput{mypack.dtx} %only one line of \DocInput, NOTHING ELSE!
\end{document}
%
%fi

package代码以及文档部分

参见示例。

条件判断

有时候一个.dtx文件要产生多个目标文件，那么其中的代码就要根据不同的目标文件区分。最基本的办法就是tag标注，但情况可能更复杂。比如有些代码要同时出现在某几个文件中而不出现在另外几个文件中，这就需要docstrip提供一种判断功能，以进行代码选择判断。这就是 guard，用 < 和 > 括起来的布尔表达式，包括与(&)，或（¦），非（ !）三种基本操作。操作元素就是出现在generate中的参数。由于guard是用户指示（user directives），并不是代码本身内容，所以它前面也要加%。如果一个guard对应一个代码块，那么需要使用guard修饰符 * 和 / ，比如：

\generate{\file{mypack.cls}{\from{mypack.dtx}{cls}}
     \file{mypack.cfg}{\from{mypack.dtx}{cfg}}

%file mypack.dtx

% code 1
%<*cls|cfg>
\def\@myname{Xue Ruini}
...
%

% code 2
%<*cls>
\def\@myage{secret}
...
%

那么code1这部分代码在mypack.cls和mypack都会出现，而code2则只出现在mypack.cls中。

还有一个特殊的guard表达式就是 %<

注意事项

主要针对.dtx文档。

macro, environment 和 macrocode

格式如下：

% \begin{macro}{\YOURMACRO}
% Put explanation of |\YOURMACRO|’s implementation here.
%    \begin{macrocode}
\newcommand{\YOURMACRO}{}
%    \end{macrocode}
% \end{macro}

% \begin{environment}{YOURENV}
% Put explanation of |YOURENV|’s implementation here.
%    \begin{macrocode}
\newenvironment{YOURENV}{}{}
%    \end{macrocode}
% \end{environment}

用户所有的代码部分必须用macrocode包含起来（否则就出错了），外面可以用macro或者 environment，主要是用来添加说明内容的。

macrocode

\begin{macrocode}\end{macrocode}和行首的％之间必须为 4 个空格。一段说明：

Trivia: Only the \end{macrocode} needs this precise spacing and then, only for
typesetting the documentation. Nevertheless, it’s good practice to use “% ” for the
\begin{macrocode}, as well.

也就是说begin部分无所谓，end部分必须是4个空格。

verb

为了方便使用\verb，可以定义简写字符\MakeShortVerb{\¦}：用¦ ... ¦表示 \verb ¦ ... ¦ \DeleteShortVerb{\¦}：取消定义。其中¦可用其它字符代替。

StopEventually 和 Finale

\StopEventually{text}：分割用户说明部分和宏包代码部分（由\OnlyDescription控制），如果设置了\OnlyDescription，那么代码部分就不会显示，文档截止到\StopEventually 所在位置，并打印text；如果没有设置\OnlyDescription，text会被保存在\Finale中，在文档最后显示。也就是说不管有没有代码部分，text都要出现，可以认为它是必须出现的总结部分（比如bib）。

注释

因为%已经被定义为特殊的含义，它不能再作为doc部分的注释符号，docstrip重新定义了 ^^A 作为内部的注释标记，如：

% ...
% \author{Xue Ruini} ^^A This is author
% \maketitle

例子

.ins 示例

%%
%% Copyright (C) 2005 by Xue Ruini <xueruini@gmail.com>
%%
%% This file is part of the Thu-Thesis package project.
%% ---------------------------------------------------
%%
%% This file may be distributed under the conditions of the LaTeX
%% Project Public License, either version 1.2 of this license or (at
%% your option) any later version. The latest version of this license
%% is in
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% and version 1.2 or later is part of all distributions of LaTeX
%% version 1999/12/01 or later.
%%
%%

\input docstrip

\askonceonly
\keepsilent
\usedir{tex/latex/thuthesis}

\preamble

This is a generated file.

Copyright (C) 2005 by Xue Ruini <xueruini@gmail.com>


It may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.2
of this license or (at your option) any later version.
The latest version of this license is in

http://www.latex-project.org/lppl.txt

and version 1.2 or later is part of all distributions of LaTeX
version 1999/12/01 or later.

This file may only be distributed together with a copy of original
source files. You may however distribute original source files
without such generated files. Copying of this file is authorized
only if either:
(1) you make absolutely no changes to your copy, including name; OR
(2) if you do make changes, you first rename it to some other name.

To produce the documentation run the original source files ending
with `.dtx' through LaTeX.

\endpreamble

\generate{\file{thuthesis.cls}{\from{thuthesis.dtx}{cls}}}

\ifToplevel{
\Msg{***********************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* files into a directory searched by TeX:}
\Msg{*}
\Msg{* The recommended directory is TEXMF/tex/latex/thuthesis}
\Msg{*}
\Msg{* \space\space thuthesis.cls}
\Msg{*}
\Msg{* To produce the documentation run the files ending with}
\Msg{* `.dtx' through LaTeX.}
\Msg{*}
\Msg{* Happy TeXing}
\Msg{***********************************************************}
}
\endbatchfile

.dtx 示例

% \iffalse meta-comment
%
% Copyright (C) 2005 by Xue Ruini <xueruini@gmail.com>
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi

% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \< %   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%

%
% \iffalse
%<*driver>
\ProvidesFile{thuthesis.dtx}
%
%\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%\ProvidesClass{thuthesis}
%<*cls>
[2005/07/06 0.1 Tsinghua University Thesis Template for Doctor and Master]
%
%
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs
%\DisableCrossrefs % Say \DisableCrossrefs if index is ready
\CodelineIndex
\RecordChanges      % Gather update information
 %\OnlyDescription  % comment out for implementation details
 %\OldMakeindex     % use if your MakeIndex is pre-v2.9
\begin{document}
\DocInput{thuthesis.dtx}
\end{document}
%
% \fi
%
%
%
% \changes{v0.1}{2005/07/06}{Initial version}
% \GetFileInfo{thuthesis.cls}
%
% \DoNotIndex{\begin}
%
% \title{The \textsf{thuthesis} class\thanks{This document
% corresponds to \textsf{Xue Ruini}~\fileversion,
% dated \filedate.}}
% \author{Xue Ruini \\ \texttt{xueruini@gmail.com}}
%
% \maketitle
%
% \begin{abstract}
% Put text here.
% \end{abstract}
%
% \section{Introduction}
%
% Put text here.
%
% \section{Usage}
%
% \DescribeMacro{\YOURMACRO}
% Put description of |\YOURMACRO| here.
%
% \DescribeEnv{YOURENV}
% Put description of |YOURENV| here.
%
% \StopEventually{\PrintIndex}
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*cls>
\newif\ifthuthesis@typeinfo \thuthesis@typeinfotrue
\DeclareOption{notypeinfo}{\thuthesis@typeinfofalse}
%
%    \end{macrocode}
% \begin{macro}{\YOURMACRO}
% Put explanation of |\YOURMACRO|’s implementation here.
%    \begin{macrocode}
\newcommand{\YOURMACRO}{}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{YOURENV}
% Put explanation of |YOURENV|’s implementation here.
%    \begin{macrocode}
\newenvironment{YOURENV}{}{}
%    \end{macrocode}
% \end{environment}
% \Finale
\endinput

^[1]. 虽然在导言区部分这个对于包含@字符的命令是必须的。

^[2]. 这个和javadoc、python中的"""注释说明"""都很像。

伸脚地

2006-09-20

如何编写LaTeX宏包