LaTeX/Packages/Listings

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. If you wish to include pseudocode or algorithms, you may find LaTeX/Algorithms_and_Pseudocode useful also. ... To use the package, you need:

\usepackage{listings}

The listings package 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. You can specify the language while including the file with the following command:

\lstinputlisting[language=Python]{source_filename.py}

It supports the following programming languages:

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

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.

2 - Specification of the dialect is mandatory for these languages (e.g. language={[x86masm]Assembler})

3 - Modelica is supported via the dtsyntax package available here.

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.

\usepackage{listings}
\usepackage{color}
 
\definecolor{dkgreen}{rgb}{0,0.6,0}
\definecolor{gray}{rgb}{0.5,0.5,0.5}
\definecolor{mauve}{rgb}{0.58,0,0.82}
 
\lstset{ %
  language=Octave,                % 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=\tiny\color{gray},  % the style that is 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
  rulecolor=\color{black},        % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. commens (green here))
  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
  title=\lstname,                   % show the filename of files included with \lstinputlisting;
                                  % also try caption instead of title
  keywordstyle=\color{blue},          % keyword style
  commentstyle=\color{dkgreen},       % comment style
  stringstyle=\color{mauve},         % string literal style
  escapeinside={\%*}{*)},            % if you want to add a comment within your code
  morekeywords={*,...}               % if you want to add more keywords to the set
}

The escapeinside 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 and Brooks Moses.

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