ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity
Files
dc2e45d08d73fdaefd92dbfa4d69b4d3f3b0f249
bind9/doc/arm/README-SGML
Eric Luce 9b26804b58 Regenerated the HTML version of the ARM again. 
Added more text to the "README-SGML" document on how to set up
environment on FreeBSD. Still need to do NetBSD.
2000-09-18 17:06:15 +00:00

243 lines
8.0 KiB
Plaintext
Raw Blame History

The BIND v9 ARM master document is now kept in DocBook XML format.
Version: $Id: README-SGML,v 1.5 2000/09/18 17:06:15 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 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
View Git Blame Copy Permalink