☰

是否有针对 LaTeX 2e 包以及这些包中定义的控制序列寻找好名称的指导原则？

tag-icon • tag-icon macros best-practices naming
是否有针对 LaTeX 2e 包以及这些包中定义的控制序列寻找好名称的指导原则？

我编写了一些代码，想要将其作为 LaTeX 2e 包提交给 CTAN。（readme、dtx、ins、带有手册和注释源的 pdf。）

我需要给包裹起一个好名字。
问题：是否有一些指南可以帮助找到适合 LaTeX 2e 包的良好指导名称？

此外，包中定义的控制序列标记需要好的指导性名称，以便读者可以轻松推断出控制序列标记所起的作用，并且不会导致与内核/其他包发生名称冲突。
问题：是否有指导原则可以帮助人们为想要在包中定义的控制序列标记找到好的指导性名称？

现在我打算做如下事情：

用户在前言或文档环境中使用的宏应全部使用小写字母。这些名称应使用户能够推断出 a) 定义相关控制序列的包的名称以及 b) 相关控制序列的作用。

形成一些用于调整的“用户界面”的宏：与上文相同，但大小写字母混合。从宏名称中，还可以轻松推断出哪些用户级宏/文档级宏的工作流程将受到相关用户界面宏/调整宏的影响。

构成包所提供功能核心的内部宏：与上面相同，可能只有小写字母和一些内容，您可以从中看到所讨论的宏的“内部性”，还可以推断出编写该宏的作者。

最重要的一点是找到好的短语，这些短语不要太长，并且用户可以轻松从中推断出所讨论的宏的作用/用途。
问题：是否有指南可以找到好的指导短语，这些短语可以作为宏名称的一部分，并且用户可以轻松推断出所讨论的宏的作用/用途？

首先，假设完全可扩展的基于宏的“机制”，在宏扩展阶段，这些机制会导致执行或多或少棘手的算法，而理解所实施的算法可能已经成为一个问题，需要深入研究。
通过具有指导意义的宏名称，应该可以简化理解构成实现的组件之间的交互...
重点是：在这种情况下，我经常会得到宏名称，这些宏名称确实可以帮助我在半年后查看代码时理解事情，但对其他人理解事情却没有任何帮助。

我自己能想到的任何宏名称方案都会产生非常长的宏名称。;-)

答案1

包内部宏和用户宏的命名方案应该不同，因为它们有不同的用途。

内部命名约定

内部宏的命名应尽可能避免包冲突，其次应避免用户直接修改它们。大多数包和类都使用以下方案的某种变体：

  • 包内部前缀或后缀用 分隔@。前缀本身可能基于包名称，或作者的姓名首字母，或者其他不太可能产生冲突的方案。

例如，我维护一个密歇根州立大学的论文文档类，所有内部宏都使用前缀msu@。包内的命名约定可以根据需要尽可能具有描述性。我更喜欢相当具有描述性的名称，即使它们相对较长，因为它使代码更容易阅读。

  • \msu@degree
  • \msu@fieldofstudy

许多作者（尤其是使用 的作者docstrip）喜欢使用后缀而不是前缀，因为这会使文档中的宏索引更加有用。在这种情况下，上面的宏将是以下内容。（然后它们将被编入索引，d而f不是全部放在一个大m列表中。）

  • \degree@msu
  • \fieldofstudy@msu

用户宏

命名用户宏的标准略有不同。根据包提供的功能，命名冲突可能不是什么大问题，因为提供相同功能的两个包可能不会一起使用。但最好避免使用可能在多个包中使用的非常通用的名称。

长度和描述性之间的平衡非常主观。如果一个宏会被大量使用，那么长的名字可能不合适，但如果它在序言中使用一次，那么长度就不是什么问题了。

然而，一些作者也对用户宏使用前缀方法，因为这大大降低了冲突的风险。这种命名方案的一个显著示例是对所有用户宏datatool使用DTL前缀。此处的前缀是大写的，以将其与相对具有描述性的宏名称的其余部分区分开来。

  • \DTLloaddb
  • \DTLforeach

答案2

您可能会对以下资源感兴趣：

CTAN——综合 TEX 档案网络——如何上传包？

CTAN - 综合 TEX 档案网络 - CTAN 上传者的附加信息，尤其是“包 ID 的条件”部分。

在这里您可以找到以下指南和短语：

e. New pack­ages and bun­dles should not be named af­ter their au­thors,
   but af­ter the pur­pose they are serv­ing, be­cause they may later
   be taken over by other main­tain­ers. (We know that there are a few
   well es­tab­lished CTAN pack­ages that do not ful­fill this rule; but
   that comes un­der “pro­tec­tion of vested rights”, and we have now
   learned from his­tory.)

相关内容