☰

我如何记录我的风格文件？

tag-icon • tag-icon documentation package-writing documentclass-writing
我如何记录我的风格文件？

我在本地 texmf 树中编写了许多样式文件（以及一两个类文件）。大多数都是简单的东西，可以帮助我摆脱一些麻烦，我将它们放入样式文件中以备再次需要。有一两个相当复杂（可能没有必要）。

我的想法是我应该为这些文件添加一些文档。主要是为了我自己：虽然我定义东西的理由在我这样做的时候非常清楚，但明年当我再次尝试使用它时（或者更糟的是，再次尝试修改它）可能就不那么清楚了。对其他人来说也是如此，因为我有时会与合作者或任何说“嘿，这很棒！你是怎么做到的？”的人分享这些文件。但肯定不是上传至 CTAN。

所以我想为这些文件添加一些基本文档。因为这只是我自己的，我觉得我不想这么做也所以我想要的是一个尽可能接近以下参数的系统：

  1. 它应该是“在文件中”：我希望能够在定义命令的地方添加命令的文档。
  2. 该格式在未编译时应该是可读的：这是上述内容的必然结果，因为如果我希望能够立即读取它，我就不想先编译它。
  3. 但它应该是可编译的，以便我能如果我愿意，可以将其发送给其他人，而他们不必费力通过样式/类文件来查找文档。
  4. 然而，编译后的形式并不一定都那么漂亮。

有这样的系统吗？在 CTAN 上搜索“文档”就像在挪威搜索雪一样——虽然有很多雪，但对于局外人来说，很难弄清楚哪种雪才是正确的。如果没有一个系统可以做到我所描述的那样，我很乐意听听其他人尝试这样做的经历（事实上，无论如何我都很乐意听到他们的经历）。

答案1

标准是 DTX 格式，您可以将文档作为注释放在代码周围。通常在注释中，所有代码都包装在macrocode环境中，宏又包装在macro环境中。然后使用ltxdoc使用该doc包的类进行编译。

有关 DTX 的更多信息请参阅 TeX FAQ：https://texfaq.org/FAQ-dtx

例子：

% \begin{macro}{\mymacro}
% Some explanation
%   \begin{macrocode}
\def\mymacro#1#2{%
  \relax
  \dosomething
%   \end{macrocode}
% Explain the next part of the macro
%   \begin{macrocode}
  \domore
  \expandafter\some\code
}
%   \end{macrocode}
% \end{macro

请注意，您可以自动生成使用任何包或其他代码文件中的 DTX 文件sty2dtx脚本。

相关内容