LaTeX/Source Code Listings

There are many packages providing code listings and highlighting, below are most popular:


 * listings
 * very useful and functionality rich,
 * minted
 * minted is an alternative to listings which has become popular. It uses the external Python library Pygments for code highlighting, which as of February 2021 boasts over 537 supported languages and text formats. As the package relies on external Python code, the setup require a few more steps than a usual LaTeX package, so please have a look at their GitHub repo and their manual.

Using the listings package
Using the package you can add non-formatted text as you would do with  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 Algorithms and Pseudocode useful also.

To use the package, you need:

The 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 environment:

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:

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:

You can also specify a scope for the file.

Or

This comes in handy if you are sure that the file will not change (at least before the specified lines). You may also omit the  or  parameter: it means everything up to or starting from this point.

This is a basic example for some Pascal code:



Supported languages
It supports the following programming languages:

ABAP2,4, ACSL, Ada4, Algol4, Ant, Assembler2,4, Awk4, bash, Basic2,4, C#5, C++4, C4, Caml4, Clean, Cobol4, Comal, csh, Delphi, Eiffel, Elan, erlang, Euphoria, Fortran4, GCL, Go (golang), Gnuplot, Haskell, HTML, IDL4, inform, Java4, JVMIS, ksh, Lisp4, Logo, Lua2, make4, Mathematica1,4, Matlab, Mercury, MetaPost, Miranda, Mizar, ML, Modelica3, Modula-2, MuPAD, NASTRAN, Oberon-2, Objective C5, OCL4, Octave, Oz, Pascal4, Perl, PHP, PL/I, Plasm, POV, Prolog, Promela, Python, R, Reduce, Rexx, RSL, Ruby, S4, SAS, Scilab, sh, SHELXL, Simula4, SQL, tcl4, TeX4, VBScript, Verilog, VHDL4, VRML4, XML, 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  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. ).
 * 3) Modelica is supported via the dtsyntax package available here.
 * 4) For these languages, multiple dialects are supported. C, for example, has ANSI, Handel, Objective and Sharp. See p. 12 of the listings manual for an overview.
 * 5) Defined as a dialect of another language

Settings
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 ), change it according to your needs. The meaning is explained next to any line.

The line needs an explanation. The option will define delimiters for escaping into LaTeX code, i.e. all the code between the string "A" and "B" will be parsed as LaTeX over the current listings style. In the example above, the comments for Octave start with, and they are going to be printed in the document unless they start with , in which case they are read as LaTeX (with all LaTeX commands fulfilled) until they're closed with another. If you add the above paragraph, the following can be used to alter the settings within the code:
 * escapeinside

There are many more options, check the official documentation.

Style definition
The package lets you define styles, i.e. profiles specifying a set of settings.

Example

In our example, we only set two options globally: the default style and the escape character. Usage:

The C part will print as



Automating file inclusion
If you have a bunch of source files you want to include, you may find yourself doing the same thing over and over again. This is where macros show their real power.

In this example, we create one command to ease source code inclusion. We set the default style to be customc. All listings will have their name as caption: we do not have to write the file name twice thanks to the macro. Finally we list all listings with this command from the package.

See Macros for more details.

Encoding issue
By default, does not support multi-byte encoding for source code. The option only works for 8-bits encodings such as latin1.

To handle UTF-8, you should tell listings how to interpret the special characters by defining them like so

The above table will cover most characters in latin languages. For a more detailed explanation of the usage of the option check section 5.4 in the Listings Documentation.

Another possibility is to replace (in the preamble) with, but this will only work for.

Customizing captions
You can have fancy captions (or titles) for your listings using the package. Here is an example for.