330 lines
12 KiB
Plaintext
330 lines
12 KiB
Plaintext
Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
|
|
Copyright (C) 2000, 2001 Internet Software Consortium.
|
|
See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
|
|
|
|
The BIND v9 ARM master document is now kept in DocBook XML format.
|
|
|
|
Version: $Id: README-SGML,v 1.17 2004/03/05 05:04:43 marka 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.
|
|
|
|
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
|
|
|
|
A convenient shell script "validate.sh" is now generated by configure
|
|
to invoke the above command with the correct system-dependent paths.
|
|
|
|
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:
|
|
|
|
openjade -v -d ./nominum-docbook-html.dsl \
|
|
-t sgml \
|
|
/usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
|
|
Bv9ARM-book.xml
|
|
|
|
A convenient shell script "genhtml.sh" is now generated by configure to
|
|
invoke the above command with the correct system-dependent paths.
|
|
|
|
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!)
|
|
|
|
CATALOG "/usr/pkg/share/sgml/iso8879/catalog"
|
|
CATALOG "/usr/pkg/share/sgml/docbook/2.4.1/catalog"
|
|
CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog"
|
|
CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog"
|
|
CATALOG "/usr/pkg/share/sgml/jade/catalog"
|
|
CATALOG "/usr/local/share/xml/catalog"
|
|
|
|
(These would all be "/usr/local" on FreeBSD)
|
|
|
|
So the command for jade on NetBSD will look like this:
|
|
|
|
jade -v -c /usr/pkg/share/sgml/catalog -t sgml \
|
|
-d ./nominum-docbook-html.dsl \
|
|
/usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
|
|
./Bv9ARM-book.xml
|
|
|
|
Furthermore, since the style sheet subset we define has in it a hard
|
|
coded path to the style sheet is based, it is actually generated by
|
|
configure from a .in file so that it will contain the correct
|
|
system-dependent path: where on FreeBSD the second line reads:
|
|
|
|
<!ENTITY dbstyle SYSTEM "/usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
|
|
|
|
On NetBSD it needs to read:
|
|
|
|
<!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
|
|
|
|
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:
|
|
|
|
openjade -d ./nominum-docbook-print.dsl -t tex -v \
|
|
/usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
|
|
Bv9ARM-book.xml
|
|
|
|
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:
|
|
|
|
tex "&jadetex" Bv9ARM-book.tex
|
|
|
|
You can also directly generate the pdf file via:
|
|
|
|
pdftex "&pdfjadetex" Bv9ARM-book.tex
|
|
|
|
The scripts "genpdf.sh" and "gendvi." have been added to simply
|
|
generating the PDF and DVI output. These substitute the correct paths
|
|
of NetBSD & FreeBSD. You still need to have TeX, jadeTeX, and pdfTeX
|
|
installed and configured properly for these to work.
|
|
|
|
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
|
|
sudo texhash
|
|
|
|
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
|
|
|
|
NOTE: In the most uptodate "ports" for FreeBSD, jadetext is 2.20+
|
|
so on this platform you should be set as of 2001.01.08.
|