# Typeset listings with preamble (Preferable using the listings package)

At the moment I use the listings package to typeset my listing. The listings are floats, use line numbers and have a top and bottom rule in order to be set apart from the surrounding text.

What I really would like to have is a short preamble to each listing that is separated by a (lighter) rule and contains annotations to the listing, like assertion, side effects, requirements, etc. So what I need is a heavier top rule, a light mid rule and a heavier bottom rule like known from the booktabs package. Moreover the lines of the preamble should not be counted, because the preamble is actually not part of the listing.

How do I achieve this in LaTeX most easily? Preferable I would like to use the listings package.

• Are your listings numbered? Could you give a small MWE with a floating listing as you have it now? – Thomas F. Sturm Dec 11 '14 at 16:46

The following example constructs floating listings using the tcolorbox package without numbering the listings . The environment preamblelisting takes the preamble as mandatory parameter. The optional parameter is any tcolorbox option. The underlying package for typesetting is listings.

Note: You may have to update the tcolorbox package to compile.

\documentclass{report}
\usepackage[skins,listings]{tcolorbox}
\usepackage{lipsum}

\newtcblisting{preamblelisting}[2][]{%
float=htb,empty,
boxsep=0pt,left=0pt,right=0pt,boxrule=2pt,leftrule=0pt,rightrule=0pt,
borderline horizontal={2pt}{0pt}{black},
segmentation engine=path,
segmentation style={solid,line width=1pt},
comment and listing,
fontupper=\itshape,
listing options={% put any listing options here
language={[LaTeX]TeX},
aboveskip=0pt, belowskip=0pt,numbers=left,numberstyle=\tiny,
basicstyle=\ttfamily,columns=fullflexible},
comment={#2},#1
}

\begin{document}

\lipsum[1]

\begin{preamblelisting}{This is the preamble. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Ut purus elit, vestibulum ut, placerat ac,
adipiscing vitae, felis. Curabitur dictum gravida
mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, magna.}
\begin{test}{Example}
This is an example
\end{test}
\end{preamblelisting}

\begin{preamblelisting}[float=b]{This is the preamble. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Ut purus elit, vestibulum ut, placerat ac,
adipiscing vitae, felis. Curabitur dictum gravida
mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, magna.}
\begin{test}{Example}
This is an example
This is an example
This is an example
\end{test}
\end{preamblelisting}

\lipsum

\end{document}


UPDATE:

This update considers the comments of the OP and adds numbering with titles set below. Also, this blends into normal listings from the listings package, i.e. both can be used in parallel. Finally, cleveref is used:

\documentclass{report}
\usepackage{cleveref,varwidth}
\usepackage[skins,listings]{tcolorbox}
\usepackage{lipsum}

\Crefname{lstlisting}{Listing}{Listings}

\AtBeginDocument{%
\newtcblisting[blend into=listings]{preamblelisting}[3][]{%
float=htb,empty,
boxsep=0pt,left=0pt,right=0pt,boxrule=2pt,leftrule=0pt,rightrule=0pt,
borderline horizontal={2pt}{0pt}{black},
segmentation engine=path,
segmentation style={solid,line width=1pt},
comment and listing,
fontupper=\itshape,
listing options={% put any listing options here
language={[LaTeX]TeX},
aboveskip=0pt, belowskip=0pt,numbers=left,numberstyle=\tiny,
basicstyle=\ttfamily,columns=fullflexible},
attach boxed title to bottom center,
varwidth boxed title,
coltitle=black,
boxed title style={blanker,top=2mm},
title={#2},comment={#3},#1
}}

\begin{document}

\lstlistoflistings

\chapter{Example}

\begin{lstlisting}[language={[LaTeX]TeX},
numbers=left,numberstyle=\tiny,
basicstyle=\ttfamily,columns=fullflexible,
caption={My normal listing},
captionpos=b,
label=mynormal]
This is a normal listing
\end{lstlisting}

\lipsum[2]

\textcolor{red}{\Cref{mynormal} is a normal listing and \Cref{mypreamble} is a listing
with a preamble.}

\begin{preamblelisting}[label=mypreamble]{My preamble listing}%
{This is the preamble. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Ut purus elit, vestibulum ut, placerat ac,
adipiscing vitae, felis. Curabitur dictum gravida
mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, magna.}
\begin{test}{Example}
This is an example
\end{test}
\end{preamblelisting}

\begin{preamblelisting}[float=b,label=floatingpreamble]{My floating preamble listing}%
{This is the preamble. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Ut purus elit, vestibulum ut, placerat ac,
adipiscing vitae, felis. Curabitur dictum gravida
mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, magna.}
\begin{test}{Example}
This is an example
This is an example
This is an example
\end{test}
\end{preamblelisting}

\lipsum

\end{document}


• Although the answer seems perfectly correct and matches my question, I do not use it. The reason is that there are a lot of other side effects and requirements I did not mention in the question. Firstly, my listings are numbered and collected into a list of listings. I found the /tcb/new/blend into key, but did not get it to work. Secondly, I use the cleveref package and it is already set up for "normal" listings but \newtcblisting does not seem to honor it. – nagmat84 Dec 17 '14 at 13:03
• Thirdly, for all my other floating objects (figures, tables) the caption is set below and centered. The pattern is always "<Type of object> <counter> : <caption>", i.e. "Figure 1: Foo". By default, tcolorbox put the title into the top. All in all, it seemed to me a lot of remaining work to go, so I decided omit any preamble of my listings and hope the reader will figure out the missing information by himself. – nagmat84 Dec 17 '14 at 13:06
• @nagmat84 I've updated my answer with additional code which considers your requirements. You should use tcolorbox with version 3.32 (2014/12/01) or newer (3.34 is the newest), because there was a cleveref-related bug before. – Thomas F. Sturm Dec 17 '14 at 19:01