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
|
<head>
<title>UK TeX FAQ -- question label install-doc</title>
</head><body>
<h3>Generating package documentation</h3>
<p/>We are faced with a range of “normal” provision, as well as several
oddities. One should note that documentation of many packages is
available on CTAN, without the need of any further effort by
the user — such documentation can usually be browsed <em>in situ</em>.
<p/>However, if you find a package that does not offer documentation on
the archive, or if you need the documentation in some other format
than the archive offers, you can usually generate the documentation
yourself from what you download from the archive.
<p/>The standard mechanism, for LaTeX packages, is simply to run
LaTeX on the <i>package.dtx</i> file, as you would any ordinary
LaTeX file (i.e., repeatedly until the warnings go away).
<p/>A variant is that the unpacking process provides a file
<i>package.drv</i>; if such a thing appears, process it in preference
to the <i>package.dtx</i> (it seems that when the documented LaTeX
source mechanism was first discussed, the <i>.drv</i> mechanism was
suggested, but it’s not widely used nowadays).
<p/>Sometimes, the LaTeX run will complain that it can’t find
<i>package.ind</i> (the code line index) and/or <i>package.gls</i>
(the list of change records, not as you might imagine, a glossary).
Both types of file are processed with special <i>makeindex</i>
style files; appropriate commands are:
<blockquote>
<pre>
makeindex -s gind package
makeindex -s gglo -o package.gls package.glo
</pre>
</blockquote><p>
This author finds that the second (the change record) is generally of
limited utility when reading package documentation; it is, however,
valuable if you’re part of the package development team. If you don’t
feel you need it, just leave out that step
<p/>Another common (and reasonable) trick performed by package authors is
to provide a separate file <i>package-doc.tex</i> or even simply
<i>manual.tex</i>; if the file <i>package.dtx</i> doesn’t help, simply
look around for such alternatives. The files are treated in the same
way as any “ordinary” LaTeX file.
<p/><p>This question on the Web: <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=install-doc">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=install-doc</a>
</body>
|