☰

Common practises for documenting CTAN-packages

tag-icon • tag-icon packages ctan dtx
Common practises for documenting CTAN-packages

背景

我最近一直在考虑为 CTAN 做出贡献。这个问题在这方面有很多很好的链接。

但是：我注意到大多数（如果不是全部）软件包的文档布局都相同。因此，我开始对此进行一些研究，并遇到了 Documented LaTeX Format，我对它的常见应用方式有一些疑问。

这个答案建议您不必使用来记录包docstrip，而且我还没有在任何地方看到它说有是这种格式。

CTAN 的 dtx 教程很好地介绍了语法，我认为我已经了解了这部分内容。我的具体问题是：

我想知道

  1. 将文档与文件分开编写是否很常见（文盲(?)）？
  2. 如果您曾经编写过可以发布到 CTAN 的包，那么您是如何处理文档的？
  3. 与此相关的任何事我应该知道吗？
  4. TeX 常见问题解答提到了“sty2dtx”，它“尝试从带有注释的‘普通’sty 文件创建 dtx 文件”。你试过这个吗？效果好吗？
  5. .dtx从.sty文件生成文件的好方法有哪些

如果我知道与此相关的任何信息我将不胜感激。

编辑：我可以说我只会编写与统计、数学、物理等相关的包。

答案1

CTAN 不需要 dtx 文件。CTAN 需要文档——大多数情况下是 PDF 文件。如何制作由您决定。

尽管如此，LaTeX 软件包的实际标准是将它们包装到 dtx 文件中。在最简单的情况下，这意味着获取您的 sty 文件并在代码之前和之后添加一些注释。详细信息已在您已引用的文档中描述。

我已经做到了，它比痛苦更有趣；-) 我从未觉得我需要一个工具来支持我。编写 LaTeX 代码即使它出现在注释中也很简单。

答案2

In general I write (documented) code using doc/docstrip. From a single source I can generate a User Manual, Documented Code, and Plain Code. This has made maintenance and code extensions relatively easy as everything is in one place rather than having to remember to update N other files.

I was so comfortable with this that, lost in the midst of time when I was a paid employee, I extended the doc/docstrip system to cater for other programming languages such as Metafont/Metapost. C and EXPRESS (an ISO 10404 Information modelling language I helped to develop).

It really enabled me to keep everything in one place. In the case of the memoir class I wrote a separate User Manual because of the size of the overall documentation; effectively I split a 2000- page document into two reasonably sized productions aimed at different audiences.

相关内容