1Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 2Copyright (C) 2000, 2001 Internet Software Consortium. 3See COPYRIGHT in the source root or http://isc.org/copyright.html for terms. 4 5The BIND v9 ARM master document is now kept in DocBook XML format. 6 7Version: Id: README-SGML,v 1.17 2004/03/05 05:04:43 marka Exp 8 9The entire ARM is in the single file: 10 11 Bv9ARM-book.xml 12 13All of the other documents - HTML, PDF, etc - are generated from this 14master source. 15 16This file attempts to describe what tools are necessary for the 17maintenance of this document as well as the generation of the 18alternate formats of this document. 19 20This file will also spend a very little time describing the XML and 21SGML headers so you can understand a bit what you may need to do to be 22able to work with this document in any fashion other than simply 23editing it. 24 25We will spend almost no time on the actual tags and how to write an 26XML DocBook compliant document. If you are at all familiar with SGML 27or HTML it will be very evident. You only need to know what the tags 28are and how to use them. You can find a good resource either for this 29either 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 37The book is available online in HTML format: 38 39 http://docbook.org/ 40 41and buried in: 42 43 http://www.nwalsh.com/docbook/defguide/index.html 44 45A lot of useful stuff is at NWalsh's site in general. You may also 46want to look at: 47 48 http://www.xml.com/ 49 50The BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and 51SGML document begins with a prefix that tells where to find the file 52that describes the meaning and structure of the tags used in the rest 53of the document. 54 55For 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 60This "DOCTYPE" statement has three parts, of which we are only using 61two: 62 63o The highest level term that represents this document (in this case 64 it is "book" 65 66o 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 72FP & SYSTEM identifiers - These are names/lookups for the actual 73DTD. The FPI is a globally unique name that should, on a properly 74configured system, tell you exactly what DTD to use. The SYSTEM 75identifier gives an absolute location for the DTD. In XML these are 76supposed to be properly formatted URL's. 77 78SGML has these things called "catalogs" that are files that map FPI's 79in to actual files. A "catalog" can also be used to remap a SYSTEM 80identifier so you can say something like: "http://www.oasis.org/foo" 81is actually "/usr/local/share/xml/foo.dtd" 82 83When you use various SGML/XML tools they need to be configured to look 84at the same "catalog" files so that as you move from tool to tool they 85all refer to the same DTD for the same document. 86 87We will be spending most of our configuration time making sure our 88tools use the same "catalog" files and that we have the same DTD's 89installed on our machines. XML's requirement of the SYSTEM identifier 90over the FPI will probably lead to more problems as it does not 91guarantee that everyone is using the same DTD. 92 93I did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and 94"jade" or "openjade." 95 96You 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 101SYSTEM identifier to the recommended value of: 102 103 http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd 104 105NOTE: Under FreeBSD this is the package: 106 107 /usr/ports/textproc/docbook-xml 108 109NetBSD instructions are coming soon. 110 111With packages listed below installed under FreeBSD the "catalog" file 112that all the tools refer to at least one is in: 113 114 /usr/local/share/sgml/catalog 115 116In order for our SYSTEM identifier for the XML DocBook dtd to be found 117I create a new catalog file at the top of the XML directory created on 118FreeBSD: 119 120 /usr/local/share/xml/catalog 121 122This 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 126Then in the main "catalog" I have it include this XML catalog: 127 128 CATALOG "/usr/local/share/xml/catalog" 129 130 131On your systems you need to replace "/usr/local/share" with your 132prefix root (probably /usr/pkg under NetBSD.) 133 134NOTE: The URL used above is supposed to the be the proper one for this 135XML DocBook DTD... but there is nothing at that URL so you really do 136need the "SYSTEM" identifier mapping in your catalog (or make the 137SYSTEM identifier in your document refer to the real location of the 138file on your local system.) 139 140HOW TO VALIDATE A DOCUMENT: 141 142I use the sgmltools "nsgmls" document validator. Since we are using 143XML we need to use the XML declarations, which are installed as part 144of 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 149A convenient shell script "validate.sh" is now generated by configure 150to invoke the above command with the correct system-dependent paths. 151 152The 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 157FreeBSD package for these is: 158 159 /usr/ports/textproc/sgmltools 160 161HOW TO RENDER A DOCUMENT AS HTML or TeX: 162 163o 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 170A convenient shell script "genhtml.sh" is now generated by configure to 171invoke the above command with the correct system-dependent paths. 172 173On NetBSD there is no port for "openjade" however "jade" does still 174work. However you need to specify the "catalog" file to use for style 175sheets on the command line AND you need to have a default "catalog" 176mapping where to find various DTDs. It seems that "jade" installed out 177of the box on NetBSD does not use a globally defined "catalog" file 178for mapping PUBLIC identifiers in to SYSTEM identifiers. 179 180So you need to have a "catalog" file in your current working directory 181that 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 192So the command for jade on NetBSD will look like this: 193 194jade -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 199Furthermore, since the style sheet subset we define has in it a hard 200coded path to the style sheet is based, it is actually generated by 201configure from a .in file so that it will contain the correct 202system-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 206On NetBSD it needs to read: 207 208 <!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL> 209 210NOTE: This is usually solved by having this style sheet modification 211be installed in a system directory and have it reference the style 212sheet it is based on via a relative path. 213 214o Generate TeX documentation: 215 216openjade -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 220If you have "jade" installed instead of "openjade" then use that as 221the command. There is little difference, openjade has some bug fixes 222and is in more active development. 223 224To convert the resulting TeX file in to a DVI file you need to do: 225 226 tex "&jadetex" Bv9ARM-book.tex 227 228You can also directly generate the pdf file via: 229 230 pdftex "&pdfjadetex" Bv9ARM-book.tex 231 232The scripts "genpdf.sh" and "gendvi." have been added to simply 233generating the PDF and DVI output. These substitute the correct paths 234of NetBSD & FreeBSD. You still need to have TeX, jadeTeX, and pdfTeX 235installed and configured properly for these to work. 236 237You will need to up both the "pool_size" and "hash_extra" variables in 238your texmf.cnf file and regenerate them. See below. 239 240You can see that I am using a DSSSL style sheet for DocBook. Actually 241two different ones - one for rendering html, and one for 'print' 242media. 243 244NOTE: For HTML we are using a Nominum DSSSL style instead of the 245default one (all it does is change the chunking to the chapter level 246and makes the files end with ".html" instead of ".htm" so far.) If you 247want to use the plain jane DSSSL style sheet replace the: 248 249 -d ./nominum-docbook-html.dsl 250 251with 252 253 -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl 254 255This style sheet will attempt to reference the one above. 256 257I am currently working on fixing these up so that it works the same on 258our various systems. The main trick is knowing which DTD's and DSSSL 259stylesheets you have installed, installing the right ones, and 260configuring a CATALOG that refers to them in the same way. We will 261probably end up putting our CATALOG's in the same place and then we 262should be able to generate and validate our documents with a minimal 263number of command line arguments. 264 265When running these commands you will get a lot of messages about a 266bunch of general entities not being defined and having no default 267entity. You can ignore those for now. 268 269Also with the style sheets we have and jade as it is you will get 270messages about "xref to title" being unsupported. You can ignore these 271for now as well. 272 273=== Getting the various tools installed on FreeBSD 274(NetBSD coming soon..) 275 276o 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 284o 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 288o you may need to edit /usr/local/share/sgml/catalog and add the line: 289 290 CATALOG "/usr/local/share/sgml/openjade/catalog" 291 292o 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. 330