☰

我可以将计算机代码与 LaTeX 文档交叉引用吗？

tag-icon • tag-icon cross-referencing literate-programming
我可以将计算机代码与 LaTeX 文档交叉引用吗？

我正在更新模拟模型的文档。在源代码、主要参考资料和现有文档中，每个参数和方程的表示方式都不同。

（这些可以在src/和documentation/目录中找到github 仓库）

即使在 LaTeX 文档中，我在解读方程式时也必须交叉引用参数表。但我还必须将这些参数和方程式与源代码中的参数和方程式进行匹配。

这是一个很令人头痛的问题，我想一定有一种更简单的方法来交叉引用 C 源代码和 LaTeX 文档。

我想知道是否已经有解决方案/包/程序可以帮助完成这项任务，例如，使

  1. 来自内联 C 文档的参考方程。
  2. 在 latex 中创建新命令，其名称以 C 源中的参数名称命名，例如\newcommand{wsun}{\omega_\text{sun}}。这样，至少参数名称在各种语言中都是一致的（并且便于搜索）。
  3. 将 C 代码解析为 LaTeX 方程式，例如从a = b*pow(c,2)到a=bc^2（类似于 Mathematica，但可能不切实际）

在开始讨论这些问题之前，我希望得到一些指导。我知道 Doxygen，但不清楚它是否能提供完整的解决方案。

答案1

这个问题有点难以回答，因为问题没有关于所需工作流程的背景，您是想从源代码生成文档，还是从文档生成源代码（“文学编程”的正常意义）或单独维护它们但使它们保持同步更容易。

无论你选择哪种方式，你都可以做一些事情来让事情变得更容易。我很难从你的存储库中找出哪段代码应该与文档中的哪一部分相关。用一些文件名标记文档可能会有所帮助。

但主要的困难是将代码中使用的标识符与文档源中的表达式进行匹配。为此，我将更改标记。

不要使用\Phi_N 和，而要T_\text{air}使用\id{PhiN}和\id{Tair}或其他命令\id，但要使用与源中相同的标识符名称。

然后您可以使用

\def\id#1{%
  \expandafter\ifx\csname id-#1\endcsname\relax
    \mathrm{#1}%
  \else
    \csname id-#1\endcsname
  \fi}

和...一起

\@namedef{id-Phi}{\Phi}
\@namedef{id-Tair}{T_{\mathrm{air}}

这样它就可以按照指定的方式排版已知的标识符，并将其用于\mathrm其他任何内容。

这样，就可以轻松地对所有标识符使用一致的排版形式，并且可以轻松地在表达式的代码和文档视图之间切换。

当然，你可以对函数做类似的事情，如果你定义

\def\pow(#1,#2){#1^{#2}}

你可以将你的例子写成

a = b*\pow(c,2)

再次使来源和文献更加接近。

一旦你通过这种方式同步了所有内容，那么产生来自文档的源表达式。要么使用 TeX 本身来写出代码，要么使用 perl 或类似程序来预处理文件，提取适当标记的表达式并将它们插入到 C 源中标记的位置（例如，通过一些风格化的注释语法）。如果您走到这一步，您基本上已经实现了自己的文学编程系统，因此使用其中一种 *WEB 变体可能会更简单，但它的好处是可以逐步实现，而不需要将源代码完全重写为新的标记系统作为初始阶段。

相关内容