LaTeX 2e, and many contributed LaTeX macro packages, are written
in a literate programming style, with source and
documentation in the
same file. This format in fact originated before the
days of the LaTeX project as one of the “Mainz” series of
packages. A documented source file conventionally has the suffix
dtx, and will normally be ‘stripped’ before use with
LaTeX; an installation (
ins) file is normally provided,
to automate this process of removing comments for speed of loading.
ins file is available, you may process it
with LaTeX to produce the package (and, often, auxiliary files).
Output should look something like:
The lines “Processing … ended byGenerating file(s) ./foo.sty Processing file foo.dtx (package) -> foo.sty File foo.dtx ended by \endinput. Lines processed: 2336 Comments removed: 1336 Comments passed: 2 Codelines passed: 972
\endinput” may be repeated if the
dtxfile provides more than one ‘unpacked’ file.
To read the comments “as a document”, you can run LaTeX on the
dtx file to produce a nicely formatted version of the
documented code. (Most LaTeX packages on CTAN, nowadays, already
have PDF of the result of processing the
Several packages may be included in one
dtx file, with
conditional sections, and there are facilities for indexes of macros,
etc. All of this mélange is sorted out by directives in the
ins file; conventional indexing utilities may be necessary
for “full” output.
Anyone may write
dtx files; the format is explained in
The LaTeX Companion, and a tutorial is available
from CTAN (which comes with skeleton
dtx files is supported in emacs by
The (unix-based) script dtxgen generates a proforma basic
dtx file, which could be useful when starting a new
Another route to an
dtx file is to write the
documentation and the code separately, and then to combine them using
the makedtx system. This technique has particular value in
that the documentation file can be used separately to generate
HTML output; it is often quite difficult to make
LaTeX to HTML conversion tools deal
dtx files, since they use an unusual class file.
The sty2dtx system goes one step further: it attempts to
dtx file from a ‘normal’
with comments. It works well, in some circumstances, but can become
confused by comments that aspire to “structure” (e.g., tabular
material, as in many older packages’ file headers).
dtx files are not used by LaTeX after they have been
processed to produce
cls (or whatever)
files. They need not be kept with the working system; however, for
many packages the
dtx file is the primary source of
documentation, so you may want to keep
dtx files elsewhere.
An interesting sideline to the story of
dtx files is the
docmfp package, which extends the model of the doc
MetaFont and MetaPost,
thus permitting documented distribution of bundles containing code for
MetaFont and MetaPost together with related LaTeX code.
This answer last edited: 2014-06-03