Creating Package Documentation

LaTeX
Getting Started Introduction Installation Installing Extra Packages Basics How to get help Common Elements Document Structure Text Formatting Paragraph Formatting Colors Fonts List Structures Special Characters Internationalization Rotations Tables Title creation Page Layout Customizing Page Headers and Footers‎ Importing Graphics Floats, Figures and Captions Footnotes and Margin Notes Hyperlinks Labels and Cross-referencing Initials Mechanics Errors and Warnings Lengths Counters Boxes Rules and Struts Technical Text Mathematics Advanced Mathematics Theorems Chemical Graphics Algorithms Source Code Listings Linguistics Special Pages Indexing Glossary Bibliography Management More Bibliographies Special Documents Scientific Reports (Bachelor Report, Master Thesis, Dissertation) Letters Presentations Teacher's Corner Curriculum Vitae Academic Journals (MLA, APA, etc.) Creating Graphics Introducing Procedural Graphics MetaPost Picture PGF/TikZ PSTricks Xy-pic Creating 3D graphics Programming Macros Plain TeX Creating Packages Creating Package Documentation Themes Miscellaneous Modular Documents Collaborative Writing of LaTeX Documents Export To Other Formats Help and Recommendations FAQ Tips and Tricks Appendices Authors Links Package Reference Sample LaTeX documents Index Command Glossary
edit this box • edit the TOC

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

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.

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.

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