Skip to content

LaTeX 代码排版 ​

LaTeX 中常用 listings 或 minted 排版源代码。前者完全由 TeX 处理,配置简单。后者通过外部程序调用 Pygments,支持更多语言和更细致的语法高亮。本文的 minted 示例与环境说明以 3.x 为准。

1 选择宏包 ​

对比项listingsminted
外部程序不需要需要 latexminted 和 Pygments
语言支持常见语言Pygments 支持的语言
高亮效果基于关键词规则基于词法分析器
UTF-8 代码多字节字符支持有限默认使用 UTF-8
投稿兼容性通常更稳妥取决于编译环境是否允许外部程序
配置复杂度较低较低,但依赖编译环境

期刊模板没有特殊要求时,选一种统一使用即可。listings 和 minted 各有自己的环境、参数和代码清单目录命令,分别配置后也可共存。

2 使用 listings ​

2.1 完整示例 ​

latex
\documentclass{article}
\usepackage{xcolor}
\usepackage{listings}

\definecolor{codebg}{RGB}{248,248,248}

\lstdefinestyle{code}{
  backgroundcolor=\color{codebg},
  basicstyle=\ttfamily\small,
  keywordstyle=\color{blue!70!black},
  commentstyle=\color{green!40!black},
  stringstyle=\color{orange!60!black},
  numbers=left,
  numberstyle=\tiny\color{gray},
  numbersep=8pt,
  frame=single,
  rulecolor=\color{black!15},
  breaklines=true,
  breakatwhitespace=false,
  showstringspaces=false,
  keepspaces=true,
  columns=fullflexible,
  tabsize=4,
  captionpos=b
}

\begin{document}

\begin{lstlisting}[
  style=code,
  language=Go,
  caption={A worker function},
  label={lst:worker}
]
package main

func worker(jobs <-chan int, results chan<- int) {
    for job := range jobs {
        results <- job * job
    }
}
\end{lstlisting}

Listing~\ref{lst:worker} receives jobs and sends results.

\end{document}

\lstdefinestyle 用于保存一组配置,后续代码块通过 style=code 复用。局部参数会覆盖同名的全局参数。

2.2 内联代码 ​

latex
Use \lstinline[language=Go]|make(chan int)| to create a channel.

分隔符不一定使用 |,只要该字符没有出现在代码内容中即可。

2.3 引入外部文件 ​

latex
\lstinputlisting[
  style=code,
  language=Go,
  firstline=5,
  lastline=12,
  firstnumber=5
]{worker.go}

firstline 和 lastline 选择源文件范围,firstnumber 控制显示的起始行号。论文中的代码来自真实项目时,引用外部文件比复制代码更容易维护。

2.4 常用参数 ​

参数作用
language=Go指定语言
numbers=left在左侧显示行号
firstnumber=10设置起始行号
breaklines=true自动折行
showstringspaces=false不标记字符串中的空格
keepspaces=true保留代码中的空格
columns=fullflexible按当前字体的自然字符宽度排版
frame=single添加边框
caption={标题}添加标题
label={lst:key}设置交叉引用标签
float=tbp把代码块作为浮动体

较长代码使用非浮动环境,可随正文分页。设置 float 后,代码块会作为整体排版。

3 使用 minted ​

3.1 完整示例 ​

latex
\documentclass{article}
\usepackage{xcolor}
\usepackage{minted}

\definecolor{codebg}{RGB}{248,248,248}

\setminted{
  fontsize=\small,
  linenos,
  breaklines,
  breakanywhere,
  autogobble,
  frame=single,
  framesep=2mm,
  bgcolor=codebg
}

\begin{document}

\begin{listing}[tbp]
\begin{minted}{go}
package main

func worker(jobs <-chan int, results chan<- int) {
    for job := range jobs {
        results <- job * job
    }
}
\end{minted}
\caption{A worker function}
\label{lst:minted-worker}
\end{listing}

Listing~\ref{lst:minted-worker} is highlighted by Pygments.

\end{document}

\setminted 设置全局参数。也可以写成 \setminted[go]{...},只对 Go 代码生效。

3.2 内联代码 ​

latex
Use \mintinline{go}|make(chan int)| to create a channel.

3.3 引入外部文件 ​

latex
\inputminted[
  firstline=5,
  lastline=12,
  firstnumber=5,
  linenos
]{go}{worker.go}

语法为 \inputminted[参数]{语言}{文件名}。外部文件默认按 UTF-8 解码。

3.4 浮动代码清单 ​

listing 环境提供标题、编号和交叉引用,其行为与 figure、table 类似:

latex
\begin{listing}[tbp]
\begin{minted}{go}
func add(a, b int) int {
    return a + b
}
\end{minted}
\caption{Add two integers}
\label{lst:add}
\end{listing}

浮动代码清单不能跨页。长代码直接使用非浮动的 minted 环境,可随正文分页。

3.5 编译权限 ​

minted 3 使用 latexminted 生成高亮结果,不再直接调用 pygmentize。通过 TeX 发行版的包管理器安装时,会一并提供 Pygments 等 Python 库,但运行环境仍需能找到 Python 3.8 或以上版本。

更新到相应版本的 TeX Live 2024 及以上环境已将 latexminted 加入受信任程序列表。在启用受限 shell escape 的默认配置下,通常可以直接编译:

sh
xelatex main.tex

minted 2.x、未加入该受信任程序的旧版 TeX Live,以及未授权 latexminted 的 MiKTeX 环境仍需额外配置。TeX Live 必要时使用:

sh
xelatex -shell-escape main.tex

MiKTeX 官方对应选项为 -enable-write18。这些选项允许 LaTeX 执行不受受信任程序列表限制的外部命令,只应在确有需要时对可信文档启用。

4 排版细节 ​

4.1 长代码行 ​

listings 使用 breaklines=true。minted 使用 breaklines,必要时再加 breakanywhere。自动折行用于调整代码的显示布局。

4.2 缩进与制表符 ​

论文代码最好统一使用空格缩进。制表符宽度在不同工具中可能不一致:listings 使用 tabsize,minted 使用 tabsize。

4.3 中文注释 ​

listings 对多字节 UTF-8 源文件支持有限,中文注释可能需要额外转换或转义。直接排版含中文的 UTF-8 源代码时,可使用 minted,配合 XeLaTeX 或 LuaLaTeX,并配置支持中文的文档类和字体。例如使用 ctexart,再通过 \setmonofont 设置合适的等宽字体。

4.4 在代码中插入 LaTeX ​

使用 escapeinside 指定分隔符,分隔符内的内容按 LaTeX 排版:

latex
% listings
\begin{lstlisting}[escapeinside={(*@}{@*)}]
x := 1 // (*@\textit{initialize}@*)
\end{lstlisting}

% minted
\begin{minted}[escapeinside=||]{go}
x := 1 // |\textit{initialize}|
\end{minted}

5 常见问题 ​

5.1 找不到语言 ​

先确认语言名称是否被当前宏包版本支持。listings 中本例使用 Go,minted 中使用 Pygments 的 go 别名。两套语言名称不完全相同,旧版 listings 也可能尚未提供对应语言。

5.2 minted 无法执行 ​

依次检查 TeX 是否能找到 minted.sty、latexminted 和 Python 是否位于 PATH,再检查当前 TeX 发行版是否允许执行 latexminted。

5.3 代码超出页边距 ​

确认已启用自动折行。若某个很长的标识符仍无法换行,minted 可以增加 breakanywhere,listings 可以调整 breakatwhitespace。

5.4 行号与源文件不一致 ​

截取外部文件时,同时设置 firstline 和 firstnumber。前者控制读取位置,后者只控制打印出来的数字。

5.5 特殊字符报错 ​

代码中的特殊字符可由 lstlisting、minted、\lstinline 或 \mintinline 原样处理,也可以在普通正文中逐个转义。直接写进正文时,#、%、_、{、} 等字符仍会按 LaTeX 语法解析。

Released under the MIT License.