LaTeX 宏包小记 (2): listings

本文及所附代码, 文件在版权协议下发布, 转载请注明出自

新年第一篇 post, 祝所有的读者新年快乐(只是不知道这么久都没有更新, 是否还有读者). 去年一年严格地说只写了2篇日志, 新年赶紧补上一篇吧.

这个 宏包的介绍系列我会坚持把它写下去. 很高兴地看到周围有更多的同学和老师(对, 最新见到几位听说/用过 的老师了), 这让我有更大的兴趣和信心继续介绍和普及 的知识了.

再次警告: 是一个较难上手的软件, 而且在熟悉后可能会使你成为一个完美主义者并再也不愿意使用 Microsoft Word.

言归正传, 为 实现代码高亮的宏包不可谓不多, listings 是我比较熟悉和常用的一个. 这里稍稍总结一下 listings 常用的参数, 更多的配置选项可以在它的手册里查到.

Getting started

listings 可以在 , 如果访问 CTAN 服务器的的速度太慢, 也可以在 CTeX 提供的 下载. CTAN 和 CRAN 的镜像可以分别在和查看. texlive 的各个版本里(至少是2008之后的各个版本里)都有这个宏包. 它的中文字体配置可以参见. 如果你使用 texlive. 你可以首先试试编译下面的代码来检验你的 listings 包是否安装成功了:

\documentclass{article} \usepackage{listings} \begin{document} \begin{lstlisting}[language=C, label=lst:helloworld, caption=Helloworld, numbers=left, basicstyle=\ttfamily] int main() { printf("Hello world!\n"); return 0; } \end{lstlisting} \end{document}

如果编译成功了, 那么你应该能看到如下图所示的文档.

第一眼看到这段代码我就觉得她有哪儿不对劲, 不过直到 yangyi 教主提醒我才发现它是用的 serif 字体排的代码, 难怪蛋疼.. 加上 basicstyle=\ttfamily 之后, 就会用等宽字体排版了. 但由于LaTeX自带的Computer Modern Typewriter等宽字体没有粗体, 会造成看不出代码高亮的效果(因为默认的代码高亮效果是粗体). 但如果使用 XeLaTeX 并调用 Consolas 或者 Courier 之类带粗体的等宽字体, 就能得到很好的效果.

Options

listings 包提供了 \lstset 命令, 可以用来设置排版出的代码效果的各种选项. 命令的格式是

\lstset{key=value}

下面的代码是我常用的 listings 设置, 从中你可以看出来它的格式是 key = value.

\lstset{numbers=none, numberstyle=\scriptsize, frame=none, flexiblecolumns=false, language=Python, basicstyle=\ttfamily\small, breaklines=true, extendedchars=true, escapechar=\%, texcl=true, showstringspaces=true, keywordstyle=\bfseries, tabsize=4}

常用的设置我都在下面做了简要介绍, 更多的设置请查阅手册.

Language

这应该是最重要的参数了, 它决定了有哪些关键词需要高亮. listings 支持的语言有很多, C/C++, Python, Ruby, Lisp 等许多语言. 详细的支持语言及其标准名称见 第12页 Table 1.

如果想输入等宽的纯文本文件, 可以使用 "language=".

Line Numbers

listings 能显示代码的行号, 相关的 key 有 numbers, numberstyle, stepnumber, numbersep, firstnumber, lastnumber.

numbers 的值可以是 left, right, none, 分别代表了将行号放在代码的左边, 右边和不显示.

numberstyle 的值设置了行号的样式, 可以是 \tiny 等设置字体大小的命令或是设置字体风更的命令.

stepnumber 的值设置了每多少行显示一次行号.

其它的参数我很少用到, 就不一一介绍了. 还是 RTFM(Read The Fucking Manual) 吧.

Frame

这个命令能让代码周围显示边框. 它的值可以是 none|leftline|topline|bottomline|lines|single|shadowbox 中的任意一个(默认为none, 即没有边框).

Escaping to LaTeX

这个选项能让 listings 里的部分代码被 LaTeX 解析而不是原封不动地显示出来. 这个设置对我来说主要有两个用处, 一个是在注释里写上公式, 另一个是它能让 listings 中的中文能正确地排版.

texcl, 设置为 true 后能让代码中的注释按照设置的注释格式显示, 并被 LaTeX 解析后显示. 设置它之后就能在代码里正确显示中文了.

escapechar, 设置了代码中, 被哪个字符包围的部分由 LaTeX 解析后显示在文档里. 比如: escapechar=\% 能让被"%"包围的代码 escape.

escapeinside, 设置两个字符(可以是不同的字符), 被它们包围的字符会 escape, 如 escapeinside=''

为了避免出现错误, 在这个转义(escaping)的区域中, 不要使用任何 listings 的命令, 所有的环境(environment)都必须闭合, $符号必须成对出现.

Floating

这个选项能让 listing 成为浮动对象. 它的值可以是 tbph 的排列组合, 具体含义见The not so Short Introduction to LaTeX( | ) 2.12 Floating Bodies 章节. 它可以避免代码块被其他文字打断.

Labels and Captions

使用 label 可以设置标签供文档的其他部分引用, 使用 caption 可以设置 listing 的标题, 这个可以像前面的例子中那样设置. 同时, 你也可以注意到另一种设置 listings 配置的方法.

lstinputlisting, 最后的命令 lstinputlisting 这个命令在排版实验报告和作业文档时特别有用. 它可以将硬盘上的一个文件作为输入, 导入文档中. 这样, 当你修改了程序后, 只需重新编译 tex 文件即可更新文档. 享受过这项的功能的方便后, 我每次看到有人在写大作业报告时, 因为对代码做了细小改动而不得不重新排版报告时, 我都会不由自主地会心一笑.