import winsup-2000-02-17 snapshot

1 files changed, 146 insertions, 0 deletions

diff --git a/winsup/doc/doctool.txt b/winsup/doc/doctool.txt
new file mode 100644
index 0000000..c89e392
--- /dev/null
+++ b/winsup/doc/doctool.txt
@@ -0,0 +1,146 @@
+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.