Classes for LaTeX documentation

Question

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.

Answer 1

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.

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:

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.

Answer 2

A remark at first: I’ve no clue in writing packages or even classes …

I could darkly remember, that some months ago Florent Chervet released such a package. After a short research I've found fcltxdoc. The manual belonging to that says:

fcltxdoc provides some facilities to print documentation (.dtx) files. Most of them are further development of commands defined in the undocumented package holtxdoc.

(It also says, that it is “not intended for public use... ...but it may be used – or copied – by the public!”)

Searching again: holtxdoc is part of the oberdiek bundle, and the manual tells us

Caution: This package is not intended for public use! …Thus the package does not know anything about compatibility. Only my current packages’ documentation must compile.

Older versions were more interesting, because they contained code to add hyper- ref’s features to LATEX’s doc system, e.g. bookmarks and index links. I separated this stuff and made a new package hypdoc.

hypdoc is of course also part of the oberdiek bundle.

Take a look at these packages.

Edit: mbork points to gmdoc. There is also a package gmdoc-enhance, whose documentation is written only in German.

Update:
This answer does not at all intend to be comprehensive, but since last edit three more classes for documentation are published by members of TeX.SE:

• The latest release is ncltdoc by Nicola Talbot. No own documentation.

• One of our admins, Martin Scharrer, developed ydoc for his own packages. The documentation is not fully complete. This is in fact a bundle of a class with some packages. These packages also could be used independently of the class.

• Simon “You” Sigurdhsson, inspired by a question here on TeX.SE, created skdoc, heavily based on ydoc. The documentation seems to be complete.

BTW Martin points in the ydoc documentation to some other classes, as well. Not all of them are already mentioned here:

Similar Packages

Other documentation related classes and packages are ltxdoc, doc, dox, xdoc, gmdoc, pauldoc, hypdoc, codedoc, nicetext and tkz-doc.

He also writes about the main reason we can assume, why there are so many different classes for the same task (“the author” = Martin):

All these packages didn’t suited the author and therefore he, take a guess, wrote his own documentation package.

Answer 3

There is also gmdoc. I don't remember much about its flexibility (I read its manual quite a time ago), but it works with hyperref to produce clickable indices etc. Also, given that the author is Polish, it should work in (at least one of) non-English languages (I did use it personally with a class documented in Polish, and it worked fine).