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. Commented Oct 9, 2011 at 14:21
  • 2
    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. Commented Oct 9, 2011 at 14:32
  • @Marco: I have no idea which perl script shall do what for this problem. Commented Oct 9, 2011 at 16:12
  • @MatthiasPospiech: For example: makedtx Commented Oct 9, 2011 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. Commented Oct 9, 2011 at 17:59

2 Answers 2


Something like

% \iffalse
% \fi
first line
second line
% \iffalse
% \fi

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

The \iffalse...\fi prevents the tag from being printed; the tag itself prevents the uncommented code from being included in the .sty file after docstrip processing.


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:

%\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
%  \LaTeXdemo@end
%  \expandafter\newcommand\expandafter*\expandafter
%    {\csname LaTeXdemo@#1\endcsname}{#2}^^A
%  \expandafter\newcommand\expandafter*\expandafter
%    {\csname LaTeXdemo@#1@end\endcsname}{#3}^^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
%  \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
%    \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

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

%  Some clever demo here

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}

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
%  \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? Commented Oct 9, 2011 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
    Commented Oct 9, 2011 at 16:16

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .