☰

在正常使用 l3doc 类时，宏代码环境不起作用

tag-icon • tag-icon package-writing documentation docstrip
在正常使用 l3doc 类时，宏代码环境不起作用

我正在编写一个包含 .dtx 和 .ins 的包。我希望它的文档是双语的，但我不想让文档和源代码同时包含两种语言，从而使我的 .dtx 文件变得复杂，因此我将使用一种主要语言编写 .dtx，并使用另一个 .tex 文件生成文档，该文档理想情况下应与使用 .dtx 文件生成的文档完全相同。我正在使用l3doctex 文件的类。

目前我有以下 MWE：

% arara: pdflatex
% arara: pdflatex
% arara: clean: {
% arara: -->      extensions: [
% arara: -->        aux,log,glo,hd,idx,out,toc,tex~
% arara: -->      ]
% arara: -->    }
\documentclass{l3doc}

\begin{document}
\begin{documentation}
  \begin{function}{abcd}
    \begin{syntax}
      \cs{abcd}\marg{abcd}
    \end{syntax}
    Hello world
  \end{function}
\end{documentation}

\begin{implementation}
Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
\end{implementation}
\end{document}

它只有一个不起作用（但可能是最需要的）因素，即环境macrocode。我也尝试过用 .dtx 扩展名保存此代码，但结果相同。有没有办法获得特定的视觉输出，即对代码行进行编号并以等宽字体排版，而无需实际使用 .dtx 文件？也许我使用了错误的环境。我真正想要获得的是以下内容。

1

请建议正确的环境来获取此功能。

答案1

由于macrocode环境是逐字逐句的，因此需要精确的结束行匹配：在这种情况下

%    \end{macrocode}

那么你可以做

    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}

这显然不是一个好的结构，并且反映了这样一个事实：背后的整个逻辑doc就是你将用来\DocInput读取文件并改变%其工作方式。因此，你确实需要坚持预期的格式：

% \iffalse
\documentclass{l3doc}
\begin{document}
  \DocInput{\jobname}
\end{document}
% \fi
% \begin{documentation}
%   \begin{function}{abcd}
%     \begin{syntax}
%       \cs{abcd}\marg{abcd}
%     \end{syntax}
%     Hello world
%   \end{function}
% \end{documentation}
%
% \begin{implementation}
% Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
% Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
% \end{implementation}

这对于较小的包或需要将 API 文档与代码放在一起的情况很有效。但是对于较大的包，我强烈建议使用单独的.tex文件用户即使只有一种语言可以编写，我也需要编写文档。因此，尽管上述方法可行，但我还是会将您的代码和 API 信息写入其中，.dtx并.tex为用户文档。请注意，这些可以全部l3doc无需任何部件即可使用implementation。

相关内容