15

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.

6
  • Note to moderators: could someone make this question CW? – mbork Oct 24 '14 at 20:48
  • 1
    Dear downvoter: what's wrong with this question? – mbork Oct 24 '14 at 22:03
  • 3
    I do not understand downvoting this question. It is much more interesting for me than tex.stackexchange.com/questions/71172/…. – Przemysław Scherwentke Oct 24 '14 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). – Claudio Fiandrino Oct 25 '14 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... – cgnieder Oct 26 '14 at 12:22
5

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}

enter image description here

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}

enter image description here

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{
  add-cmds = lipsum
}
\begin{document}

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

\end{document}

enter image description here

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

% arara: pdflatex: { shell: on }
\documentclass{article}
\usepackage[example]{cnltx}
\setcnltx{
  add-cmds = lipsum
}
\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}

enter image description here

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.

0

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}

screenshot

  • 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)

Considered Options

See also

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.

showexpl

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)

ydoc-expl

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.