☰

如何使用 dtx 记录 expl3 宏

tag-icon • tag-icon documentation expl3 dtx
如何使用 dtx 记录 expl3 宏

expl3我正在为使用中实现的包编写文档ltxdoc，相关部分如下所示

% \begin{macro}{\conteq_args_once}
% Some explanation
%
%    \begin{macrocode}
\cs_new:Npn \conteq_args_once:Nn #1#2 {
   \exp_not:o {#1 {#2}}
}
\cs_generate_variant:Nn \conteq_args_once:Nn {NV}
%    \end{macrocode}
% \end{macro}

不幸的是，这给了我

! Missing $ inserted.
<inserted text> 
                $
l.385 % \begin{macro}{\conteq_args_once}

但\conteq\_args\_once:Nnn也不起作用。如何正确注释此类函数的文档？

答案1

虽然您可以启动 formltxdoc并“自行开发”，但建议使用l3doc，这是 LaTeX 团队为expl3自己使用的类。目前这是一个相当大的 hack 集合，但确实可以正确处理_名称之类的内容，并且还提供了比 更丰富的文档环境ltxdoc。遗憾的是，l3doc缺乏真正全面的文档：正如我所说，它的内部并不完美！l3doc.dtx但是，您可以排版以至少获取一些信息。

也许掌握这些知识的最好方法是查看一些 LaTeX3 源代码。我建议避免使用l3doc.dtx本身和，l3bootstrap.dtx因为它们并不常见：像 这样的代码可能是更好的选择。（除了 的使用之外，源代码还展示了团队标准化的“内部风格”。我们热衷于鼓励将其作为一种更通用的“代码风格”：虽然您可能不完全同意每个决定，但从长远来看，如果大多数代码无论作者是谁都看起来一样，那就太好了，因为这将有助于维护。）l3names,dtxl3basics.dtxl3clist.dtxl3docexpl3expl3

答案2

我所做的就是使用skdoc（这是我写的，尽管它是基于ydoc假设ydoc您加载expl3），并在文档的实施部分之前发出以下命令：

\ExplSyntaxOn
\cs_set_protected_nopar:Npn\ExplHack{
    \char_set_catcode_letter:n{ 58 }
    \char_set_catcode_letter:n{ 95 }
}
\ExplSyntaxOff
\ExplHack

这使得macro环境（以及\cs和朋友）在 LaTeX3 代码中适当地将下划线和冒号读取为“字母”（即宏名的一部分）。

答案3

我最近遇到了同样的问题，并看到了这篇文章。虽然最好采用l3doc另一个更高级的类，但现在我需要一个快速解决方案，因为我没有时间深入研究另一个文档类。对于那些处于相同情况的人：您可以添加

\def\MakePrivateLetters{
    \catcode`\@=11\relax
    \catcode`\_=11\relax
    \catcode`\:=11\relax
}

放入 dtx 文件中的驱动程序代码的前导码中，然后expl3名称就不再是问题了。

相关内容