newlib/winsup/doc/doctool.txt

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.