Side-by-side source and output when documenting a style file

Question

When documenting a style file, it would be nice to be able to easily put side by side different examples of code, side-by-side with the output they produce.

What recommendations to people have to do this efficiently, and æsthetically?

Answer 1

My package tcolorbox provides another possible answer for the question. It allows to place the source code before or after the output. With version 2.20, source and output can be set side-by-side. The output can be placed inside a colored box or outside, before the source or after the source.

\documentclass{article}

\usepackage[skins,listings]{tcolorbox}

\newtcblisting{exampleA}[2][]{%
  colframe=red!50!yellow!50!black,
  colback=red!50!yellow!5!white,
  coltitle=red!50!yellow!3!white,
  bicolor,colbacklower=white,
  fonttitle=\sffamily\bfseries,
  sidebyside,
  title=#2,#1}

\newtcblisting{exampleB}[2][]{%
  colframe=red!50!yellow!50!black,
  colback=white,
  coltitle=red!50!yellow!3!white,
  bicolor,colbacklower=red!50!yellow!5!white,
  fonttitle=\sffamily\bfseries,
  sidebyside,text and listing,
  title=#2,#1}

\begin{document}

\begin{exampleA}[righthand width=3.5cm,center lower]{Side-by-side (inside box)}
\begin{tikzpicture}
\path[fill=yellow!50!white] (0,0) circle (11mm);
\path[fill=white] (0,0) circle (9mm);
\foreach \w/\c in {90/red,210/green,330/blue}
{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
\end{tikzpicture}
\end{exampleA}

\begin{exampleA}[righthand width=3.5cm,listing outside text]{Side-by-side (outside box)}
\begin{tikzpicture}
\path[fill=yellow!50!white] (0,0) circle (11mm);
\path[fill=white] (0,0) circle (9mm);
\foreach \w/\c in {90/red,210/green,330/blue}
{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
\end{tikzpicture}
\end{exampleA}

\begin{exampleB}[lefthand width=3.5cm]{}
\begin{tikzpicture}
\path[fill=yellow!50!white] (0,0) circle (11mm);
\path[fill=white] (0,0) circle (9mm);
\foreach \w/\c in {90/red,210/green,330/blue}
{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
\end{tikzpicture}
\end{exampleB}

\begin{exampleB}[lefthand width=3.5cm,text outside listing,
  colback=red!50!yellow!5!white,top=0mm,bottom=0mm,left=0mm,right=0mm,
  arc=0mm,boxrule=1pt,watermark text=Source,
  watermark color=yellow!75!red!30!white]{}
\begin{tikzpicture}
\path[fill=yellow!50!white] (0,0) circle (11mm);
\path[fill=white] (0,0) circle (9mm);
\foreach \w/\c in {90/red,210/green,330/blue}
{\path[shading=ball,ball color=\c] (\w:1cm) circle (7mm);}
\end{tikzpicture}
\end{exampleB}

\end{document}

Answer 2

I made a package tkzexample that I use for all my documentation. I upload yesterday on ctan a new version (you need to wait several days before see it) but without documentation actually ( I have a little work to do to finish the doc. The main macro is based on the \codeexampleof T. Tantau. Till gave me permission to use and modify the macro. \codeexample don't work with accents and utf8 but tkzexample accepts accents and utf8. I add the possibility to num the lines and I created an option to save the example on an extern file with \usepackage[saved]{tkzexample}.

\documentclass[]{scrartcl}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}   
\usepackage[usenames,dvipsnames]{xcolor}
\usepackage{tikz}
\usepackage{amsmath,amssymb,booktabs}
\usepackage[frenchb]{babel}
\usepackage{tkzexample} 
% possible \usepackage[saved]{tkzexample} permet de sauvegarder l'exemple
\usepackage[protrusion = true,
            expansion, final,
            verbose = false, babel   = true]{microtype}
\DisableLigatures{encoding = T1, family = tt*}  

\parindent=0pt

\begin{document}

\colorlet{graphicbackground}{blue!10!white}%
\colorlet{codebackground}{red!10}%  
1) How to use

 \begin{tkzltxexample}[]
\documentclass{scrartcl}
\usepackage{tkzexample}
\begin{document}     
\begin{tkzexample}[]
\begin{tikzpicture}
    \path coordinate (A) at (0,0)
          coordinate (B) at (-60:12cm)
          coordinate (C) at (240:12cm);
\foreach \density in {20,30,...,160}{%
    \draw[fill=MidnightBlue!\density] (A)--(B)--(C)--cycle;
    \path (A) coordinate (X) -- (B) coordinate[pos=.15](A)
          -- (C) coordinate[pos=.15](B) -- (X) coordinate[pos=.15](C);}
\end{tikzpicture}  
\end{tkzexample}
\end{document}  
\end{tkzltxexample} 

2) Usage classique

\begin{tkzexample}[latex=6cm]
\begin{tikzpicture}[scale=.5]
    \path coordinate (A) at (0,0)
          coordinate (B) at (-60:12cm)
          coordinate (C) at (240:12cm);
    \foreach \density in {20,30,...,160}{%
        \draw[fill=MidnightBlue!\density] 
             (A)--(B)--(C)--cycle;
        \path (A) coordinate (X)
           -- (B) coordinate[pos=.15](A)
           -- (C) coordinate[pos=.15](B)
           -- (X) coordinate[pos=.15](C);
    }
\end{tikzpicture}  
\end{tkzexample}
3) Un tableau
\begin{tkzexample}[width=6cm,frame tex=Maroon,frame code=Maroon,num ]
\begin{tabular}{ll}
\toprule  
Essai avec un tabeau  &\\
\midrule
Un premier &   texte\\
Un second & texte\\
\bottomrule
\end{tabular}
\end{tkzexample} 

4) Les accents en français
\begin{tkzexample}[small,num]
\begin{tikzpicture}
    \node[draw] {éè§çà};
\end{tikzpicture}
\end{tkzexample} 
\end{document} 

Answer 3

There's showexpl which has the LTXexample environment for exactly this purpose. It's based on listings

Answer 4

For normal documents the showexpl package would be the way to go, as Seamus already stated in his answer. However, special care must be taken for DTX files because of the special handling of % in them.

I wrote some own code for the my ydoc bundle. The ydoc-expl package of this bundle provides an example float where the actual code is wrapped into examplecode. You can add a caption and also display a list of examples. It uses listings and float for this. You can use \lstset{...} to modify its display. Its sets the compiled output on the left or top and the code on the right or bottom depending on the amount of horizontal space both require.

Note that ydoc is still an alpha version and under development. Things might change in future revisions and there a still a few bugs in it.

You can use the ydoc class instead of ltxdoc or just load the ydoc-expl package.

% \iffalse meta-comment
%
% Copyright (C) 2009 by Martin Scharrer <martin@scharrer-online.de>
% -----------------------------------------------------------------
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%
%   http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Martin Scharrer.
%
% This work consists of the files j.dtx, j.ins
% and the derived file j.sty.
%
% \fi
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{ydoc-expl}
%\documentclass{ydoc}

\usepackage{tikz}

\EnableCrossrefs
%\CodelineIndex
\RecordChanges
%\OnlyDescription
\begin{document}
  \DocInput{\jobname.dtx}
  \PrintChanges
  %\newpage\PrintIndex
\end{document}
%</driver>
% \fi
%
% {Titlepage ..}
% \listof{example}{List of Examples}
%
% \section{Usage}
% \begin{example}
%    \begin{examplecode}
%       \begin{tikzpicture}
%           \draw (2.5,2.5) circle (2cm);
%           \draw (0,0) -- (5,5);
%       \end{tikzpicture}
%    \end{examplecode}
%    \caption{Some example}
% \end{example}
%
% \StopEventually{}
% \iffalse
%<*package>
% \fi
%
% \section{Implementation}
% \subsection{Package Header}
%
% \begin{macro}{\mymacro}
%    \begin{macrocode}
\def\mymacro{%
}
%    \end{macrocode}
% \end{macro}
%
% \Finale
%</package>

Answer 5

There are several packages for this purpose:

• fvrb-ex, based on fancyvrb, contributed with fancyvrb together.
• lstdoc, part of listings package, used by document of listings itself.
• examplep, based on listings.
• showexpl, based on listings.
• sverb, provides demo environment.

And Martin may explain ydoc himself.

Answer 6

For documenting my own packages I wrote a custom class cnltx-doc which comes bundled with a package called cnltx-example:

\usepackage{cnltx-example}

or

\usepackage[example]{cnltx}

It provides an environment {example} which can display code and output side by side (for which there's also the {sidebyside} environment)) or above each other or only the code (for which there's also the {sourcecode} environment).

It allows for compiling the example as separate document if needed (with the engine of choice) – this needs shell-escape enabled at least for the first compilation, of course.

The package comes with predefined styles for LaTeX, BibTeX and makeindex listings. Output (colors, frames…) can be customized.

Behind the scenes the listings package is used.

\documentclass{article}

\usepackage{cnltx-example}
\setcnltx{
  add-cmds = {foo}
}

\begin{document}

\begin{example}
  This is a \LaTeX\ example.

  \newcommand*\foo{foo}

  Some inline math $x^2$ and some display math:
  \begin{equation}
    x^2 + y^2 = z^2
  \end{equation}
\end{example}

\begin{example}[side-by-side]
  This is a \LaTeX\ example.

  \newcommand*\foo{foo}

  Some inline math $x^2$ and some display math:
  \begin{equation}
    x^2 + y^2 = z^2
  \end{equation}
\end{example}

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

  \newcommand*\foo{foo}

  Some inline math $x^2$ and some display math:
  \begin{equation}
    x^2 + y^2 = z^2
  \end{equation}
\end{example}

\newpage

\begin{example}[compile,graphics={trim={2cm 22cm 2cm 2cm},clip}]
  \documentclass{article}
  \begin{document}

  This is a \LaTeX\ example.

  \newcommand*\foo{foo}

  Some inline math $x^2$ and some display math:
  \begin{equation}
    x^2 + y^2 = z^2
  \end{equation}

  \end{document}
\end{example}

\end{document}