23

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.
2
  • Do you want highlighting in the user part of the documentation (where listings is workable), or in the actual implementation part? The two are not the same 'problem'.
    – Joseph Wright
    Feb 22, 2012 at 16:55
  • @JosephWright: Both :-). May I should post this as a separate question, at this place I wanted to collect different documentation classes … ?
    – Tobi
    Feb 22, 2012 at 17:53

3 Answers 3

18
+50

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.

5
  • Thank you very much for this answer. Sure it would be nice to see how you do your documentations, but it was not my (main) intention. With some time I can develop my own class for documentations but I wondered if there are finished classes the work and look good “ex factory” … At the moment I’m using ltxdoc with hypdoc and some adaptions. I’m developing my packages in a tex file and paste it from time to time to the dtx file. I set up my editor to be able to compile the ins file before processing the test file or extract the manual from the dtx with makindex etc.
    – Tobi
    Mar 5, 2012 at 22:12
  • @Tobi -- Thanks for the comment. Sorry if my post was not that clear. My suggestion is to follow the listings and microtype style and include their documentation packages with the standard ltxdoc class, i.e., include lstdoc and or docstyle packages, provided by listings and microtype respectively. Based on what you describe as your workflow, it will be better to follow the smaller package approach I described above. Mar 6, 2012 at 5:22
  • Ahh :-) OK. “Based on what …” but if I want to have a dtx in the final distribution it’s less work to work directly with dtx.
    – Tobi
    Mar 6, 2012 at 13:50
  • @Tobi The final distribution will only have one dtx file. The code should be included like 'usepackage{lstdoc} etc, in the driver section of your dtx file. Mar 6, 2012 at 14:03
  • Yes I know. :-) My comment was referring to your suggestion to build the sty with {filecontents} instead of a regular dtx file. To explain my workflow is to long for a comment, You may ask a question about who people develop and I can answer it or you sen an e-mail at [email protected]
    – Tobi
    Mar 6, 2012 at 15:17
6

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.

4

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).

4
  • 1
    Wow, the “manual” is the documented source. Funnyly there is a package gmdoc-enhance, whose documentation is in only in German (but that’s not a problem for Tobi).
    – Speravir
    Mar 5, 2012 at 16:09
  • Thanks for this tip. German is much better than english for me :-)
    – Tobi
    Mar 6, 2012 at 15:31
  • @Speravir: It seems thay you can skip the source and get to the real manual. Mar 8, 2012 at 15:50
  • @AndreyVihrov: (You relate to gmdoc, I guess.) Ah, thanks. That's really confusing or even misleading, that the toc is set after the source.
    – Speravir
    Mar 8, 2012 at 16:47

You must log in to answer this question.

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