LaTeX/Packages/Listings

From Wikibooks, the open-content textbooks collection

Using the package listings you can add non-formatted text as you would do with \begin{verbatim} but its main aim is to include the source code of any programming language within your document. It supports highlighting of all the most common languages and it is highly customizable. If you just want to write code within your document the package provides the lstlisting environment:

\begin{lstlisting}
put your code here
\end{lstlisting}

Another possibility, that is very useful if you created a program on several files and you are still editing it, is to import the code from the source itself. This way, if you modify the source, you just have to recompile the LaTeX code and your document will be updated. The command is:

\lstinputlisting{source_filename.py}

in the example there is a Python source, but it doesn't matter: you can include any file but you have to write the full file name. It will be considered plain text and it will be highlighted according to your settings, that means it doesn't recognize the programming language by itself.

It supports the following programming languages:

ABAP	IDL	Plasm
ACSL	inform	POV
Ada	Java	Prolog
Algol	JVMIS	Promela
Ant	ksh	Python
Assembler	Lisp	R
Awk	Logo	Reduce
bash	make	Rexx
Basic	Mathematica1	RSL
C	Matlab	Ruby
C++	Mercury	S
Caml	MetaPost	SAS
Clean	Miranda	Scilab
Cobol	Mizar	sh
Comal	ML	SHELXL
csh	Modula-2	Simula
Delphi	MuPAD	SQL
Eiffel	NASTRAN	tcl
Elan	Oberon-2	TeX
erlang	OCL	VBScript
Euphoria	Octave	Verilog
Fortran	Oz	VHDL
GCL	Pascal	VRML
Gnuplot	Perl	XML
Haskell	PHP	XSLT
HTML	PL/I

For some of them, several dialects are supported. For more information, refer to the documentation that comes with the package, it should be within your distribution under the name listings-*.dvi.

Notes 1 - It supports Mathematica code only if you are typing in plain text format. You can't include *.NB files \lstinputlisting{...} as you could with any other programming language, but Mathematica can export in a pretty-formatted LaTeX source.

you can modify several parameters that will affect how the code is shown. You can put the following code anywhere in the document (it doesn't matter whether before or after \begin{document}), change it according to your needs. The meaning is explained next to any line.

\lstset{ %
language=Octave,                % choose the language of the code
basicstyle=\footnotesize,       % the size of the fonts that are used for the code
numbers=left,                   % where to put the line-numbers
numberstyle=\footnotesize,      % the size of the fonts that are used for the line-numbers
stepnumber=2,                   % the step between two line-numbers. If it's 1 each line will be numbered
numbersep=5pt,                  % how far the line-numbers are from the code
backgroundcolor=\color{white},  % choose the background color. You must add \usepackage{color}
showspaces=false,               % show spaces adding particular underscores
showstringspaces=false,         % underline spaces within strings
showtabs=false,                 % show tabs within strings adding particular underscores
frame=single,                   % adds a frame around the code
tabsize=2,                      % sets default tabsize to 2 spaces
captionpos=b,                   % sets the caption-position to bottom
breaklines=true,                % sets automatic line breaking
breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
escapeinside={\%*}{*)}          % if you want to add a comment within your code
}

The last line needs an explanation. You need it if you want to add some text within the code that will not be printed. Note that, by default, comments of the language you are inserting will be printed; the command escapeinside={A}{B} will define comments for listings only. All the code between the string "A" and "B" will be ignored. In the example above, the comments for Octave start with %, and they are going to be printed in the document unless they start with %*, but you have to remember to "close" the comment with another "*".

If you add the above paragraph, the following can be used to alter the settings within the code:

\lstset{language=C,caption=Descriptive Caption Text,label=DescriptiveLabel}

A lot more detailed information can be found in a PDF by Carsten Heinz.

Details and documentation about the Listings package can be found at its CTAN website.