LaTeX2e源码中`@@`符号的文档规范问题解析

问题背景

在LaTeX2e项目的源码文档中，维护者发现多处出现了未正确解析的@@符号，这些符号本应显示为对应的模块名称。这种现象主要出现在几个关键模块的文档说明部分，包括lthooks、ltmarks、ltfilehook等核心组件。

技术细节分析

@@符号在LaTeX的expl3编程接口中具有特殊含义，它代表当前模块的命名空间前缀。在文档生成过程中，这些符号应当被自动替换为实际的模块名称。出现未替换的情况通常表明文档生成流程存在以下两类问题：

1. 文档命令支持不足：例如\DescribeMacro命令在设计时未考虑处理@@命名约定，因为通常不会用这种方式描述内部命令。

2. 变更日志处理策略：对于代码变更记录(\changes条目)，项目维护者决定保留原始的@@形式，因为这更贴近实际的代码实现层面，便于开发者直接对应源代码。

具体问题实例

在lthooks模块中，文档出现了\g_@@_⟨hook⟩_code_prop这样的未解析形式，而它本应显示为带有模块前缀的完整名称。类似地，在描述\ClearHookRule功能时，@@_rule_gclear:nnn缺少了必要的反斜杠转义。

ltmarks模块的\mark_copy_structure:nn描述中，\@@_update_singlecol_structures:等内部命令名称也未正确展开。ltfilehook模块的\IncludeInRelease部分同样存在@@_set_curr_file:nNN命令缺少反斜杠的问题。

解决方案与最佳实践

项目维护者采取了差异化的处理策略：

1. 直接描述内部命令时：采用手动替换的方式，使用完整的实际命令名称替代@@占位符。

2. 变更日志记录时：保留原始的@@形式，因为变更日志主要面向开发者，直接显示代码层面的原始名称更有利于代码审查和版本比对。

这种处理方式既保证了文档的可读性，又维护了开发文档的准确性，体现了LaTeX项目在开发者文档与用户文档之间的平衡考量。

对开发者的启示

这个问题反映了文档系统设计中需要考虑的几个重要方面：

1. 需要明确区分面向开发者的技术文档和面向最终用户的功能文档
2. 文档生成工具需要与代码命名约定保持同步
3. 对于内部实现细节的文档，有时直接展示原始代码形式反而更有利于开发者理解

LaTeX2e项目对此问题的处理方式为其他大型TeX项目提供了很好的参考，展示了如何在保持文档准确性的同时兼顾不同受众的需求。