Source code highlighting in LaTeX

Question

I need to highlight source code in LaTeX. The package listings seems to be the best choice for most use-cases and for me it was, until now.

However, now I need more flexibility. Generally, what I’m looking for is a real lexer. In particular, I need (for an own language definition) to define (and highlight!) own number styles. listings does not allow highlighting numbers in code. However, I need to produce something like this:

listings also cannot cope with arbitrary delimiters for strings. Consider the following valid Ruby code:

s = %q!this is a string.!

Here, ! can be replaced by almost any delimiter.

(That listings cannot handle Unicode is also quite vexing, but that’s another issue.)

Ideally, I am looking for an extension of listings that allows me to provide more complex lexing rules. But barring that, I am also searching for viable alternatives.

Other threads have suggested using Pygments which can produce LaTeX output. There’s even a package – texments – to ease the transition.

However, this sorely lacks features. In particular, I am interested in listings-style line numbering, source code line references, and the possibility of embedding LaTeX in source code (options texcl and mathescape in listings).

As an example, here’s a source code typeset with listings which shows some of the things that a replacement should also provide:

^{_{[“Sideways addition” modified from Bit Twiddling Hacks]}}

Solution 1

Taking Norman’s advice to heart, I’ve hacked together a solution that used (a patched) Pygments for highlighting and pushed in as many features as possible without bursting ;-)

I’ve also created a LateX package, once my Pygments patch was released in version 1.2 …

Presenting minted

minted is a package that uses Pygments to provide top-notch syntax highlighting in LaTeX. For example, it allows the following output.

Here’s a minimal file to reproduce the above code (notice that including Unicode characters might require XeTeX)!

\documentclass[a4paper]{article}
\usepackage{fontspec}
\usepackage{minted}

\setsansfont{Calibri}
\setmonofont{Consolas}

\begin{document}
\renewcommand{\theFancyVerbLine}{
  \sffamily\textcolor[rgb]{0.5,0.5,0.5}{\scriptsize\arabic{FancyVerbLine}}}

\begin{minted}[mathescape,
               linenos,
               numbersep=5pt,
               gobble=2,
               frame=lines,
               framesep=2mm]{csharp}
  string title = "This is a Unicode π in the sky"
  /*
  Defined as $\pi=\lim_{n\to\infty}\frac{P_n}{d}$ where $P$ is the perimeter
  of an $n$-sided regular polygon circumscribing a
  circle of diameter $d$.
  */
  const double pi = 3.1415926535
\end{minted}
\end{document}

This can be typeset using the following command:

xelatex -shell-escape test.tex

(But minted also works with latex and pdflatex …)

minted.sty works similar to texments.sty but allows additional features.

How to get it

• minted is listed on CTAN (package info)

• documentation is of course included.

• minted is now maintained by Geoffrey Poore. The development version, including the latest .sty file, is available at github.com/gpoore/minted, and can be cloned from there.

Once again, thanks to Norman for motivating me to produce this package.

Solution 2

TeX is (famously) Turing-complete, but I'm pretty sure you're going to have to write this extension yourself. The documentation makes it clear that the original author of listings orphaned it in 2004, and that it has not been updated since 2006. The package wasn't designed to override the formatting of numeric literals, but you might be able to modify it by changing the definition of \lst@ProcessDigit. If that doesn't work, you'll have to understand in detail how the "identifier style" options work, and you'll have to duplicate that machinery for your numeric literals.

I don't quite understand why you're so reluctant to introduce an external tool into your toolchain, but because you are, you'll have to do extra work. After a look at the source code, I expect that modifying listings should be possible, but I personally would choose to preprocess my LaTeX instead.

Solution 3

This is a package which converts source code to TeX and LaTeX with syntax highlighting. It is possible to add custom programming language definitions easily.

Highlight supports 100 programming languages and includes 50 colour themes. It features code reformatting and indenting.

I haven't used it to know how WELL it works, but someone else I know said it worked pretty well. If I get a chance to, I'll try it out myself and see.

Comments

[Mica]

if you're not reluctant to bring in external tools such as pygments, then why not just write a makefile for your document?

[Matthias]

Shouldn't this be migrated to tex.stackexchange.com ?^^

[Konrad Rudolph]

@Matthias Not sure. When I posted it there was no tex.se but now it seems quite useful here – the question has had a tremendous echo, while on TeX.SE nobody so far posted a similar question. Furthermore, it actually relates specifically to programming and programming tools so I guess programmers are the people who benefit from it.

[MohamedEzz]

For those who have can forget LaTeX for the document they're currently writing : Note that with Office Word, or LibreOffice Writer, you just copy/paste your code from e.g Eclipse to there and get your colors preserved !!

[Konrad Rudolph]

@MemoryLeaks I’m not sure who this advice is terribly useful: Office software is not a valid substitute for LaTeX (which is not an office software, it’s a desktop publishing system, which, in a nutshell, means that it provides much superior typography, apart from all its other advantages over office software).

[MohamedEzz]

@KonradRudolph , my comment is by no means a comparison of both, or intended for such a popular debate. I had an assignment to hand out containing python code, I spent a lot of time trying to do put it in LaTeX with color highlighting, after around 30 minutes of working on this, I tried to paste my code LibreOffice Writer and everything was perfect in 5 seconds. I see it very useful to save someone else's time in a similar situation to mine. Remember that this is a comment not an answer.

[Konrad Rudolph]

highlight shares all the problems of Pygments, though. In particular, it is not a LaTeX package, despite what its description says. It is simply a stand-alone program. The problem, just as with Pygments, is how to use it meaningfully from within LaTeX and provide all the nice things that listings has.

[Konrad Rudolph]

I’m not at all reluctant to introduce external tools – in fact, I think that using Pygments is probably the best solution. The question is how to do this in a smart way so that I can still have escapes to LaTeX and \labels inside the code.

[Konrad Rudolph]

As for changing listings, I have already had a look at its source – and unfortunately, I don’t understand it at all. My TeX skills are nowhere near that level. Until now, I’ve only ever used the LaTeX subset of TeX anyway.

[sykora]

After hours of searching on how to use pygments with LaTeX, and more hours of trying to hack together my own solution, this is the best I've found. Better yet, it actually works. Thanks for this.

[Filip Dupanović]

here just to appreciate the work you've done in a becoming manner ;)!

[Bahadır Yıldırım]

It took me ages to get everything set up, but it was worth it in the end. Installing it via MiKTeX didn't work (seamlessly) for me; I had to install several packages separately. Also Python's easy_install didn't grab a working Pygments EGG, so I downloaded it separately and installed it via easy_install.exe pygments*.egg. Finally, don't forget to run latex or pdflatex with the --shell-escape switch... and cross your fingers!

[Konrad Rudolph]

@Paul: It’s true that the whole thing is quite messy on Windows. :-( Hopefully, the next version of Pygments will alleviate this somewhat, but for people who don’t often work with Python (and hence easy_install) the process will never be very smooth.

[Paŭlo Ebermann]

On the TeX SE site there are now quite some questions about your package, and I just hit one with a kind of feature request (hidden in the comments). You might want to have a look.

[Konrad Rudolph]

@Paŭlo Thanks. I try to read all mentions of the package (I’ve got a Google alert) but I don’t always succeed. The question you mentioned I’ve actually read (apparently: I upvoted it but I can’t remember) but it’s not at all straightforward. “Ab”using TikZ for this seems like a bad hack …

[Namey]

I would say that the biggest issue with introducing an external tool is that if you're publishing. A lot of journal publishers (cough-cough SPRINGER, and others) require submission in raw LaTex, which is then compiled on their servers. Needless to say, if your 3rd-party tool is not on their server, you're SOL unless you pre-process (which defeats most of the utility of letting Tex drive).

[aphex]

Is it possible to define custom pygments template in latex with minted? I want to highlight a custom made dsl language.

[Konrad Rudolph]

@aphex Not inside LaTeX, you have to do it in Python as shown in the Pygments documentation.

[Ivan]

Any luck with trying to couple Kile's automatic pdflatex and this?

[DetlevCM]

If the documentation is correct, the listings package is still maintained - however the maintainer changed and it has received bugfixes: ctan.org/pkg/listings?lang=en

[Volker Stolz]

@Namey, just a data-point: I just managed to successfully sneak a paper using minted through Springer's LNCS publishing-process.

[thymaro]

Wait, what!? The first version of minted was made in less than two days from the original idea to the finished product? What kind of mad world is this?

[alper]

l.45 \msg_fatal:nn {fontspec} {cannot-use-pdftex}