☰

如何修改 latex 包文档

tag-icon • tag-icon packages documentation
如何修改 latex 包文档

假设我想修改某个包的文档。我下载了.dtx和.ins文件，发现文档在文件中.dtx，但被注释了。如果我编译该.ins文件，就会得到该.sty文件。为什么文档被注释了，我该如何获取.pdf？

答案1

尽管我编写过一些 dtx 文件，但我并不是这方面的专家。如果我没记错的话，我拿了一个现有的 .dtx 文件，并根据我的需要对其进行了改编。因此，我在sample.dtx下面提供了一个非常精简的文件（以及相关的sample.ins）。在其中，我展示了从中提取的sample.sty和文件。sample.pdf

需要注意的一些要点如下：

A. ins 文件中的行\generate{\file{sample.sty}{\from{sample.dtx}{package}}}表示在 dtx 文件中查找被标识为“包”的行。这些行以两种方式标识：

  1. 以 开头的行<package>标识包，并以 sty 文件结尾。

  2. %<*package>dtx 文件中的分隔%</package>符将所有中间行标识为“包”，用于提取sample.sty。在此范围内，以单数开头的任何内容%都不会提取到 sty 文件中，但以%% 是作为注释提取到 sty 文件中。

B. dtx 文件使用ltxdocdocument 类。它遵循不同的规则。我并不完全了解，但以下是一些要点：

  1. %<*driver>和分隔符%</driver>以标准 LaTeX 方式提供编译 dtx 文档可能需要的代码定义。

  2. 和区域周围的\iffalse和分隔符是必需的。如果省略，编译会失败。\fi<package><driver>

  3. 该\CheckSum{}宏是可选的，用于在文件传输后保证文件的完整性。如果参数不正确，它会在编译期间生成错误，告诉您它期望的校验和以及您指定的校验和。作为包开发人员，您将参数值编辑为与编译器告诉您的相同，然后错误就会消失。如果文件在传输过程中损坏，错误将再次出现（使用现代传输错误更正，这是一种古雅的回归）。

  4. 在%</driver>和% \fi行之后，dtx 文档编译遵循ltxdoc规则，其中%从每行中删除前导以创建文档。

  5. 环境% \begin{macrocode}...% \end{macrocode}（其中 和 之间的四个空格字符%必不可少\begin）分隔将显示为逐字代码的代码。在本例中它将被编号，因为\CodelineNumbered是代码中的一个选项<driver>。

  6. 环境\begin{macro}{宏名}...\end{macro}用于封装相关macrocode环境定义宏名以及该宏的描述。

  7. 根据 LaTeX Companion，\StopEventually{}将源文件分为“用户文档”和“实现”部分。

  8. 至于\Finale，这将运行之前延迟的所有内容\StopEventually，但在这个特定的例子中它实际上什么也不做。

随着 .ZIP 文件的出现，我认为对 dtx 格式的需求可能会减少。但在 .ZIP 出现之前，将代码和文档放在一个文件中是一个很大的优势，无论是对于版本控制还是数据传输。

这个sample.dtx文件足够小，希望您能轻松地跟踪其各个部分。至于如何修改文档，您可以在此 dtx MWE 中轻松看到文档的不同部分的来源。因此，我希望它可以帮助您了解 dtx 的哪些部分被修改以反映文档中的更改。

% \CheckSum{9}
% \iffalse
%%
%% sample.sty
%% Comments and license info
%%
%<package>\ProvidesPackage{sample}
%<package>[2015/02/16 v1.00
%<package> Tools for absolutely nothing]
%<package>\NeedsTeXFormat{LaTeX2e}
%<*driver>
% V1.00-Initial release (version control could go here)
\documentclass{ltxdoc}
\usepackage{sample}
\DisableCrossrefs
\CodelineNumbered
% DEFINE SOME COMMANDS THAT ARE EASIER HERE THAN IN DocInput ENVIRONMENT
\let\iq\itshape%     SHORTHAND FOR ITALIC  FONT
\let\uq\upshape%     SHORTHAND FOR UPSHAPE FONT
\newcommand\sample{\textsf{sample}}
\GetFileInfo{sample.sty}
\begin{document}
   \title{The \textsf{sample} Package\\
         \rule{0em}{0.7em}\small\fileinfo}
   \author{A. Nonymous\\
           [email protected]}
   \date{\filedate\\
         \fileversion}
   \maketitle
   \DocInput{sample.dtx}
\end{document}
%</driver>
% \fi
% \parskip 1ex
% \begin{abstract}
% This is the package abstract
% \end{abstract}
%
% \tableofcontents
%
%\noindent\hrulefill
%
% \section {Introduction}
%
% blah-blah
%
% \subsection{Commands}
%
% This \sample{} package provides the macros named:
% 
% \noindent
% |\sampleA[|\iq integer\uq|]{|\iq text\uq|}|\\
% |\sampleB[|\iq integer\uq|]{|\iq text\uq|}|
%
% Here is a description of their use.
% 
% \DescribeMacro{\sampleA}
% The routine |\sampleA| is useful for nothing.
%
% \DescribeMacro{\SampleB}
% Likewise, the macro |\sampleB| is also pretty much useless.
%
% \section{Sample Usage}
%
% The code |\sampleA[3]{test}\sampleB[5]{I win.}| will result in
%
% \sampleA[3]{test}\sampleB[5]{I win.}
%
% This package provides little utility. The only thing left
% is the code listing itself.
%% \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         \~}
% \StopEventually{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{macro}{sample.sty}
% \section{Code Listing}
% I'll try to lay out herein
% the workings of the \sample style package.  
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{mysample}
% We start by defining and initializing the counter that is used.
%    \begin{macrocode}
\newcounter{mysample}
\setcounter{mysample}{0}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sampleA}
% The routine |\sampleA| will do absolutely nothing,
% except for setting |mycounter| to the value of |#1|.
%    \begin{macrocode}
\newcommand\sampleA[2][0]{%
  \setcounter{mysample}{#1}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sampleB}
% The routine |\sampleB| will output |\themysample|
% surrounded by brackets.  It
% will then store |#1| as the counter |mysample|.
% Finally, it outputs |#2| followed by ``NOT!''.
%    \begin{macrocode}
\newcommand\sampleB[2][0]{%
  [\themysample]
  \setcounter{mysample}{#1}%
  #2 NOT!
}
%    \end{macrocode}
% \end{macro}
%
% We are done now.
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput
%
%End of file `sample.dtx'.

这是sample.ins用于从 dtx 文件中提取 .sty 文件的文件：

% LaTeX this .ins file in order to generate the .sty file from the .dtx file
\input docstrip
\askforoverwritefalse
\generate{\file{sample.sty}{\from{sample.dtx}{package}}
         }
\endbatchfile

如果我编译该sample.ins文件，sample.sty则会提取以下文件：

%%
%% This is file `sample.sty',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% sample.dtx  (with options: `package')
%% 
%% IMPORTANT NOTICE:
%% 
%% For the copyright see the source file.
%% 
%% Any modified versions of this file must be renamed
%% with new filenames distinct from sample.sty.
%% 
%% For distribution of the original source see the terms
%% for copying and modification in the file sample.dtx.
%% 
%% This generated file may be distributed as long as the
%% original source files, as listed above, are part of the
%% same distribution. (The sources need not necessarily be
%% in the same archive or directory.)
%%
%% sample.sty
%% Comments and license info
%%
\ProvidesPackage{sample}
[2015/02/16 v1.00
 Tools for absolutely nothing]
\NeedsTeXFormat{LaTeX2e}
%% \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         \~}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcounter{mysample}
\setcounter{mysample}{0}
\newcommand\sampleA[2][0]{%
  \setcounter{mysample}{#1}%
}
\newcommand\sampleB[2][0]{%
  [\themysample]
  \setcounter{mysample}{#1}%
  #2 NOT!
}
\endinput
%%
%% End of file `sample.sty'.

另一方面，如果我编译sample.dtx，我会得到以下 PDF：

在此处输入图片描述

在此处输入图片描述

相关内容