# Comparison of LaTeX example typesetting packages?

I am writing a (longer) text on LaTeX usage, and I want to typeset some LaTeX source code together with its results – and I'm not sure how to achieve it.

I am aware of this question, however, it only lists several alternatives. What I am interested in is more like a comparison. What I'm especially interested in are the following features (of lack thereof):

1. Possibility of syntax highlighting.

2. Dependence on external tools (Perl/Python scripts, for instance), and/or on \write18.

3. Possibility/ease of customizing the layout.

4. Possibility to typeset snippets of code and/or full documents (with \documentclass etc.).

5. Speed (I will have quite a few snippets of LaTeX code, maybe even more than a hundred, and I'm usually working on a slow netbook). I assume that the only way to achieve what I want is by means of writing to external files, which is slow; OTOH, I'm pretty sure LuaTeX could be used without these files – but LuaTeX is not very fast, either...)

6. Dependence on a specific TeX engine (LuaTeX, for instance).

No feature (or lack of a feature) is a deal-breaker for me (maybe except the possibility of customizing the layout - horizontal or vertical alignment of the code and result, so, for example, sverb is not my favorite choice), so even if a package does not have specific features, you're welcome to include it.

For completeness, ConTeXt solutions are also welcome.

I'd suggest one package per answer.

• Note to moderators: could someone make this question CW? Oct 24, 2014 at 20:48
• Dear downvoter: what's wrong with this question? Oct 24, 2014 at 22:03
• I do not understand downvoting this question. It is much more interesting for me than tex.stackexchange.com/questions/71172/…. Oct 24, 2014 at 23:40
• Recently, at GuIT Meeting there has been an article which compares different packages to list and highlight UNICODE source code (Typesetting and highlighting Unicode source code with LaTeX: a package comparison). Oct 25, 2014 at 7:16
• I have a package which I use for my package manuals with which LaTeX source examples can be set in various ways (code only, code and example, ...). It is able to handle code snippets as well as complete documents (which can be compiled on the go). It has a few quirks still which is why I'm hesitating to post an answer – but if you're interested... Oct 26, 2014 at 12:22

In the manuals of my packages I use a custom package for code and examples which uses a combination of listings and mdframed for displaying the code. I haven't really intended to make it public (which is why it has a lot of quirks which should be addressed some time...) but it is available on CTAN. However: usage at your own risk!

\documentclass{article}
\usepackage[example]{cnltx}
\begin{document}

\begin{example}
This is a piece of \LaTeX\ code.
\end{example}

\begin{example}[code-only]
This is a piece of \LaTeX\ code.
\end{example}

\begin{example}[side-by-side]
This is a piece of \LaTeX\ code.
\end{example}

\begin{example}[side-by-side,code-left=false]
This is a piece of \LaTeX\ code.
\end{example}

\end{document}


This uses a custom listings style per default called cnltx. But this can be customized. The following example overwrites the style cnltx. There are also options to modify it instead of redefining it. The default style knows that the language is TeX or LaTeX and also knows a lot of (La)TeX macro names and environment names. It's layout depends on a color-scheme which can be changed. This means it is also possible to use the cnltx style with different colors

\documentclass{article}
\usepackage[example]{cnltx}
\lstdefinestyle{mystyle}{
language   = [AlLaTeX]TeX,
basicstyle = {\ttfamily\small},
columns    = fullflexible ,
texcsstyle = \color{blue},
}
\setcnltx{
listings-options = {style=mystyle} ,
frame-options = ,
code-sep = \dotfill
}
\begin{document}

\begin{example}
This is a piece of \LaTeX\ code.
\end{example}

\begin{example}[code-only]
This is a piece of \LaTeX\ code.
\end{example}

\begin{example}[side-by-side]
This is a piece of \LaTeX\ code.
\end{example}

\begin{example}[side-by-side,code-left=false]
This is a piece of \LaTeX\ code.
\end{example}

\end{document}


It is also possible to display complete documents. This means that shell-escape must be enabled – at least for one run in order to produce the PDF that then is included.

% arara: pdflatex: { shell: on }
\documentclass{article}
\usepackage[example]{cnltx}
\setcnltx{
}
\begin{document}

\begin{example}[compile]
\documentclass{article}
\usepackage{lipsum}
\begin{document}
\lipsum
\end{document}
\end{example}

\end{document}


Again, there are a number of options to influence the behavior.

% arara: pdflatex: { shell: on }
\documentclass{article}
\usepackage[example]{cnltx}
\setcnltx{
}
\begin{document}

\begin{example}[compile,program=lualatex,runs=1,pages=1,
graphics={trim={5cm 18cm 5cm 7cm},clip}]
\documentclass{article}
\usepackage{lipsum}
\begin{document}
\lipsum
\end{document}
\end{example}

\end{document}


The package has quite a number of further features like macros \cs{cs name}, \env{env name}, ... (those macros use the same color-scheme as the cnltx listings style), it supports indexing of macro and environment names and so on.

After going through nearly all available packages, I wrote my own macro. It uses listings inside tcolorbox to highlight the soruce code:

\documentclass{article}
\usepackage{currfile}
\usepackage{tcolorbox}
\tcbuselibrary{listings}
\begin{document}
\newcount\LTGbeginlineexample
\newcount\LTGendlineexample
\newenvironment{ltgexample}%
{\LTGbeginlineexample=\numexpr\inputlineno+1\relax}%
{%
\LTGendlineexample=\numexpr\inputlineno-1\relax%

\tcbinputlisting{%
listing only,
listing file=\currfilepath,
colback=green!5!white,
colframe=green!25,
coltitle=black!90,
coltext=black!90,
left=8mm,
title=Corresponding \LaTeX{} code of \texttt{\currfilepath},
listing options={%
language={[LaTeX]TeX},
firstline=\the\LTGbeginlineexample,
lastline=\the\LTGendlineexample,
firstnumber=\the\LTGbeginlineexample,
basewidth=.5em,
aboveskip=0mm,
belowskip=0mm,
numbers=left,
xleftmargin=0mm,
numberstyle=\tiny,
numbersep=8pt%
}
}
}%

\begin{ltgexample}
This text demonstrates \LaTeX.
\end{ltgexample}

\end{document}


• Possibility of syntax highlighting: yes
• Dependence on external tools (Perl/Python scripts, for instance), and/or on \write18.: none
• Possibility/ease of customizing the layout: fully customizable (depends on your personal LaTeX skills)
• Possibility to typeset snippets of code and/or full documents (with \documentclass etc.): Snippets only
• Speed (I will have quite a few snippets of LaTeX code, maybe even more than a hundred, and I'm usually working on a slow netbook). I assume that the only way to achieve what I want is by means of writing to external files, which is slow; OTOH, I'm pretty sure LuaTeX could be used without these files – but LuaTeX is not very fast, either...): Very fast as only listings package is used
• Dependence on a specific TeX engine (LuaTeX, for instance): no

Here my full notes comparing the solution to others. Maybe this is helpful in case you want to rely on an existing package instead of using 36 lines of LaTeX code inside your document. (I am thinking of creating a package based on my findings).

# Use custom LaTeX environment for example presentation

## Context and Problem Statement

We want to present LaTeX examples. They should be shown both as LaTeX source and as rendered output.

## Decision Drives

• Write once - have two outputs (source and rendered)
• Good interaction with all pacakges
• Should support floats
• Should support compilation without special configuration (such as --shell-escape)

## Decision Outcome

Chosen option: "custom solution", because resolves all forces.

### Positive Consequences

• Works with floats and umlauts

### Negative Consequences

• A little bit more than minimal code is presented to the user

## Pros and Cons of the Options

### cnltx-example

Hint: Bold typewriter keywords can be generated by the LuxiMono package (hint by listings package).

### examplep

• Good, because allows for minipages automatically set to correctly render the LaTeX source.
• Bad, because it is GPL-licensed and thus requires all tex files to be GPL-licensed, too.
• Bad, because it does not fully support floating environments. See examplep#1 for details.

### tcolorbox, latexdemo, tkzexample, fancyvrb-ex

• Good, because nice boxes
• Bad, because all of them do not support floating environments

### sverb

• Bad, because it does not support floating environments

### lstdoc

• Bad, because works only within listings documentation properly (otherwise, it causes issues)

### gincltex

Includes .tex as graphics.

• Bad, because rendering as source and rendered output has to be done "on top".

### minted

The source code contains the example environment (taken from http://blog.karssen.org/2009/11/15/a-latex-example-environment/): https://github.com/gpoore/minted/blob/5d72859d714a6f2f6a42eec524476994d954b960/source/minted.dtx#L134.

• Bad, because does not deal with protection.

### Self-made with standalone package

• Good, because complete documents can be typeset
• Bad, because -write-18 will be required