listings 宏包札記

from: http://blog.linuxgem.org/lyanry/show/319.html

listings 是專用於代碼排版的 LaTeX 宏包，可對關鍵詞、註釋和字符串等使用不同的字體和顏色或顏色，也可以爲代碼添加邊框、背景等風格。

1 基本用法

下面給出一份用於排版 C 語言 HelloWorld 程序代碼的完整的 LaTeX 文檔：

\documentclass{article}
\usepackage{listings}

\begin{document}

\begin{lstlisting}[language=C]
int main(int argc, char ** argv)
{
/* print a string "Hello world!"
printf("Hello world!\n");

return 0;
}
\end{lstlisting}

\end{document}

排版效果如下圖所示：

2 對計算機語言的支持

listings 宏包支持大約近百種計算機語言，下面只列舉幾個常用的：

• C ：ANSI, Handel, Objective, Sharp
• C++ ：ANSI, GNU, ISO, Visual
• Delphi
• Java ：empty, AspectJ
• TeX ：AlLaTeX, common, LaTeX, plain, primitive
• XML
• Gnuplot
• HTML
• Python
• Ruby
• make ：empty, gnu

從上面的語言支持列表可看到有些語言是分爲了多種類型的，比如 C 語言分爲了 ANSI, Handel, Objective, Sharp 等類型。在使用 listings 宏包時，對某種語言存在多種類型的情況下，可以指定所需類型的，例如：

\begin{lstlisting}[language={[ANSI]C}]
int main(int argc, char ** argv)
{
/* print a string "Hello world!"
printf("Hello world!\n");

return 0;
}
\end{lstlisting}

3 語法高亮

listings 宏包提供了關鍵詞高亮與註釋高亮，分別體現爲 keywordstyle 與 commentstyle 參數。

下面將 C 語言關鍵詞使用淺藍色高亮顯示，代碼採用灰色顯示：

\documentclass{article}
\usepackage{listings}
\usepackage{xcolor} % 使用顏色宏包

\begin{document}

\begin{lstlisting}[language={[ANSI]C}, keywordstyle=\color{blue!70}, commentstyle=\color{red!50!green!50!blue!50}]
int main(int argc, char ** argv)
{
/* print a string "Hello world!" */
printf("Hello world!\n");

return 0;
}
\end{lstlisting}

\end{document}

注意，要使用 listings 宏包提供的語法高亮，需要 xcolor 宏包支持。

語法高亮的排版效果如下圖所示：

4 添加邊框

listings 宏包爲代碼邊框提供了很多風格，大體可分爲帶有陰影的邊框與圓角邊框。這裏僅僅給出一個陰影邊框的示例，至於其它邊框風格，可查閱 listings 宏包文檔，裏面給出了一些示例。

下面 LaTeX 源文檔將爲代碼添加陰影邊框，並將陰影設置爲淺灰色：

\begin{lstlisting}[language={[ANSI]C}, keywordstyle=\color{blue!70}, commentstyle=\color{red!50!green!50!blue!50}, frame=shadowbox, rulesepcolor=\color{red!20!green!20!blue!20}]
int main(int argc, char ** argv)
{
/* print a string "Hello world!" */
printf("Hello world!\n");

return 0;
}
\end{lstlisting}

排版效果如下圖：

5 添加行號

很多時候需要對文檔中的代碼進行解釋，只有帶有行號的代碼纔可以讓解釋更清晰，因爲你只需要說第 x 行代碼有什麼作用即可。如果沒有行號，那對讀者而言就太殘忍了，他們不得不從你的文字敘述中得知行號信息，然後去一行一行的查到相應代碼行。

listings 宏包通過參數 numbers 來設定行號，該參數的值有兩個，分別是 left 與 right，表示行號顯示在代碼的左側還是右側。下面爲帶有邊框的代碼添加行號，並設置行號字體爲 \tiny：

\begin{lstlisting}[language={[ANSI]C}, numbers=left, numberstyle=\tiny, keywordstyle=\color{blue!70}, commentstyle=\color{red!50!green!50!blue!50}, frame=shadowbox, rulesepcolor=\color{red!20!green!20!blue!20}]
int main(int argc, char ** argv)
{
/* print a string "Hello world!" */
printf("Hello world!\n");

return 0;
}
\end{lstlisting}

排版效果如下圖所示：

6 全局設置

上面所給的各個示例中，lstlisting 環境後面尾隨了很多參數，要是每使用一次 lstlisting 環境就要設置這麼多參數，那就沒什麼意思了。

可以使用 \lstset 命令在 LaTeX 源文檔的導言區設定好 lstlisting 環境所用的公共參數，如下：

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

\begin{document}

\lstset{numbers=left,
numberstyle=\tiny,
keywordstyle=\color{blue!70}, commentstyle=\color{red!50!green!50!blue!50},
frame=shadowbox,
rulesepcolor=\color{red!20!green!20!blue!20}
}

\begin{lstlisting}[language={[ANSI]C}]
int main(int argc, char ** argv)
{
/* print a string "Hello world!" */
printf("Hello world!\n");

return 0;
}
\end{lstlisting}

\end{document}

7 顯示中文

listings 宏包默認是不支持包含中文字串的代碼顯示的，但是可以使用 “逃逸” 字串來顯示中文。

在 \lstset 命令中設置逃逸字串的開始符號與終止符號，推薦使用的符號是左引號，即 “ `”

\lstset{numbers=left,
numberstyle=\tiny, keywordstyle=\color{blue!70}, commentstyle=\color{red!50!green!50!blue!50},
frame=shadowbox, rulesepcolor=\color{red!20!green!20!blue!20},
escapeinside=``}

……

\begin{lstlisting}[language={[ANSI]C}]
int main(int argc, char ** argv)
{
/* print a string "Hello world!" */
printf("`我愛中文`!\n");

return 0;
}
\end{lstlisting}

8 調整一下邊距

listings 的代碼框的寬度默認是與頁芯等寬的，其上邊距也過於小，可根據自己的審美觀念適度調整一下。我通常是將代碼框的左右邊距設置爲 2em，上邊距爲 1em，下邊距採用默認值即可，所作設定如下：

\lstset{numbers=left, numberstyle=\tiny, keywordstyle=\color{blue!70}, commentstyle=\color{red!50!green!50!blue!50}, frame=shadowbox, rulesepcolor=\color{red!20!green!20!blue!20},escapeinside=``, xleftmargin=2em,xrightmargin=2em, aboveskip=1em}