diff options
Diffstat (limited to 'winsup/doc/doctool.txt')
| -rw-r--r-- | winsup/doc/doctool.txt | 146 |
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. |