LaTeX by example: code listings

A popular document markup system for technical and scientific documents is the LaTeX text processing system. LaTeX offers a variety of options and packages to write articles, books, and papers that include mathematics, diagrams, tables, and other special formatting.

The listings package, offered by default in most LaTeX installations, makes it easy to include source code into documents. 

The old way

By default, you can use \begin{verbatim} and \end{verbatim} to enclose any text that must be inserted in "plain text" style.

\documentclass{article}
\begin{document}

Here is a \textsc{c} program that prints the text
``Hello world'' back to the user:

\begin{verbatim}
#include 

int
main()
{
  puts("Hello world!");
  printf("Hello world!\n");
  return 0;
}
\end{verbatim}

\end{document}

This generates a rather plain version of the source text. It gets the job done, but it's not very nice to look at:

Listings with style

The verbatim block may be suitable if your document only includes a few lines of verbatim text. However, for scientific and engineering papers that must incorporate source code samples, such as to demonstrate a method to calculate results, check out the listings package.

With listings, LaTeX will format your code samples with special formatting to highlight keywords, strings, comments, and other components of the source code. listings provides distinct highlighting for different programming languages, such as C, FORTRAN, R, Matlab, Mathematica, and Python. 

Similar to using verbatim, you can include a source code listing using \begin{lstlisting} and \end{lstlisting}. Provide the programing language type as an extra parameter, such as this to include a Linux Bash shell:

\begin{lstlisting}[language=sh]
#!/bin/sh
echo 'Hello world!'
\end{lstlisting}

However, you may find it more convenient to load the source file into the document using \lstinputlisting with the filename as a parameter. For example, use this command to include a C program stored in hello.c:

\lstinputlisting[language=c]{hello.c}

LaTeX by example

The listings package allows options to control borders, line numbers, and other styling of code listings. To get started with listings in LaTeX, use this sample document as a guide. This demonstrates many of the most useful features of the listings package.

\documentclass{article}
\usepackage{listings}

\begin{document}

The old way of doing it:

\begin{verbatim}
This is verbatim text
\end{verbatim}

Basic usage, without styles:

\lstinputlisting{hello.sh}

Entered directly, with language specifier and left line:

\begin{lstlisting}[language=sh,frame=leftline]
#!/bin/sh
echo 'Hello world!'
\end{lstlisting}

As a program, with a caption, line numbers, and top line:

\lstinputlisting[language={[77]Fortran},caption={old-style \textsc{fortran77}},numbers=right,numberstyle=\tiny,frame=topline]{hello.f}

Or this program, with a title, line numbers, and frame:

\lstinputlisting[language=C,title=\textsf{C programming},numbers=left,numberstyle=\tiny,frame=single]{hello.c}

As a web page fragment, with line numbers:
\lstinputlisting[language=HTML,numbers=right,numberstyle=\tiny,firstnumber=7,firstline=7,lastline=8,frame=lines]{hello.html}

Typewriter style:
\lstinputlisting[basicstyle=\ttfamily,language=HTML,numbers=right,numberstyle=\tiny,firstnumber=7,firstline=7,lastline=8,frame=lines]{hello.html}

Sans serif style:
\lstinputlisting[basicstyle=\sffamily,language=HTML,numbers=right,numberstyle=\tiny,firstnumber=7,firstline=7,lastline=8,frame=lines]{hello.html}

\end{document}

The listings package should be included by default in most LaTeX installations, so you shouldn't need to do anything extra to use it. Process the sample document with LaTeX to see the results:

$ pdflatex code.tex

Learn more about the listings package by reading the manual. You can find a copy at your favorite CTAN mirror: listings-devel.pdf