aboutsummaryrefslogtreecommitdiff
path: root/winsup/doc/doctool.txt
diff options
context:
space:
mode:
Diffstat (limited to 'winsup/doc/doctool.txt')
-rw-r--r--winsup/doc/doctool.txt146
1 files changed, 0 insertions, 146 deletions
diff --git a/winsup/doc/doctool.txt b/winsup/doc/doctool.txt
deleted file mode 100644
index c89e392..0000000
--- a/winsup/doc/doctool.txt
+++ /dev/null
@@ -1,146 +0,0 @@
-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.