/contrib/bind9/doc/arm/README-SGML

  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.