本文已加入专栏文章目录,归入「宏包介绍」文章系列。
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。
补充
embedfile
目前仅支持 pdftex 引擎- 在需要自动把宏包源文件存入 PDF 时,可以考虑使用进一步封装的
embedall
宏包 bashful
也适用于 macOS,稍作修改后即能用于 windows