f2c814353bd1de305b5341554c803a85f88d6b72Andreas GustafssonThe BIND v9 ARM master document is now kept in DocBook XML format.

0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews

40f53fa8d9c6a4fc38c0014495e7a42b08f52481David LawrenceThe entire ARM is in the single file:

0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews

0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews Bv9ARM-book.xml

0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews

f2c814353bd1de305b5341554c803a85f88d6b72Andreas GustafssonAll of the other documents - HTML, PDF, etc - are generated from this

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafssonmaster source.

e6ada020f5003124613f4f71c6fc3f5d32c8d979Automatic Updater

821644d49b73b49f2abc5463bc53a3132f612478Mark AndrewsThis file attempts to describe what tools are necessary for the

821644d49b73b49f2abc5463bc53a3132f612478Mark Andrewsmaintenance of this document as well as the generation of the

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafssonalternate formats of this document.

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafsson

67adc03ef81fb610f8df093b17f55275ee816754Evan HuntThis file will also spend a very little time describing the XML and

67adc03ef81fb610f8df093b17f55275ee816754Evan HuntSGML headers so you can understand a bit what you may need to do to be

67adc03ef81fb610f8df093b17f55275ee816754Evan Huntable to work with this document in any fashion other than simply

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafssonediting it.

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafsson

f2c814353bd1de305b5341554c803a85f88d6b72Andreas GustafssonWe will spend almost no time on the actual tags and how to write an

5a77e9620a0b2f7417469c98be374de49d0eccc6Andreas GustafssonXML DocBook compliant document. If you are at all familiar with SGML

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafssonor HTML it will be very evident. You only need to know what the tags

429e23d2f56d28d86439f75c13cda2b4ac5ab67bMark Andrewsare and how to use them. You can find a good resource either for this

40d0f115a64595aa83cfe0b760587d3d1efa0385Tatuya JINMEI 神明達哉either online or in printed form:

40d0f115a64595aa83cfe0b760587d3d1efa0385Tatuya JINMEI 神明達哉

40d0f115a64595aa83cfe0b760587d3d1efa0385Tatuya JINMEI 神明達哉 DocBook: The Definitive Guide

40d0f115a64595aa83cfe0b760587d3d1efa0385Tatuya JINMEI 神明達哉 By Norman Walsh and Leonard Muellner

40d0f115a64595aa83cfe0b760587d3d1efa0385Tatuya JINMEI 神明達哉 ISBN: 156592-580-7

0618287859d99c2fc69790df28500fb37324d43dEvan Hunt 1st Edition, October 1999

4ca7391e640bd4f0abb31508019d3bd62819fa8eMark Andrews Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews

f2c814353bd1de305b5341554c803a85f88d6b72Andreas GustafssonThe book is available online in HTML format:

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafsson

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews http://docbook.org/

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrewsand buried in:

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews http://www.nwalsh.com/docbook/defguide/index.html

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark AndrewsA lot of useful stuff is at NWalsh's site in general. You may also

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrewswant to look at:

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews http://www.xml.com/

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark Andrews

75d747e1c5a30d6ef6c6238c6e27baa11d6f3bf6Mark AndrewsThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and

dd1bcab25cf91eccb77060023d94a306411f7f14Mark AndrewsSGML document begins with a prefix that tells where to find the file

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrewsthat describes the meaning and structure of the tags used in the rest

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrewsof the document.

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews

dd1bcab25cf91eccb77060023d94a306411f7f14Mark AndrewsFor our XML DocBook 4.0 based document this prefix looks like this:

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafsson<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"

f2c814353bd1de305b5341554c803a85f88d6b72Andreas Gustafsson "/usr/local/share/xml/dtd/docbook/docbookx.dtd">

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews

dd1bcab25cf91eccb77060023d94a306411f7f14Mark AndrewsThis "DOCTYPE" statement has three parts, of which we are only using

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrewstwo:

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrewso The highest level term that represents this document (in this case

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews it is "book"

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrewso The identifier that tells us which DTD to use. This identifier has

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews two parts, the "Formal Public Identifier" (or FPI) and the system

dd1bcab25cf91eccb77060023d94a306411f7f14Mark Andrews identifier. In SGML you can have either a FPI or a SYSTEM identifier

but you have to have at least one of them. In XML you have to have a

SYSTEM identifier.

FP & SYSTEM identifiers - These are names/lookups for the actual

DTD. The FPI is a globally unique name that should, on a properly

configured system, tell you exactly what DTD to use. The SYSTEM

identifier gives an absolute location for the DTD. In XML these are

supposed to be properly formatted URL's.

SGML has these things called "catalogs" that are files that map FPI's

in to actual files. A "catalog" can also be used to remap a SYSTEM

identifier so you can say something like: "http://www.oasis.org/foo"

is actually "/usr/local/share/xml/foo.dtd"

When you use various SGML/XML tools they need to be configured to look

at the same "catalog" files so that as you move from tool to tool they

all refer to the same DTD for the same document.

We will be spending most of our configuration time making sure our

tools use the same "catalog" files and that we have the same DTD's

installed on our machines. XML's requirement of the SYSTEM identifier

over the FPI will probably lead to more problems as it does not

guarantee that everyone is using the same DTD.

I did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and

"jade" or "openjade."

HOW TO VALIDATE A DOCUMENT:

I use the sgmltools "nsgmls" document validator. Since we are using

XML we need to use the XML declarations, which are installed as part

of the modular DSSL style sheets:

nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \

Bv9ARM-book.xml

HOW TO RENDER A DOCUMENT AS HTML or TeX:

o Generate html doc with:

jade -d ./nominum-docbook-html.dsl \

-t sgml \

-v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \

Bv9ARM-book.xml

o Generate TeX documentation:

jade -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \

-t tex \

-v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \

Bv9ARM-book.xml

To convert the resulting TeX file in to a DVI file you need to do:

tex "&jadetex" Bv9ARM-book.tex

You will need to up both the "pool_size" and "hash_extra" variables in

your texmf.cnf file and regenerate them. Stay tuned for instructions

here.

You can see that I am using a DSSSL style sheet for DocBook. Actually

two different ones - one for rendering html, and one for 'print'

media.

NOTE: For HTML we are using a Nominum DSSSL style instead of the

default one (all it does is change the chunking to the chapter level

and makes the files end with ".html" instead of ".htm" so far.) If you

want to use the plain jane DSSSL style sheet replace the:

-d ./nominum-docbook-html.dsl

with

-d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl

This style sheet will attempt to reference the one above.

I am currently working on fixing these up so that it works the same on

our various systems. The main trick is knowing which DTD's and DSSSL

stylesheets you have installed, installing the right ones, and

configuring a CATALOG that refers to them in the same way. We will

probably end up putting our CATALOG's in the same place and then we

should be able to generate and validate our documents with a minimal

number of command line arguments.

When running these commands you will get a lot of messages about a

bunch of general entities not being defined and having no default

entity. You can ignore those for now.

Also with the style sheets we have and jade as it is you will get

messages about "xref to title" being unsupported. You can ignore these

for now as well.