软件包文档的约定

软件包文档的约定

有没有关于公约当需要为包编写文档时(尤其是 .dtx 文件中的文档,而不是单独的文档)。我完成了我的第一个非平凡包,并想将其上传到 CTAN,我想为其编写一份好的标准文档,但我对以下几点不清楚:

  1. 在 .dtx 文件中,关于实现的部分是否应包含所有(每一行)代码。如果不是,我该如何放置将进入 .sty 文件但不进入文档的代码,我应该将其放在 iffalse 块中吗?
  2. 我注意到,宏代码环境中的行号仅计算文档中逐字出现的行,因此 .sty 的前几行(声明 TeX 格式,\ProvidesPackage任何\RequirePackage)将抵消这一点。大概全局行号的全部意义在于用户可以跳转到 .sty 文件中的该行并找到他们要查找的内容。我如何在需要时手动移动当前行号(大概它保存在计数器中)?
  3. 包含空白行和注释行(例如------- INTERNAL MACRO DEFINITIONS -------为了帮助直观地划分 .sty)是否被认为是不好的做法,当然还要将它们从文档中排除(参见第 1 点)?这些当然会弄乱行号,因此请参阅第 2 点。
  4. 应该与 一起\RequirePackage放在标签部分吗?<package>\ProvidesPackage
  5. 我是否仍使用macro环境来记录部分实现(例如定义 tikz 样式)?如果是这样,我应该将什么作为“宏”名称,将其留空或不使用任何环境(只输入文本和macrocode)?

PS 我找到的关于 .dtx 文件的唯一指南/教程(除了ltxdocdoc文档docstrip)是 Scott Pakin 编写的,这里,任何额外的资源都会有帮助。

相关内容