147 lines
5.4 KiB
Plaintext
147 lines
5.4 KiB
Plaintext
Doctool
|
|
|
|
DJ Delorie <dj@cygnus.com>
|
|
|
|
These are the instructions for using doctool. Yes, I should have
|
|
written them *in* DocBook, but hey, I was in a hurry.
|
|
|
|
OK, doctool is a program that gathers snippets of a docbook document and
|
|
puts them all together in the right order. There are three
|
|
places that it gets snippets from:
|
|
|
|
1. The document that you tell it you want "finished"
|
|
|
|
2. blocks of SGML in *.sgml files
|
|
|
|
3. comments in source code
|
|
|
|
The first of these is the template file, which is to say, it's a
|
|
normal SGML file (sort of). This file is the first one read, and
|
|
includes such things as your <book> tags etc. It contains commands to
|
|
doctool to tell it where to put the other parts.
|
|
|
|
The second, the *.sgml files, contain one or more blocks of SGML.
|
|
To work with doctool, each of these snippets must begin and end
|
|
with matching tags, must have an id="" attribute, and the start/end
|
|
tags must begin at the beginning of the line. For example:
|
|
|
|
<foo id="frob-45">
|
|
stuff goes here
|
|
</foo>
|
|
<bar id="frob-48">
|
|
stuff goes here
|
|
</bar>
|
|
|
|
In this example, the file contains two snippets, one marked by "foo"
|
|
and one barked by "bar", with id's "from-45" and "from-48". Note that
|
|
I made up the foo and bar tags. You'd usually use a <sect1> tag or
|
|
something useful like that. Stuff outside the blocks is ignored.
|
|
|
|
The third is simply an encapsulation of the second in comments, like this:
|
|
|
|
/* DOCTOOL-START
|
|
<foo id="frob-45">
|
|
stuff goes here
|
|
</foo>
|
|
DOCTOOL-END */
|
|
|
|
The DOCTOOL-START and DOCTOOL-END things are special. Doctool uses
|
|
those to know which parts of which comments are useful, and which
|
|
parts are the useless source code stuff ;-)
|
|
|
|
|
|
OK, so now we've got all these snippets of SGML floating around. What
|
|
do we do with them? Well, inside the template document (#1 in our
|
|
list up there) you'd put text snippets that said "ok, put them
|
|
here". Each text snippet looks like this:
|
|
|
|
DOCTOOL-INSERT-frob-
|
|
|
|
Note that the "frob-" part tells doctool to pull in all the snippets
|
|
with IDs that start with "frob-", in alphabetical (well, asciibetical
|
|
at the moment) order. So, by saying "DOCTOOL-INSERT-frob-" you'd get
|
|
all the "frob-*" snippets, like "frob-45" and "frob-48".
|
|
|
|
If you just said DOCTOOL-INSERT-frob, it inserts the snippet named
|
|
"frob" and no others.
|
|
|
|
Note that no snippet will ever be inserted more than once, no matter
|
|
how many DOCTOOL-INSERTs you have.
|
|
|
|
There's two other tricks doctool has. If it finds a snippet with an ID
|
|
like "int-*" (i.e. int-frob-45) that means that snippet of documentation
|
|
is for the "internal" version only. The "int-" is discarded, and if
|
|
the -i option is given to doctool, this snippet is treated as if the
|
|
int- wasn't there. Without the -i, the int-* snippets are ignored
|
|
completely.
|
|
|
|
If a snippet has "add-" on it, like "add-frob-45", that's an addendum.
|
|
Each time a snippet named without the add- is found, doctool looks for
|
|
an addendum with exactly that same name (i.e. frob-45 looks for
|
|
add-frob-45). If it finds any, it puts them just before the last line
|
|
of the non-add snippet (so that it's *inside* the main snippet's
|
|
block, not after it). Example:
|
|
|
|
<sect1 id="frob-45">
|
|
some text
|
|
</sect1>
|
|
<sect1 id="add-frob-45">
|
|
more text
|
|
</sect1>
|
|
|
|
This would yield:
|
|
|
|
<sect1 id="frob-45">
|
|
some text
|
|
more text
|
|
</sect1>
|
|
|
|
You should use the same outermost tags as the main snippet, but only
|
|
because it sets the proper nesting rules for what's enclosed.
|
|
|
|
You can use add- and int- at the same time, but always do add-int- and
|
|
not int-add- (i.e. "add-int-frob-45").
|
|
|
|
|
|
OK, now for doctool command line options.
|
|
|
|
-m tells doctool to "fix" the Makefile (not makefile) to include the
|
|
extra dependencies needed by the file you're generating. You need to
|
|
manually include dependencies on the Makefile itself and the template
|
|
file; doctool only includes the snippet files (sources etc) that it
|
|
actually pulled content from. Note: this isn't perfect! Someone can
|
|
come along and add a new snippet to a source file, and doctool would
|
|
never know. Sometimes, it's best to just rebuild the docs all the
|
|
time.
|
|
|
|
-i means to include snippets with the "int-" prefix on their IDs. Use
|
|
with -b to make internal and public versions from the same sources.
|
|
|
|
"-d dir" tells doctool to scan all the files in that directory (and
|
|
subdirectories, recursively) for files that might contain snippets of
|
|
SGML. These include *.c, *.cc, *.h, and *.sgml. The idea is that
|
|
most of the documentation would be in a *.sgml file named after the
|
|
source (i.e. foo.c -> foo.sgml) but some commentary within the source
|
|
might be useful in the docs as well. SGML files (*.sgml) do not need
|
|
the DOCTOOL-START/END tags but the others do.
|
|
|
|
-o sets the output file. Without -o, the file goes to stdout (ick).
|
|
|
|
-s tells doctool to supress a "source directory prefix". What this
|
|
means is that, in the generated output doctool puts comments that say
|
|
where each snippet comes from (for debugging), which includes the full
|
|
path sometimes, but if you use -s, you can tell doctool to cut off
|
|
that prefix. For example,
|
|
/usr/people/dj/src/cygnus/latest/devo/winsup/foo.c might get shortened
|
|
to winsup/foo.c if you gave "-s
|
|
/usr/people/dj/src/cygnus/latest/devo/". Cygnus makefiles could
|
|
just use -s $(srcdir) most of the time.
|
|
|
|
-b changes the ID for the <book> tag. db2html uses the <book> tag's
|
|
ID as the default subdirectory name and/or html file name to create
|
|
the book with. You'd need this to generate two books (internal vs
|
|
public) from the same source.
|
|
|
|
The only other thing you'd add to the command line is the ONE template
|
|
file you want to pull in.
|