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.