Eric Luce
c71787bd63
XML DocBook 4.0 dtd and what packages they need to install under FreeBSD at least. Also regenerate the HTML based on Andreas' changes and commit that (Really need to get html rendering working on NetBSD so they can do this themselves and immediately see the output of their changes.)
184 lines
6.3 KiB
Plaintext
184 lines
6.3 KiB
Plaintext
The BIND v9 ARM master document is now kept in DocBook XML format.
|
|
|
|
Version: $Id: README-SGML,v 1.4 2000/09/11 17:54:44 scanner Exp $
|
|
|
|
The entire ARM is in the single file:
|
|
|
|
Bv9ARM-book.xml
|
|
|
|
All of the other documents - HTML, PDF, etc - are generated from this
|
|
master source.
|
|
|
|
This file attempts to describe what tools are necessary for the
|
|
maintenance of this document as well as the generation of the
|
|
alternate formats of this document.
|
|
|
|
This file will also spend a very little time describing the XML and
|
|
SGML headers so you can understand a bit what you may need to do to be
|
|
able to work with this document in any fashion other than simply
|
|
editing it.
|
|
|
|
We will spend almost no time on the actual tags and how to write an
|
|
XML DocBook compliant document. If you are at all familiar with SGML
|
|
or HTML it will be very evident. You only need to know what the tags
|
|
are and how to use them. You can find a good resource either for this
|
|
either online or in printed form:
|
|
|
|
DocBook: The Definitive Guide
|
|
By Norman Walsh and Leonard Muellner
|
|
ISBN: 156592-580-7
|
|
1st Edition, October 1999
|
|
Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
|
|
|
|
The book is available online in HTML format:
|
|
|
|
http://docbook.org/
|
|
|
|
and buried in:
|
|
|
|
http://www.nwalsh.com/docbook/defguide/index.html
|
|
|
|
A lot of useful stuff is at NWalsh's site in general. You may also
|
|
want to look at:
|
|
|
|
http://www.xml.com/
|
|
|
|
The BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
|
|
SGML document begins with a prefix that tells where to find the file
|
|
that describes the meaning and structure of the tags used in the rest
|
|
of the document.
|
|
|
|
For our XML DocBook 4.0 based document this prefix looks like this:
|
|
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
|
|
"/usr/local/share/xml/dtd/docbook/docbookx.dtd">
|
|
|
|
This "DOCTYPE" statement has three parts, of which we are only using
|
|
two:
|
|
|
|
o 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.
|
|
|
|
As soon as I figure out the proper "catalog" files to change and how
|
|
to change them for this to do the proper re-mapping.
|
|
|
|
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 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.
|