有没有关于公约当需要为包编写文档时(尤其是 .dtx 文件中的文档,而不是单独的文档)。我完成了我的第一个非平凡包,并想将其上传到 CTAN,我想为其编写一份好的标准文档,但我对以下几点不清楚:
- 在 .dtx 文件中,关于实现的部分是否应包含所有(每一行)代码。如果不是,我该如何放置将进入 .sty 文件但不进入文档的代码,我应该将其放在 iffalse 块中吗?
- 我注意到,宏代码环境中的行号仅计算文档中逐字出现的行,因此 .sty 的前几行(声明 TeX 格式,
\ProvidesPackage
任何\RequirePackage
)将抵消这一点。大概全局行号的全部意义在于用户可以跳转到 .sty 文件中的该行并找到他们要查找的内容。我如何在需要时手动移动当前行号(大概它保存在计数器中)? - 包含空白行和注释行(例如
------- INTERNAL MACRO DEFINITIONS -------
为了帮助直观地划分 .sty)是否被认为是不好的做法,当然还要将它们从文档中排除(参见第 1 点)?这些当然会弄乱行号,因此请参阅第 2 点。 - 应该与 一起
\RequirePackage
放在标签部分吗?<package>
\ProvidesPackage
- 我是否仍使用
macro
环境来记录部分实现(例如定义 tikz 样式)?如果是这样,我应该将什么作为“宏”名称,将其留空或不使用任何环境(只输入文本和macrocode
)?
PS 我找到的关于 .dtx 文件的唯一指南/教程(除了ltxdoc
和doc
文档docstrip
)是 Scott Pakin 编写的,这里,任何额外的资源都会有帮助。