# How to add listings environment to DTX files

I am working on my first DTX file and want to add a code example, which shall be printed with listings. This works so far, but since the documentation is commented the listings code is using a full verbatim input and prints everything commented.

I assume that I have to play with externals files creation, but still the code must be commented to be part of the documentation. Since I am for sure not the first one to handle this problem I would like to know the common solutions.

-
Please have a look at this post: tex.stackexchange.com/questions/23892/…. You can write a standalone tex-file and then you can use a perl script. –  Marco Daniel Oct 9 '11 at 14:21
That's actally a common problem. I wrote my own code as part of my ydoc bundle for this kind of listings. Unfortunately, it is still in the alpha stage and not recommended to be used for other users packages. –  Martin Scharrer Oct 9 '11 at 14:32
@Marco: I have no idea which perl script shall do what for this problem. –  Matthias Pospiech Oct 9 '11 at 16:12
@MatthiasPospiech: For example: makedtx –  Marco Daniel Oct 9 '11 at 17:16
@Marco: I used sty2dtx. But I do not see what this has to do with the original problem of inserting verbatim material in a dtx file. –  Matthias Pospiech Oct 9 '11 at 17:59
show 1 more comment

Something like

% \iffalse
%<*example>
% \fi
\begin{lstlisting}
first line
second line
...
\end{lstlisting}
% \iffalse
%</example>
% \fi


should work, where example is an otherwise unused tag (it can be used for any such environment).

The \iffalse...\fi avoids that the tag is printed; the tag itself avoids that the uncommented code is included in the .sty file after docstrip processing.

-
It turns out that this code fails to generate a valid sty file. It though works for the pdf file. See tex.stackexchange.com/questions/35214/… for more information. –  Matthias Pospiech Nov 17 '11 at 21:10

I've detailed some of how I approach this in my blog. I use the listings package along with some code adapted from the listings documentation:

%\lst@RequireAspects{writefile}
%\newsavebox{\LaTeXdemo@box}
%\lstnewenvironment{LaTeXdemo}[1][code and example]{^^A
%  \global\let\lst@intname\@empty
%  \expandafter\let\expandafter\LaTeXdemo@end
%    \csname LaTeXdemo@#1@end\endcsname
%  \@nameuse{LaTeXdemo@#1}^^A
%}{^^A
%  \LaTeXdemo@end
%}
%\newcommand*\LaTeXdemo@new[3]{^^A
%  \expandafter\newcommand\expandafter*\expandafter
%    {\csname LaTeXdemo@#1\endcsname}{#2}^^A
%  \expandafter\newcommand\expandafter*\expandafter
%    {\csname LaTeXdemo@#1@end\endcsname}{#3}^^A
%}
%\newcommand*\LaTeXdemo@common{^^A
%  \setkeys{lst}{
%    basicstyle   = \small\ttfamily,
%    basewidth    = 0.51em,
%    gobble       = 3,
%    keywordstyle = \color{blue},
%    language     = [LaTeX]{TeX},
%    moretexcs    = {
%      examplemacro,
%      ^^A Add you command names here!
%    }
%  }^^A
%}
%\newcommand*\LaTeXdemo@input{^^A
%  \MakePercentComment
%  \catcode\^^M=10\relax
%  \small
%  \begingroup
%    \setkeys{lst}{
%      SelectCharTable=\lst@ReplaceInput{\^\^I}{\lst@ProcessTabulator}
%    }^^A
%    \leavevmode
%      \input{\jobname.tmp}^^A
%  \endgroup
%  \MakePercentIgnore
%}
%\LaTeXdemo@new{code and example}{^^A
%  \setbox\LaTeXdemo@box=\hbox\bgroup
%    \lst@BeginAlsoWriteFile{\jobname.tmp}^^A
%    \LaTeXdemo@common
%}{^^A
%    \lst@EndWriteFile
%  \egroup
%  \begin{center}
%    \ifdim\wd\LaTeXdemo@box>0.48\linewidth\relax
%      \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
%        \begin{minipage}{\linewidth}
%          \LaTeXdemo@input
%        \end{minipage}
%    \else
%      \begin{minipage}{0.48\linewidth}
%        \LaTeXdemo@input
%      \end{minipage}
%      \hfill
%      \begin{minipage}{0.48\linewidth}
%        \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
%      \end{minipage}
%    \fi
%  \end{center}
%}
%\LaTeXdemo@new{code only}{^^A
%  \LaTeXdemo@common
%}{^^A
%}


(This is taken directly from a .dtx, hence the apparent comment-out characters!) This can then be used as

%\begin{LaTeXdemo}
%  Some clever demo here
%\end{LaTeXdemo}


and will typeset the code and the result of the code side-by-side.

I use a three character 'gobble' as the way I tend to lay out my code is to indent by two spaces for each environment, and there is also the % to gobble. I also have an optional argument to my demo environment, so I can do things like

%\begin{LaTeXdemo}[code only]
%  \usepackage{foo}
%\end{LaTeXdemo}


to explain preamble-only stuff and similar 'show code but don't actually execute' material.

If you have stuff which needs to float, you need a different demo, which I set up using the additional lines

%\LaTeXdemo@new{code and float}{^^A
%  \lst@BeginAlsoWriteFile{\jobname.tmp}^^A
%  \LaTeXdemo@common
%}{^^A
%  \lst@EndWriteFile
%  \LaTeXdemo@input
%}


This again is set up to work with an optional argument to the environment, and avoids placing the float inside a box (which will fail).

-
This is close to my current implementation of my templatedemo package. It would be worth to generalize such approaches in a package. However I am using filecontents and lstinputlisting as a result of some discussion here within the last days. Anyway: do you have an example dtx file demonstrating the usage of your code? –  Matthias Pospiech Oct 9 '11 at 16:11
@MatthiasPospiech See my packages on CTAN (perhaps achemso` would be best - no LaTeX3 stuff but relatively big). See also texdev.net/2009/10/06/a-model-dtx-file –  Joseph Wright Oct 9 '11 at 16:16