1

I read some advice suggesting that when writing a package, one should use that package in one's dtx file in order to demonstrate the use of macros and environments. Presumably, the same should be true when writing a class, but I'm encountering the issue of not knowing how to actually do this. Attempting to stick \LoadClass{\jobname} (or even \LoadClass{democls} assuming the file is named democls.dtx) leads to a two \LoadClass commands error. (Note: I don't think my question is a duplicate of Is it possible to extract a .cls from a .dtx and avoid the Two \LoadClass commands error? because it doesn't seem like that question addresses directly using macros and environments defined by the class in the typesetting of the class documentation. I am basing my democls on the same Joseph Wright model dtx file, though.)

% \iffalse meta-comment
%<*internal>
\iffalse
%</internal>
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\preamble
(preamble)
\endpreamble
\postamble
(postamble)
\endpostamble
\usedir{tex/latex/democls}
\generate{
  \file{\jobname.cls}{\from{\jobname.dtx}{class}}
}
%</install>
%<install>\endbatchfile
%<*internal>
\usedir{source/latex/democls}
\generate{
  \file{\jobname.ins}{\from{\jobname.dtx}{install}}
}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%<*class>
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{democls}[2015/07/07 v1.0 description text]
%</class>
%<*driver>
\documentclass{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% 
%\GetFileInfo{\jobname.cls}
%
%\title{^^A
%  \textsf{democls} --- description text\thanks{^^A
%    This file describes version \fileversion, last revised \filedate.^^A
%  }^^A
%}
%\author{^^A
%  You\thanks{email: you+obfuscation@your.domain}^^A
%}
%\date{Released \filedate}
%%
%\maketitle
%
%\DescribeMacro{\examplemacro}
% Some text about an example macro called \cs{examplemacro}, which
% might have an optional argument \oarg{arg1} and mandatory one
% \marg{arg2}. It looks like \examplemacro{foo}{bar}.
%
%    \begin{macrocode}
%<*class>
%    \end{macrocode}
%
%    \begin{macrocode}
\LoadClass{article}
%    \end{macrocode}
%
%\begin{macro}{\examplemacro}
%    \begin{macrocode}
\newcommand{\examplemacro}[2][]{%
  \textit{#1 #2}
}
%    \end{macrocode}
%\end{macro} 
%
%    \begin{macrocode}
%</class>
%    \end{macrocode}
%\Finale

edit: If anyone cares to make use of the finished templates, they're available at https://github.com/RyanMatlock/LaTeX-dtx-templates.

  • 3
    Whilst using the source .dtx as a demo is common for packages (which are normally safe to mix in with other code), for classes that is far less likely to be the case. Specialised classes may well be poorly suited to actually typesetting the documentation (which will have lots of code-related material in it). I would favour using a separate .tex file as a demo. – Joseph Wright Jul 8 '15 at 6:17
  • 1
    When you say "a separate .tex file," I don't see any reason not to include it in between %<*demo>...%</demo> guards and create it with \generate{\file{demodoc.tex}{\from{\jobname.dtx}{demo}}. You could maybe get really fancy and have your first pass of pdflatex democls.dtx also generate a bash script that runs makeindex on democls.tex, pdflatex on democls.dtx and demodoc.tex, and then mvs the .cls file to $TEXMFHOME. Does that sound reasonable? – Ryan M Jul 8 '15 at 11:41
  • 1
    Yes, of course one can included such a demo file in the .dtx. (Generating a script doesn't work so well cross-platform, so I'd tend to avoid.) My experience is that for a small package an 'all in one' .dtx works but as projects get bigger this becomes more tricky: editing big files, etc. is not so easy. For example, I've recently split up achemso to have a separate demo file rather than bundle it in the .dtx. Your call, of course. – Joseph Wright Jul 8 '15 at 11:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.