2426N/AThe BIND v9 ARM master document is now kept in DocBook XML format.

2426N/A

2426N/AVersion: $Id: README-SGML,v 1.6 2000/09/20 01:20:26 scanner Exp $

2426N/A

2426N/AThe entire ARM is in the single file:

2426N/A

2426N/A Bv9ARM-book.xml

2426N/A

2426N/AAll of the other documents - HTML, PDF, etc - are generated from this

2426N/Amaster source.

2426N/A

2426N/AThis file attempts to describe what tools are necessary for the

2426N/Amaintenance of this document as well as the generation of the

2426N/Aalternate formats of this document.

2426N/A

2426N/AThis file will also spend a very little time describing the XML and

2426N/ASGML headers so you can understand a bit what you may need to do to be

2426N/Aable to work with this document in any fashion other than simply

2426N/Aediting it.

2426N/A

2850N/AWe will spend almost no time on the actual tags and how to write an

2850N/AXML DocBook compliant document. If you are at all familiar with SGML

3996N/Aor HTML it will be very evident. You only need to know what the tags

2426N/Aare and how to use them. You can find a good resource either for this

4070N/Aeither online or in printed form:

2426N/A

2426N/A DocBook: The Definitive Guide

2426N/A By Norman Walsh and Leonard Muellner

4070N/A ISBN: 156592-580-7

2426N/A 1st Edition, October 1999

2426N/A Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.

2426N/A

4070N/AThe book is available online in HTML format:

4070N/A

4070N/A http://docbook.org/

2850N/A

2426N/Aand buried in:

4070N/A

3661N/A http://www.nwalsh.com/docbook/defguide/index.html

3996N/A

3996N/AA lot of useful stuff is at NWalsh's site in general. You may also

3996N/Awant to look at:

2426N/A

2426N/A http://www.xml.com/

4070N/A

4070N/AThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and

4070N/ASGML document begins with a prefix that tells where to find the file

4070N/Athat describes the meaning and structure of the tags used in the rest

2426N/Aof the document.

2426N/A

2426N/AFor our XML DocBook 4.0 based document this prefix looks like this:

2426N/A

2426N/A<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"

2426N/A "/usr/local/share/xml/dtd/docbook/docbookx.dtd">

2426N/A

2426N/AThis "DOCTYPE" statement has three parts, of which we are only using

4070N/Atwo:

4070N/A

2426N/Ao The highest level term that represents this document (in this case

it is "book"

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

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

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."

You can get the 4.0 XML DocBook DTD from:

http://www.docbook.org/xml/4.0/

(download the .zip file.) NOTE: We will eventually be changing the

SYSTEM identifier to the recommended value of:

http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd

NOTE: Under FreeBSD this is the package:

/usr/ports/textproc/docbook-xml

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:

/usr/local/share/sgml/catalog

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

FreeBSD:

/usr/local/share/xml/catalog

This file has one line:

SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"

Then in the main "catalog" I have it include this XML catalog:

CATALOG "/usr/local/share/xml/catalog"

On your systems you need to replace "/usr/local/share" with your

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:

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

Bv9ARM-book.xml

The SGML tools can be found at:

ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \

ftp://ftp.nllgg.nl/pub/SGMLtools/v2.0/source/

FreeBSD package for these is:

/usr/ports/textproc/sgmltools

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 can also directly generate the pdf file via:

pdftex "&pdfjadetex" Bv9ARM-book.tex

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'

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.

=== Getting the various tools installed on FreeBSD

(NetBSD coming soon..)

o On freebsd you need to install the following packages:

o print/teTeX

o textproc/openjade

o textproc/docbook

o textproc/docbook-xml

o textproc/dsssl-docbook-modular

o textproc/dtd-catalogs

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)

ln -s /usr/local/share/xml/entity /usr/local/share/xml/dtd/docbook/ent

o you may need to edit /usr/local/share/sgml/catalog and add the line:

CATALOG "/usr/local/share/sgml/openjade/catalog"

o add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver

file.

cd /usr/local/share/texmf/web2c/

sudo cp texmf.cnf texmf.cnf.bak

o edit the lines in texmf.cnf with these keys to these values:

main_memory = 1100000

hash_extra = 15000

pool_size = 500000

string_vacancies = 45000

max_strings = 55000

pool_free = 47500

nest_size = 500

param_size = 1500

save_size = 5000

stack_size = 1500

sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx

sudo texconfig init

o For the jadetex macros you will need I recommend you get a more

current version than what is packaged with openjade or jade.

Checkout http://www.tug.org/applications/jadetex/

Unzip the file you get from there (should be jadetex-2.20 or

newer.)

In the directory you unzip:

sudo make install

sudo texhash