LaTeX/Creating Package Documentation

Documentation is important for the end users to quickly know how to use your package. They are also helpful to other developers since they can make it easier to read your codes. Each programming language has its own ways to make documentation. For LaTeX, we generate pdf documentation from .dtx file.

.dtx suffix is the acronym of documentation TeX. It has two kinds of functionality:
 * explain to users how to use commands in your package
 * format source codes for easier reading

Basic structure
Suppose you'd like to write a documentation for your newly created package called mypackage for example. The basic structure of .dtx file is like the following:

When you run pdflatex mypackage.dtx, you can generate mypackage.pdf, which is the manual. In this pdf file, all contents after the and  are stripped out of the comment and inserted between the document. Notice that the first time the LaTeX engine encounters, it reads the same file again but strips all lines starting with %. As a result, it ignores the code block with . It should also be noticed that the second pass of the same file also ignores the magic comments between and. The indicator driver manifests that the inner contents are a kind of wrapper to produce the final manual and you can replace them with other word as you like.

There are some macros which need some further explanations:
 * works similar to, it writes contents within the square brackets to the log file.
 * meta-comment is used to provide information of the .dtx file itself. As you can not use normal TeX comments, because they will be stripped.
 * <tt>ltxdoc</tt> is like other document class and provides some easy-to-use commands to write package documentation, which is illustatred below.

New Macro Description
To describe macros defined in your package, you can use

The environment <tt>macro</tt> accepts a mandatory argument, which is the name of the macro and printed on the left margin. You can also use and put the extra explanations on the normal text. For new environment description, you can use. Their difference lies in the index entry type, which will be illustrated below.

Index Entries and Changes
Add to the preamble of the package documentation file(without comment at line beginning). Add to the point where you'd like the index to appear. And all the macros you described will be printed at the end of the document. For the general introduction of making indices, see Compiling indices. Usually, the following building is enough:

<tt>makeindex</tt> -s gind.ist -o mypackage.ind mypackage.idx

<tt>ltxdoc</tt> also provides the functionality to record package changes. To enable this feature, add to the preamble and use

Add to the point where you'd like the index to appear. Changes are recorded with glossary support, invoke <tt>makeindex</tt> from command line:

<tt>makeindex</tt> -s gglo.ist -o mypackage.gls mypackage.glo