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

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?

-
I think it has been asked by others. See this solution: tex.stackexchange.com/questions/4095/… –  xport May 28 '11 at 16:50
@xport: that's a question about just showing the source-code. Mine is somewhat more precise in that it requires side-by-side displaying of LaTeX code, and Seamus' answer happens to suggest the same tool as the answer you've linked to. –  Niel de Beaudrap May 28 '11 at 17:01
@xport: That question is not a duplicate, but I see that your answer is relevant here. However, DTX files must be handled different here because of there special handling of %. These must first be removed from the start of the code lines, but remaining ones must be handled as comments again when processing the output... –  Martin Scharrer May 28 '11 at 17:05

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

-
I was going to answer recommending the same package; while I was designing a little example you beat me! –  Gonzalo Medina May 28 '11 at 16:29
I tried to use showexpl quite a while ago for my DTX files and it had issues with the special handling of % in these files. I can't remember the exact details now, but I gave up on it and coded something by myself as part of my ydoc class (which is still an unstable alpha version). –  Martin Scharrer May 28 '11 at 16:55
@Martin I've only ever used it in normal .tex files, not in .dtx files, and I've not encountered any (serious) problems. If you could add an answer about ydoc I'm sure people would be interested in it. –  Seamus May 28 '11 at 17:01
@Gonzalo For these "low-hanging fruit" questions you need to be quick on the draw... Heh. You beat me to the sections/chapter headings one, so I guess we're even... –  Seamus May 28 '11 at 17:02
@Seamus: The issue is that ydoc is not really finished yet and has almost no documentation. I didn't do much on that part of the code for over a year and have issues recalling its current state. ;-) –  Martin Scharrer May 28 '11 at 17:03

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}


-
I shall have to check it out. Nice eye-candy! –  Niel de Beaudrap Jun 5 '11 at 15:41
Thanks!. I will put on my site the new version this week and a beta version of the documentation. The version on ctan will arrive in several days because I uploaded a lot of stuff. –  Alain Matthes Jun 5 '11 at 17:22
@Niel The announcement is not done yet but the new version in on CTAN. The collection tkz is also on CTAN and on TeXLive 2011. TL 2010 is now frozen so you need to install the package by hand Otherwise you'll wait for the TL2011 ( the beginning of July) –  Alain Matthes Jun 7 '11 at 15:20

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
%
%   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}
%
% \begin{macro}{\mymacro}
%    \begin{macrocode}
\def\mymacro{%
}
%    \end{macrocode}
% \end{macro}
%
% \Finale
%</package>


-

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}
\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}
\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}
\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}
\end{tikzpicture}
\end{exampleB}

\end{document}


-
And Martin may explain ydoc himself.
In my own document, I also wrote some macros using verbatim package for myself. (I didn't know these packages that time.) It seems the function is implemented time and time again. –  Leo Liu May 28 '11 at 17:13
@Martin: At least lstdoc.sty works fine in DTX files. It is used in listings.dtx. However, it is not well documented. –  Leo Liu May 28 '11 at 17:18
It seems OK to use fvrb-ex (used in fvrb-ex.dtx) and sverb (used in sverb.dtx`) in DTX files too. –  Leo Liu May 28 '11 at 17:38