LaTeX/Creating Package Documentation

From Wikibooks, open books for an open world
Jump to navigation Jump to search

LaTeX

Getting Started
  1. Introduction
  2. Installation
  3. Installing Extra Packages
  4. Basics
  5. How to get help

Common Elements

  1. Document Structure
  2. Text Formatting
  3. Paragraph Formatting
  4. Colors
  5. Fonts
  6. List Structures
  7. Special Characters
  8. Internationalization
  9. Rotations
  10. Tables
  11. Title creation
  12. Page Layout
  13. Customizing Page Headers and Footers‎
  14. Importing Graphics
  15. Floats, Figures and Captions
  16. Footnotes and Margin Notes
  17. Hyperlinks
  18. Labels and Cross-referencing
  19. Initials

Mechanics

  1. Errors and Warnings
  2. Lengths
  3. Counters
  4. Boxes
  5. Rules and Struts

Technical Text

  1. Mathematics
  2. Advanced Mathematics
  3. Theorems
  4. Chemical Graphics
  5. Algorithms
  6. Source Code Listings
  7. Linguistics

Special Pages

  1. Indexing
  2. Glossary
  3. Bibliography Management
  4. More Bibliographies

Special Documents

  1. Scientific Reports (Bachelor Report, Master Thesis, Dissertation)
  2. Letters
  3. Presentations
  4. Teacher's Corner
  5. Curriculum Vitae
  6. Academic Journals (MLA, APA, etc.)

Creating Graphics

  1. Introducing Procedural Graphics
  2. MetaPost
  3. Picture
  4. PGF/TikZ
  5. PSTricks
  6. Xy-pic
  7. Creating 3D graphics

Programming

  1. Macros
  2. Plain TeX
  3. Creating Packages
  4. Creating Package Documentation
  5. Themes

Miscellaneous

  1. Modular Documents
  2. Collaborative Writing of LaTeX Documents
  3. Export To Other Formats

Help and Recommendations

  1. FAQ
  2. Tips and Tricks

Appendices

  1. Authors
  2. Links
  3. Package Reference
  4. Sample LaTeX documents
  5. Index
  6. Command Glossary

edit this boxedit 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

Basic structure[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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