[Tex/LaTex] Classes for LaTeX documentation

document-classesdocumentation

I wonder which classes are available to typeset LaTeX manuals. Until now I have used ltxdoc. I’m satisfied with its functions but not with its layout/design and it’s not really flexible when writing in a language other than English (see Class/package for German documentation). Furthermore the {verbatim} environment puts to much space after it.

Are there any other classes that can take the place of ltxdoc without causing too much work in adapting my existing .dtx files?

Is there a class that uses listings.sty instead of pure {verbatim}, to get syntax highlighting? I tried

\let\verbatim\relax
\let\endverbatim\relax
\lstnewenvironment{verbatim}{}{}

but this won’t work with a DocStrip input like

% Describing text for the following code
%    \begin{macrocode}
\newcommand{\foo}{FOO}
\newcommand{\bar}{BAR}
%    \end{macrocode}
% Some more text.

Best Answer

Documenting LaTeX sources with the default classes and packages is a bit of a patchwork, as the overall system has four major dependencies doc, docstrip, ltxdoc and article, plus the additional commands that you add in the driver.

Some of the major package authors have put a lot of effort to modify the standard classes the same way we all modify the preambles of the standard classes in our documents. Document classes, packages or extensive modifications that stand out are those of the listings (lstdoc), microtype (docstyle) and biblatex (ltxdockit) packages. For the commonly used classes you can have a look at Koma and memoir dtx files. The LaTeX3 project has also an experimental documentation class (l3doc.dtx), which is aesthetically very pleasing.

But in the end, you will probably want to define your own. This is not as hard as it sounds. The major issues in the typography of the documentation part normally lie within the "user manual" section. The implementation section is best done in a less colorful way with the only major change, the graying of the numbering.

enter image description here

Have a look at the microtype and LaTeX3 documentation to see how this improves the looks of the code part, especially when the line numbering gets into the thousands.

Now for the user manual part. This is where you need to put effort and anything is possible, down to having micro typography. A number of improvements are possible here. First to get in some form of boxing and to have a method for pretty printing of LaTeX code using listings. In addition depending on the package or class you are developing, running the actual examples automatically can make life easier. A package I would recommend to add is tcolorbox. It provides environments for display boxes, automatically executing the LaTeX code and is very good at displaying keys in the pgf style. In a preamble with a combination of all these, I managed to get this type of output:

enter image description hereenter image description here

The major difficulty I had was to get the hyperref, lstdoc and tcolorbox to be in the right order and load options without generating any clashes. This worked nicely:

\usepackage[pdftex,bookmarks,raiselinks,pageanchor,hyperindex,colorlinks]{hyperref}
\usepackage{lstdoc}
\usepackage[listings,theorems,documentation]{tcolorbox}

As simple as this sounds, plus the addition of microtypography and changing fonts to:

 \usepackage[charter]{mathdesign}
 \def\rmdefault{bch} % not scaled
 \def\ttdefault{blg}

had a marked improvement in the document typography.

The rest of the commands about 200 lines were to reformat the headers and sectioning commands. For microtypography I cut and pasted the relevant code from the microtype package.

If your package is smallish a very good short solution is to do the following:

\documentclass{article}
\usepackage{a,b,c,d,e} % as required
\usepackage{filecontents}
\begin{filecontents}{foo.sty}
... Package contents
\end{filecontents*}
\input{foo.sty}
\begin{document}
... User manual
... Code documentation
... \lstinputlisting{foo.sty} 
\end{document}

The package is typed within the filecontents environment and saved as foo.sty. You then input it in order to use it. At the main document you just input the code using one of the listings commands of the tcolorbox verbatim input commands. For anything up to a 100-200 code lines this is an excellent method and has the advantage that you are always working though one file. In addition while you developing the package you can test it at the same time while staying within one file. Styling of course will still be your own responsibility, but you will get pretty printing for both the manual as well as the code.

I have some code that I am busy with, if you interested to have a copy just post a comment (it is rather lengthy and I will clean it up and post it on github for you during the weekend). However MWE can be found at Different approach to literate programming for LaTeX.

Related Question