369N/AThe BIND v9 ARM master document is now kept in DocBook XML format.
369N/AVersion: $Id: README-SGML,v 1.8 2000/11/03 18:25:09 gson Exp $
369N/AThe entire ARM is in the single file:
369N/AAll of the other documents - HTML, PDF, etc - are generated from this
369N/AThis file attempts to describe what tools are necessary for the
369N/Amaintenance of this document as well as the generation of the
369N/Aalternate formats of this document.
369N/AThis file will also spend a very little time describing the XML and
369N/ASGML headers so you can understand a bit what you may need to do to be
369N/Aable to work with this document in any fashion other than simply
3661N/AWe will spend almost no time on the actual tags and how to write an
369N/AXML DocBook compliant document. If you are at all familiar with SGML
3661N/Aor HTML it will be very evident. You only need to know what the tags
3661N/Aare and how to use them. You can find a good resource either for this
3661N/Aeither online or in printed form:
3661N/A DocBook: The Definitive Guide
3661N/A By Norman Walsh and Leonard Muellner
3661N/A Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
3661N/AThe book is available online in HTML format:
369N/AA lot of useful stuff is at NWalsh's site in general. You may also
369N/AThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
618N/ASGML document begins with a prefix that tells where to find the file
1273N/Athat describes the meaning and structure of the tags used in the rest
369N/AFor our XML DocBook 4.0 based document this prefix looks like this:
1574N/A<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
1574N/AThis "DOCTYPE" statement has three parts, of which we are only using
369N/Ao The highest level term that represents this document (in this case
369N/Ao The identifier that tells us which DTD to use. This identifier has
369N/A two parts, the "Formal Public Identifier" (or FPI) and the system
369N/A identifier. In SGML you can have either a FPI or a SYSTEM identifier
369N/A but you have to have at least one of them. In XML you have to have a
369N/ADTD. The FPI is a globally unique name that should, on a properly
369N/Aconfigured system, tell you exactly what DTD to use. The SYSTEM
369N/Aidentifier gives an absolute location for the DTD. In XML these are
369N/Asupposed to be properly formatted URL's.
369N/ASGML has these things called "catalogs" that are files that map FPI's
369N/Ain to actual files. A "catalog" can also be used to remap a SYSTEM
369N/AWhen you use various
SGML/XML tools they need to be configured to look
369N/Aat the same "catalog" files so that as you move from tool to tool they
369N/Aall refer to the same DTD for the same document.
369N/AWe will be spending most of our configuration time making sure our
369N/Atools use the same "catalog" files and that we have the same DTD's
369N/Ainstalled on our machines. XML's requirement of the SYSTEM identifier
369N/Aover the FPI will probably lead to more problems as it does not
369N/Aguarantee that everyone is using the same DTD.
369N/AI did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
369N/AYou can get the 4.0 XML DocBook DTD from:
3996N/A(download the .zip file.) NOTE: We will eventually be changing the
3996N/ASYSTEM identifier to the recommended value of:
3996N/ANOTE: Under FreeBSD this is the package:
NetBSD instructions are coming soon.
With packages listed below installed under FreeBSD the "catalog" file
that all the tools refer to at least one is in:
In order for our SYSTEM identifier for the XML DocBook dtd to be found
I create a new catalog file at the top of the XML directory created on
Then in the main "catalog" I have it include this XML catalog:
prefix root (probably
/usr/pkg under NetBSD.)
NOTE: The URL used above is supposed to the be the proper one for this
XML DocBook DTD.. but there is nothing at that URL so you really do
need the "SYSTEM" identifier mapping in your catalog (or make the
SYSTEM identifier in your document refer to the real location of the
file on your local system.)
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:
The SGML tools can be found at:
FreeBSD package for these is:
HOW TO RENDER A DOCUMENT AS HTML or TeX:
o Generate html doc with:
On NetBSD there is no port for "openjade" however "jade" does still
work. However you need to specify the "catalog" file to use for style
sheets on the command line AND you need to have a default "catalog"
mapping where to find various DTDs. It seems that "jade" installed out
of the box on NetBSD does not use a globally defined "catalog" file
for mapping PUBLIC identifiers in to SYSTEM identifiers.
So you need to have a "catalog" file in your current working directory
that has in it this: (these are probably more entries than you need!)
So the command for jade on NetBSD will look like this:
Furthermore, since the style sheet subset we define has in it a hard
coded path to the style sheet is based on you need to modify the
second line of this file (this needs to be done via configure so we
are not tripping over each other.)
Where on FreeBSD the second line reads:
On NetBSD it needs to read:
NOTE: This is usually solved by having this style sheet modification
be installed in a system directory and have it reference the style
sheet it is based on via a relative path.
o Generate TeX documentation:
If you have "jade" installed instead of "openjade" then use that as
the command. There is little difference, openjade has some bug fixes
and is in more active development.
To convert the resulting TeX file in to a DVI file you need to do:
You can also directly generate the pdf file via:
You will need to up both the "pool_size" and "hash_extra" variables in
your
texmf.cnf file and regenerate them. See below.
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'
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:
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
=== Getting the various tools installed on FreeBSD
o On freebsd you need to install the following packages:
o on freebsd you need to make some entities visible to the docbook xml
dtd by making a symlink (can probably be done with a catalog too)
o add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
o edit the lines in
texmf.cnf with these keys to these values:
sudo tex -ini -progname=hugelatex -fmt=hugelatex
latex.ltx o For the jadetex macros you will need I recommend you get a more
current version than what is packaged with openjade or jade.
Unzip the file you get from there (should be jadetex-2.20 or
In the directory you unzip: