latex 注释_[LaTeX 尝试] 利用 PDF 附件和终端输出，从 Overleaf 里获得更多信息

本文已加入专栏文章目录，归入「宏包介绍」文章系列。

overleaf.com 是个提供在线版 LaTeX 的网站。在线版便利了使用，但因为 latex 运行在网站服务器上，排查分析某些问题时会不够方便。

本文以 minted 宏包项目的一个 issue 为例，介绍如何从 overleaf 里获得更多信息。本文的目的不是介绍该 issue 是如何解决的，而是介绍如何

• 借助 embedfile 宏包，把任意文件以附件形式插入 PDF；
• 借助 bashful 宏包，把终端的任意输出插入 PDF 页面。

示例描述

用户报告，用minted 排版汇编语言 GAS 时，遇到高亮错误。 具体为，若上一行包含注释，则下一行的操作符高亮颜色错误。（笔者不懂汇编，描述很可能有误。）

示例文件（节选自 issue）

documentclass{article}
usepackage{minted}

begin{document}
begin{minted}{gas}
  dec:
  cmp edi, 0 # comment
  je quit
  print:
  dec edi
  mov edx, 13 ; comment
  mov ecx, msg
end{minted}
end{document}

输出效果（已圈出两处高亮错误）

把辅助文件嵌入 PDF

minted 的工作方式，大致是

• 把源码存入辅助文件 jobname.pyg
• 调用 python 的 pygments 库，对 jobname.pyg 进行语法分析，分析结果输出为新的辅助文件，默认是 ./_minted-<jobname>/<long HEX number>.pygtex，文件内容是一个完整的 Verbatim 环境
• 在 latex 里读入 .pygtex 文件，同时删除 .pyg 文件

遇到 PDF 里发生 minted 高亮错误，第一步就是确认读入的 .pygtex 文件是否也包含相同的错误。

首先，找到 .pygtex 文件的文件名

在 overleaf 的界面里点开完整 log，搜索 "pygtex"，可知该文件的完整路径是 /compile/_minted-output/<long HEX number>.pygtex

然后，把这个文件以附件的形式嵌入生成的 PDF 文件

这里我们使用 embedfile 宏包，具体用法为

usepackage{embedfile}
embedfile[filespec=pygments-output.pygtex]{/compile/_minted-output/<long HEX number>.pygtex}

其中，选项 filespec 用于给嵌入的文件重命名。

这样，就能通过从 overleaf 下载 PDF，来查看 .pygtex 文件的内容。

在 PDF 里显示终端输出

在 issue 的例子中，我们确认了 .pygtex 文件中包含高亮错误，这说明问题出在 pygments 库。 结合本地无法复现该问题，我们猜测问题和 pygments 的版本差异有关。

这样，问题就转化为了，如何探知 overleaf 自带的 pygments 的版本。

首先，了解在本机上如何获取 pygments 的版本。

一种方式是在终端执行 pygmentize -V（pygmentize 是 pygments 库提供的可执行文件的名字）， 这会得到类似下方的版本信息

Pygments version 2.4.2, (c) 2006-2019 by Georg Brandl.

然后，了解如何在 overleaf 里执行终端命令，并使得执行结果可以被获取。

执行终端命令可使用 write18（见本专栏文章《LaTeX：与 write18 有关的小事》）。这里我们使用 bashful 宏包， 它便利了「执行命令、获取结果、在 latex 里输出结果」这个过程，而且适用于 overleaf 后台使用的 linux 操作系统。

bashful 的用法是这样的

% usepackage{bashful}

bash[stdout]
pygmentize -V
END

编译后就能在 PDF 里看到执行 pygmentize -V 获得的信息。在 issue 的例子中，我们就此知道了 overleaf 使用 pygments v2.2.0。

补充

1. embedfile 目前仅支持 pdftex 引擎
2. 在需要自动把宏包源文件存入 PDF 时，可以考虑使用进一步封装的 embedall 宏包
3. bashful 也适用于 macOS，稍作修改后即能用于 windows