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:

% \iffalse meta-comment % Add copyright,author,version information % here for this documentation file % \fi % \iffalse %<*driver> \ProvidesFile{mypackage.dtx}[1.0 My package] \documentclass{ltxdoc} \begin{document} \DocInput{\jobname.dtx} \end{document} %</driver> % \fi % write normal LaTeX documentation content here % \Finale % \endinput

When you run pdflatex mypackage.dtx, you can generate mypackage.pdf, which is the manual. In this pdf file, all contents after the \fi and \endinput are stripped out of the comment and inserted between the document. Notice that the first time the LaTeX engine encounters \DocInput, it reads the same file again but strips all lines starting with %. As a result, it ignores the code block with \iffalse ...\fi. It should also be noticed that the second pass of the same file also ignores the magic comments between %<driver> and %<*driver>. 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:

• \ProvidesFile{<name>}[<version>] works similar to \ProvidesPackage{<name>}[<version>], 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.
• ltxdoc 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

% \begin{macro}{\mymacro} % mymacro definition goes here % \end{macro}

The environment macro accepts a mandatory argument, which is the name of the macro and printed on the left margin. You can also use \DescribeMacro{mymacro} and put the extra explanations on the normal text. For new environment description, you can use \DescribeEnv{mynewenv}. Their difference lies in the index entry type, which will be illustrated below.

Index Entries and Changes

Add \EnableCrossrefs to the preamble of the package documentation file(without comment at line beginning). Add \PrintIndex 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:

makeindex -s gind.ist -o mypackage.ind mypackage.idx

ltxdoc also provides the functionality to record package changes. To enable this feature, add \RecordChanges to the preamble and use

\changes{v1.0}{2017/01/01}{create my package.}

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

makeindex -s gglo.ist -o mypackage.gls mypackage.glo