summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/html/FAQ-dtx.html
blob: cbbed32fbb15f6207e6eab07ce530795fa7180b1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
<head>
<title>UK TeX FAQ -- question label dtx</title>
</head><body>
<h3>Documented LaTeX sources (<code>.dtx</code> files)</h3>
<p/>LaTeX2e, and most contributed macro packages, are now written in a
<a href="FAQ-lit.html">literate programming style</a>, with source and
documentation in the
same file.  This format, known as &lsquo;doc&rsquo;, in fact originated before the
days of the LaTeX project as one of the &ldquo;Mainz&rdquo; series of
packages. A documented source file conventionally has the suffix
<code>.dtx</code>, and will normally be &lsquo;stripped&rsquo; before use with
LaTeX; an installation file (<code>.ins</code>) is normally provided,
to automate this process of removing comments for speed of loading.
To read the comments, you can run LaTeX on the
<code>.dtx</code> file to produce a nicely formatted version of the
documented code.  Several
packages can be included in one <code>.dtx</code> file (they&rsquo;re sorted
out by the <code>.ins</code> file), with conditional
sections, and there are facilities for indexes of macros, etc.
<p/>Anyone can write <code>.dtx</code> files; the format is explained in
<a href="FAQ-books.html">The LaTeX Companion</a>, and a tutorial is available
from CTAN (which comes with skeleton <code>.dtx</code> and
<code>.ins</code> files).
<p/>Composition of <code>.dtx</code> files is supported in <i>emacs</i> by
<a href="FAQ-editors.html">AUC-TeX</a>.
<p/>Another useful way of generating <code>.dtx</code> files is to write the
documentation and the code separately, and then to combine them using
the <i>makedtx</i> 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 
<a href="FAQ-LaTeX2HTML.html">LaTeX to HTML conversion</a> tools deal
with <code>.dtx</code> files, since they use an unusual class file.
<p/>The <code>.dtx</code> files are not used by LaTeX after they have been
processed to produce <code>.sty</code> or <code>.cls</code> (or whatever)
files.  They need not be kept with the working system; however, for
many packages the <code>.dtx</code> file is the primary source of
documentation, so you may want to keep <code>.dtx</code> files elsewhere.
<p/>An interesting sideline to the story of <code>.dtx</code> files is the
<i>docmfp</i> package, which extends the model of the <i>doc</i>
package to

  <a href="FAQ-MF.html">Metafont</a> and <a href="FAQ-MP.html">MetaPost</a>,
thus permitting documented distribution of bundles containing code for
Metafont and MetaPost together with related LaTeX code.
<dl>
<dt><tt><i>clsguide.pdf</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/doc/clsguide.pdf">macros/latex/doc/clsguide.pdf</a>
<dt><tt><i>docmfp.sty</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/docmfp.zip">macros/latex/contrib/docmfp</a> (<a href="ftp://cam.ctan.org/tex-archive/macros/latex/contrib/docmfp.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/macros/latex/contrib/docmfp/">browse</a>)
<dt><tt><i>docstrip.tex</i></tt><dd>Part of the LaTeX distribution
<dt><tt><i>DTX tutorial</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/info/dtxtut.zip">info/dtxtut</a> (<a href="ftp://cam.ctan.org/tex-archive/info/dtxtut.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/info/dtxtut/">browse</a>)
<dt><tt><i>makedtx</i></tt><dd><a href="ftp://cam.ctan.org/tex-archive/support/makedtx.zip">support/makedtx</a> (<a href="ftp://cam.ctan.org/tex-archive/support/makedtx.tar.gz">gzipped tar</a>, <a href="http://www.tex.ac.uk/tex-archive/support/makedtx/">browse</a>)
</dl>
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=dtx">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=dtx</a>
</body>