contrib/bind9/doc/arm/README-SGML

   1 Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 Copyright (C) 2000, 2001  Internet Software Consortium.
   3 See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
   4
   5 The BIND v9 ARM master document is now kept in DocBook XML format.
   6
   7 Version: $Id: README-SGML,v 1.17 2004/03/05 05:04:43 marka Exp $
   8
   9 The entire ARM is in the single file:
  10
  11     Bv9ARM-book.xml
  12
  13 All of the other documents - HTML, PDF, etc - are generated from this
  14 master source.
  15
  16 This file attempts to describe what tools are necessary for the
  17 maintenance of this document as well as the generation of the
  18 alternate formats of this document.
  19
  20 This file will also spend a very little time describing the XML and
  21 SGML headers so you can understand a bit what you may need to do to be
  22 able to work with this document in any fashion other than simply
  23 editing it.
  24
  25 We will spend almost no time on the actual tags and how to write an
  26 XML DocBook compliant document. If you are at all familiar with SGML
  27 or HTML it will be very evident. You only need to know what the tags
  28 are and how to use them. You can find a good resource either for this
  29 either online or in printed form:
  30
  31     DocBook: The Definitive Guide
  32     By Norman Walsh and Leonard Muellner
  33     ISBN: 156592-580-7
  34     1st Edition, October 1999
  35     Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
  36
  37 The book is available online in HTML format:
  38
  39     http://docbook.org/
  40
  41 and buried in:
  42
  43     http://www.nwalsh.com/docbook/defguide/index.html
  44
  45 A lot of useful stuff is at NWalsh's site in general. You may also
  46 want to look at:
  47
  48     http://www.xml.com/
  49
  50 The BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
  51 SGML document begins with a prefix that tells where to find the file
  52 that describes the meaning and structure of the tags used in the rest
  53 of the document.
  54
  55 For our XML DocBook 4.0 based document this prefix looks like this:
  56
  57     <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
  58                    "/usr/local/share/xml/dtd/docbook/docbookx.dtd">
  59
  60 This "DOCTYPE" statement has three parts, of which we are only using
  61 two:
  62
  63 o The highest level term that represents this document (in this case
  64   it is "book"
  65
  66 o The identifier that tells us which DTD to use. This identifier has
  67   two parts, the "Formal Public Identifier" (or FPI) and the system
  68   identifier. In SGML you can have either a FPI or a SYSTEM identifier
  69   but you have to have at least one of them. In XML you have to have a
  70   SYSTEM identifier.
  71
  72 FP & SYSTEM identifiers - These are names/lookups for the actual
  73 DTD. The FPI is a globally unique name that should, on a properly
  74 configured system, tell you exactly what DTD to use. The SYSTEM
  75 identifier gives an absolute location for the DTD. In XML these are
  76 supposed to be properly formatted URL's.
  77
  78 SGML has these things called "catalogs" that are files that map FPI's
  79 in to actual files. A "catalog" can also be used to remap a SYSTEM
  80 identifier so you can say something like: "http://www.oasis.org/foo"
  81 is actually "/usr/local/share/xml/foo.dtd"
  82
  83 When you use various SGML/XML tools they need to be configured to look
  84 at the same "catalog" files so that as you move from tool to tool they
  85 all refer to the same DTD for the same document.
  86
  87 We will be spending most of our configuration time making sure our
  88 tools use the same "catalog" files and that we have the same DTD's
  89 installed on our machines. XML's requirement of the SYSTEM identifier
  90 over the FPI will probably lead to more problems as it does not
  91 guarantee that everyone is using the same DTD.
  92
  93 I did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
  94 "jade" or "openjade."
  95
  96 You can get the 4.0 XML DocBook DTD from:
  97
  98     http://www.docbook.org/xml/4.0/
  99
 100 (download the .zip file.) NOTE: We will eventually be changing the
 101 SYSTEM identifier to the recommended value of:
 102
 103     http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
 104
 105 NOTE: Under FreeBSD this is the package:
 106
 107     /usr/ports/textproc/docbook-xml
 108
 109 NetBSD instructions are coming soon.
 110
 111 With packages listed below installed under FreeBSD the "catalog" file
 112 that all the tools refer to at least one is in:
 113
 114     /usr/local/share/sgml/catalog
 115
 116 In order for our SYSTEM identifier for the XML DocBook dtd to be found
 117 I create a new catalog file at the top of the XML directory created on
 118 FreeBSD:
 119
 120    /usr/local/share/xml/catalog
 121
 122 This file has one line:
 123
 124    SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"
 125
 126 Then in the main "catalog" I have it include this XML catalog:
 127
 128    CATALOG "/usr/local/share/xml/catalog"
 129
 130
 131 On your systems you need to replace "/usr/local/share" with your
 132 prefix root (probably /usr/pkg under NetBSD.)
 133
 134 NOTE: The URL used above is supposed to the be the proper one for this
 135 XML DocBook DTD... but there is nothing at that URL so you really do
 136 need the "SYSTEM" identifier mapping in your catalog (or make the
 137 SYSTEM identifier in your document refer to the real location of the
 138 file on your local system.)
 139
 140 HOW TO VALIDATE A DOCUMENT:
 141
 142 I use the sgmltools "nsgmls" document validator. Since we are using
 143 XML we need to use the XML declarations, which are installed as part
 144 of the modular DSSL style sheets:
 145
 146     nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
 147            Bv9ARM-book.xml
 148
 149 A convenient shell script "validate.sh" is now generated by configure
 150 to invoke the above command with the correct system-dependent paths.
 151
 152 The SGML tools can be found at:
 153
 154     ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
 155     ftp://ftp.nllgg.nl/pub/SGMLtools/v2.0/source/
 156
 157 FreeBSD package for these is:
 158
 159     /usr/ports/textproc/sgmltools
 160
 161 HOW TO RENDER A DOCUMENT AS HTML or TeX:
 162
 163 o Generate html doc with:
 164
 165     openjade -v -d ./nominum-docbook-html.dsl \
 166          -t sgml \
 167          /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
 168          Bv9ARM-book.xml
 169
 170 A convenient shell script "genhtml.sh" is now generated by configure to
 171 invoke the above command with the correct system-dependent paths.
 172
 173 On NetBSD there is no port for "openjade" however "jade" does still
 174 work. However you need to specify the "catalog" file to use for style
 175 sheets on the command line AND you need to have a default "catalog"
 176 mapping where to find various DTDs. It seems that "jade" installed out
 177 of the box on NetBSD does not use a globally defined "catalog" file
 178 for mapping PUBLIC identifiers in to SYSTEM identifiers.
 179
 180 So you need to have a "catalog" file in your current working directory
 181 that has in it this: (these are probably more entries than you need!)
 182
 183      CATALOG "/usr/pkg/share/sgml/iso8879/catalog"
 184      CATALOG "/usr/pkg/share/sgml/docbook/2.4.1/catalog"
 185      CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog"
 186      CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog"
 187      CATALOG "/usr/pkg/share/sgml/jade/catalog"
 188      CATALOG "/usr/local/share/xml/catalog"
 189
 190 (These would all be "/usr/local" on FreeBSD)
 191
 192 So the command for jade on NetBSD will look like this:
 193
 194 jade -v -c /usr/pkg/share/sgml/catalog -t sgml \
 195      -d ./nominum-docbook-html.dsl \
 196      /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
 197      ./Bv9ARM-book.xml
 198
 199 Furthermore, since the style sheet subset we define has in it a hard
 200 coded path to the style sheet is based, it is actually generated by
 201 configure from a .in file so that it will contain the correct
 202 system-dependent path: where on FreeBSD the second line reads:
 203
 204     <!ENTITY dbstyle SYSTEM "/usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
 205
 206 On NetBSD it needs to read:
 207
 208     <!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
 209
 210 NOTE: This is usually solved by having this style sheet modification
 211 be installed in a system directory and have it reference the style
 212 sheet it is based on via a relative path.
 213
 214 o Generate TeX documentation:
 215
 216 openjade -d ./nominum-docbook-print.dsl -t tex -v \
 217      /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
 218      Bv9ARM-book.xml
 219
 220 If you have "jade" installed instead of "openjade" then use that as
 221 the command. There is little difference, openjade has some bug fixes
 222 and is in more active development.
 223
 224 To convert the resulting TeX file in to a DVI file you need to do:
 225
 226     tex "&jadetex" Bv9ARM-book.tex
 227
 228 You can also directly generate the pdf file via:
 229
 230     pdftex "&pdfjadetex" Bv9ARM-book.tex
 231
 232 The scripts "genpdf.sh" and "gendvi." have been added to simply
 233 generating the  PDF and DVI output. These substitute the correct paths
 234 of NetBSD & FreeBSD. You still need to have TeX, jadeTeX, and pdfTeX
 235 installed and configured properly for these to work.
 236
 237 You will need to up both the "pool_size" and "hash_extra" variables in
 238 your texmf.cnf file and regenerate them. See below.
 239
 240 You can see that I am using a DSSSL style sheet for DocBook. Actually
 241 two different ones - one for rendering html, and one for 'print'
 242 media.
 243
 244 NOTE: For HTML we are using a Nominum DSSSL style instead of the
 245 default one (all it does is change the chunking to the chapter level
 246 and makes the files end with ".html" instead of ".htm" so far.) If you
 247 want to use the plain jane DSSSL style sheet replace the:
 248
 249     -d ./nominum-docbook-html.dsl
 250
 251 with
 252
 253     -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl
 254
 255 This style sheet will attempt to reference the one above.
 256
 257 I am currently working on fixing these up so that it works the same on
 258 our various systems. The main trick is knowing which DTD's and DSSSL
 259 stylesheets you have installed, installing the right ones, and
 260 configuring a CATALOG that refers to them in the same way. We will
 261 probably end up putting our CATALOG's in the same place and then we
 262 should be able to generate and validate our documents with a minimal
 263 number of command line arguments.
 264
 265 When running these commands you will get a lot of messages about a
 266 bunch of general entities not being defined and having no default
 267 entity. You can ignore those for now.
 268
 269 Also with the style sheets we have and jade as it is you will get
 270 messages about "xref to title" being unsupported. You can ignore these
 271 for now as well.
 272
 273 === Getting the various tools installed on FreeBSD
 274 (NetBSD coming soon..)
 275
 276 o On freebsd you need to install the following packages:
 277   o print/teTeX
 278   o textproc/openjade
 279   o textproc/docbook
 280   o textproc/docbook-xml
 281   o textproc/dsssl-docbook-modular
 282   o textproc/dtd-catalogs
 283
 284 o on freebsd you need to make some entities visible to the docbook xml
 285   dtd by making a symlink (can probably be done with a catalog too)
 286   ln -s /usr/local/share/xml/entity /usr/local/share/xml/dtd/docbook/ent
 287
 288 o you may need to edit /usr/local/share/sgml/catalog and add the line:
 289
 290   CATALOG "/usr/local/share/sgml/openjade/catalog"
 291
 292 o add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
 293   file.
 294
 295   cd /usr/local/share/texmf/web2c/
 296   sudo cp texmf.cnf texmf.cnf.bak
 297
 298   o edit the lines in texmf.cnf with these keys to these values:
 299
 300                   main_memory = 1100000
 301                   hash_extra = 15000
 302                   pool_size = 500000
 303                   string_vacancies = 45000
 304                   max_strings = 55000
 305                   pool_free = 47500
 306                   nest_size = 500
 307                   param_size = 1500
 308                   save_size = 5000
 309                   stack_size = 1500
 310
 311   sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx
 312   sudo texconfig init
 313   sudo texhash
 314
 315   o For the jadetex macros you will need I recommend you get a more
 316     current version than what is packaged with openjade or jade.
 317
 318     Checkout http://www.tug.org/applications/jadetex/
 319
 320     Unzip the file you get from there (should be jadetex-2.20 or
 321     newer.)
 322
 323     In the directory you unzip:
 324
 325       sudo make install
 326       sudo texhash
 327
 328     NOTE: In the most uptodate "ports" for FreeBSD, jadetext is 2.20+
 329     so on this platform you should be set as of 2001.01.08.