Welcome to the UK List of
TeX Frequently Asked Questions
on the Web

Searching

The index of Frequently Asked Questions about TeX is searchable.

Please enter your keyword here:   then press here: ,    or:
Google

Documented LaTeX sources (.dtx files)

LaTeX2e, 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. If the .ins file is available, you may process it with LaTeX to produce the package (and, often, auxiliary files).

Output should look something like:

Generating 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

The lines “Processing … ended by \endinput” may be repeated if the .dtx file 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 .dtx file, as “documentation”.)

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 and .ins files).

Composition of .dtx files is supported in emacs by AUC-TeX.

The (unix-based) script dtxgen generates a proforma basic .dtx file, which could be useful when starting a new project.

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 with .dtx files, since they use an unusual class file.

The sty2dtx system goes one step further: it attempts to create a .dtx file from a ‘normal’ .sty file 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).

The .dtx files are not used by LaTeX after they have been processed to produce .sty or .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 package to Metafont and MetaPost, thus permitting documented distribution of bundles containing code for Metafont and MetaPost together with related LaTeX code.

AUC-TeX
support/auctex; catalogue entry
clsguide.pdf
macros/latex/doc/clsguide.pdf; catalogue entry
docmfp.sty
macros/latex/contrib/docmfp (or browse the directory); catalogue entry
docstrip.tex
Part of the LaTeX distribution
DTX tutorial
info/dtxtut (or browse the directory); catalogue entry
dtxgen
support/dtxgen (or browse the directory); catalogue entry
makedtx
support/makedtx (or browse the directory); catalogue entry
sty2dtx
support/sty2dtx (or browse the directory); catalogue entry

This answer last edited: 2014-06-03


Go to previous question, or next question

Go to FAQ home.

URL for this question: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=dtx

Comments, suggestions, or error reports? - see “how to improve the FAQ”.

This is FAQ version 3.28, released on 2014-06-10.