winsup/doc/doctool.txt

   1 Doctool
   2
   3 DJ Delorie <dj@cygnus.com>
   4
   5 These are the instructions for using doctool.  Yes, I should have
   6 written them *in* DocBook, but hey, I was in a hurry.
   7
   8 OK, doctool is a program that gathers snippets of a docbook document and
   9 puts them all together in the right order.  There are three
  10 places that it gets snippets from:
  11
  12 1. The document that you tell it you want "finished"
  13
  14 2. blocks of SGML in *.sgml files
  15
  16 3. comments in source code
  17
  18 The first of these is the template file, which is to say, it's a
  19 normal SGML file (sort of).  This file is the first one read, and
  20 includes such things as your <book> tags etc.  It contains commands to
  21 doctool to tell it where to put the other parts.
  22
  23 The second, the *.sgml files, contain one or more blocks of SGML.
  24 To work with doctool, each of these snippets must begin and end
  25 with matching tags, must have an id="" attribute, and the start/end
  26 tags must begin at the beginning of the line.  For example:
  27
  28 <foo id="frob-45">
  29   stuff goes here
  30 </foo>
  31 <bar id="frob-48">
  32   stuff goes here
  33 </bar>
  34
  35 In this example, the file contains two snippets, one marked by "foo"
  36 and one barked by "bar", with id's "from-45" and "from-48".  Note that
  37 I made up the foo and bar tags.  You'd usually use a <sect1> tag or
  38 something useful like that.  Stuff outside the blocks is ignored.
  39
  40 The third is simply an encapsulation of the second in comments, like this:
  41
  42 /* DOCTOOL-START
  43 <foo id="frob-45">
  44   stuff goes here
  45 </foo>
  46 DOCTOOL-END */
  47
  48 The DOCTOOL-START and DOCTOOL-END things are special.  Doctool uses
  49 those to know which parts of which comments are useful, and which
  50 parts are the useless source code stuff ;-)
  51
  52
  53 OK, so now we've got all these snippets of SGML floating around.  What
  54 do we do with them?  Well, inside the template document (#1 in our
  55 list up there) you'd put text snippets that said "ok, put them
  56 here".  Each text snippet looks like this:
  57
  58 DOCTOOL-INSERT-frob-
  59
  60 Note that the "frob-" part tells doctool to pull in all the snippets
  61 with IDs that start with "frob-", in alphabetical (well, asciibetical
  62 at the moment) order.  So, by saying "DOCTOOL-INSERT-frob-" you'd get
  63 all the "frob-*" snippets, like "frob-45" and "frob-48".
  64
  65 If you just said DOCTOOL-INSERT-frob, it inserts the snippet named
  66 "frob" and no others.
  67
  68 Note that no snippet will ever be inserted more than once, no matter
  69 how many DOCTOOL-INSERTs you have.
  70
  71 There's two other tricks doctool has.  If it finds a snippet with an ID
  72 like "int-*" (i.e. int-frob-45) that means that snippet of documentation
  73 is for the "internal" version only.  The "int-" is discarded, and if
  74 the -i option is given to doctool, this snippet is treated as if the
  75 int- wasn't there.  Without the -i, the int-* snippets are ignored
  76 completely.
  77
  78 If a snippet has "add-" on it, like "add-frob-45", that's an addendum.
  79 Each time a snippet named without the add- is found, doctool looks for
  80 an addendum with exactly that same name (i.e. frob-45 looks for
  81 add-frob-45).  If it finds any, it puts them just before the last line
  82 of the non-add snippet (so that it's *inside* the main snippet's
  83 block, not after it).  Example:
  84
  85 <sect1 id="frob-45">
  86   some text
  87 </sect1>
  88 <sect1 id="add-frob-45">
  89   more text
  90 </sect1>
  91
  92 This would yield:
  93
  94 <sect1 id="frob-45">
  95   some text
  96   more text
  97 </sect1>
  98
  99 You should use the same outermost tags as the main snippet, but only
 100 because it sets the proper nesting rules for what's enclosed.
 101
 102 You can use add- and int- at the same time, but always do add-int- and
 103 not int-add- (i.e. "add-int-frob-45").
 104
 105
 106 OK, now for doctool command line options.
 107
 108 -m tells doctool to "fix" the Makefile (not makefile) to include the
 109 extra dependencies needed by the file you're generating.  You need to
 110 manually include dependencies on the Makefile itself and the template
 111 file; doctool only includes the snippet files (sources etc) that it
 112 actually pulled content from.  Note: this isn't perfect!  Someone can
 113 come along and add a new snippet to a source file, and doctool would
 114 never know.  Sometimes, it's best to just rebuild the docs all the
 115 time.
 116
 117 -i means to include snippets with the "int-" prefix on their IDs.  Use
 118 with -b to make internal and public versions from the same sources.
 119
 120 "-d dir" tells doctool to scan all the files in that directory (and
 121 subdirectories, recursively) for files that might contain snippets of
 122 SGML.  These include *.c, *.cc, *.h, and *.sgml.  The idea is that
 123 most of the documentation would be in a *.sgml file named after the
 124 source (i.e. foo.c -> foo.sgml) but some commentary within the source
 125 might be useful in the docs as well.  SGML files (*.sgml) do not need
 126 the DOCTOOL-START/END tags but the others do.
 127
 128 -o sets the output file.  Without -o, the file goes to stdout (ick).
 129
 130 -s tells doctool to supress a "source directory prefix".  What this
 131 means is that, in the generated output doctool puts comments that say
 132 where each snippet comes from (for debugging), which includes the full
 133 path sometimes, but if you use -s, you can tell doctool to cut off
 134 that prefix.  For example,
 135 /usr/people/dj/src/cygnus/latest/devo/winsup/foo.c might get shortened
 136 to winsup/foo.c if you gave "-s
 137 /usr/people/dj/src/cygnus/latest/devo/".  Cygnus makefiles could
 138 just use -s $(srcdir) most of the time.
 139
 140 -b changes the ID for the <book> tag.  db2html uses the <book> tag's
 141 ID as the default subdirectory name and/or html file name to create
 142 the book with.  You'd need this to generate two books (internal vs
 143 public) from the same source.
 144
 145 The only other thing you'd add to the command line is the ONE template
 146 file you want to pull in.