README-SGML revision fafd1d771905532e8dc3efa2ce90ce4c9e74af61
45312f52ff3a3d4c137447be4c7556500c2f8bf2Timo SirainenThe BIND v9 ARM master document is now kept in DocBook XML format.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenVersion: $Id: README-SGML,v 1.6 2000/09/20 01:20:26 scanner Exp $
16f816d3f3c32ae3351834253f52ddd0212bcbf3Timo SirainenThe entire ARM is in the single file:
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenAll of the other documents - HTML, PDF, etc - are generated from this
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainenmaster source.
b346610430690398b8c840006004a2df4aa8ce92Timo SirainenThis file attempts to describe what tools are necessary for the
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainenmaintenance of this document as well as the generation of the
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainenalternate formats of this document.
48136ae5a0eb49daa44e343553f3688a500307e2Timo SirainenThis file will also spend a very little time describing the XML and
2674b4f0cf8f3c203d8e56b29735f5e267038dafTimo SirainenSGML headers so you can understand a bit what you may need to do to be
48136ae5a0eb49daa44e343553f3688a500307e2Timo Sirainenable to work with this document in any fashion other than simply
48136ae5a0eb49daa44e343553f3688a500307e2Timo SirainenWe will spend almost no time on the actual tags and how to write an
e376693bfa3985232c41df99c7010fca22612c89Timo SirainenXML DocBook compliant document. If you are at all familiar with SGML
e376693bfa3985232c41df99c7010fca22612c89Timo Sirainenor HTML it will be very evident. You only need to know what the tags
e376693bfa3985232c41df99c7010fca22612c89Timo Sirainenare and how to use them. You can find a good resource either for this
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo Siraineneither online or in printed form:
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo Sirainen DocBook: The Definitive Guide
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo Sirainen By Norman Walsh and Leonard Muellner
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo Sirainen ISBN: 156592-580-7
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo Sirainen 1st Edition, October 1999
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo Sirainen Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
0c909e3461607eadcd66f4eac69b7f34e37fccf1Timo SirainenThe book is available online in HTML format:
e376693bfa3985232c41df99c7010fca22612c89Timo Sirainenand buried in:
09c3a491f4f6ccebe290c7709bdc0d79a187610bTimo Sirainen http://www.nwalsh.com/docbook/defguide/index.html
09c3a491f4f6ccebe290c7709bdc0d79a187610bTimo SirainenA lot of useful stuff is at NWalsh's site in general. You may also
09c3a491f4f6ccebe290c7709bdc0d79a187610bTimo Sirainenwant to look at:
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo SirainenThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo SirainenSGML document begins with a prefix that tells where to find the file
b346610430690398b8c840006004a2df4aa8ce92Timo Sirainenthat describes the meaning and structure of the tags used in the rest
b346610430690398b8c840006004a2df4aa8ce92Timo Sirainenof the document.
741d705983e10046f07ef372b760bcdd169b068aTimo SirainenFor our XML DocBook 4.0 based document this prefix looks like this:
b346610430690398b8c840006004a2df4aa8ce92Timo Sirainen<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
b346610430690398b8c840006004a2df4aa8ce92Timo Sirainen "/usr/local/share/xml/dtd/docbook/docbookx.dtd">
b346610430690398b8c840006004a2df4aa8ce92Timo SirainenThis "DOCTYPE" statement has three parts, of which we are only using
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Siraineno The highest level term that represents this document (in this case
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Siraineno The identifier that tells us which DTD to use. This identifier has
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen two parts, the "Formal Public Identifier" (or FPI) and the system
7212243efb0d8fa1cd8b2e37b7498323540b9e97Timo Sirainen identifier. In SGML you can have either a FPI or a SYSTEM identifier
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen but you have to have at least one of them. In XML you have to have a
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen SYSTEM identifier.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenFP & SYSTEM identifiers - These are names/lookups for the actual
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenDTD. The FPI is a globally unique name that should, on a properly
d1baa8c6f97cdb1b3c2c44a73cc21f9dfc7a963fTimo Sirainenconfigured system, tell you exactly what DTD to use. The SYSTEM
d1baa8c6f97cdb1b3c2c44a73cc21f9dfc7a963fTimo Sirainenidentifier gives an absolute location for the DTD. In XML these are
d1baa8c6f97cdb1b3c2c44a73cc21f9dfc7a963fTimo Sirainensupposed to be properly formatted URL's.
d1baa8c6f97cdb1b3c2c44a73cc21f9dfc7a963fTimo SirainenSGML has these things called "catalogs" that are files that map FPI's
7212243efb0d8fa1cd8b2e37b7498323540b9e97Timo Sirainenin to actual files. A "catalog" can also be used to remap a SYSTEM
7212243efb0d8fa1cd8b2e37b7498323540b9e97Timo Sirainenidentifier so you can say something like: "http://www.oasis.org/foo"
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenWhen you use various SGML/XML tools they need to be configured to look
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenat the same "catalog" files so that as you move from tool to tool they
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenall refer to the same DTD for the same document.
7212243efb0d8fa1cd8b2e37b7498323540b9e97Timo SirainenWe will be spending most of our configuration time making sure our
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainentools use the same "catalog" files and that we have the same DTD's
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Siraineninstalled on our machines. XML's requirement of the SYSTEM identifier
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenover the FPI will probably lead to more problems as it does not
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenguarantee that everyone is using the same DTD.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenI did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
7212243efb0d8fa1cd8b2e37b7498323540b9e97Timo Sirainen"jade" or "openjade."
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenYou can get the 4.0 XML DocBook DTD from:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen(download the .zip file.) NOTE: We will eventually be changing the
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenSYSTEM identifier to the recommended value of:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenNOTE: Under FreeBSD this is the package:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenNetBSD instructions are coming soon.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenWith packages listed below installed under FreeBSD the "catalog" file
8e7da21696c9f8a6d5e601243fb6172ec85d47b2Timo Sirainenthat all the tools refer to at least one is in:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenIn order for our SYSTEM identifier for the XML DocBook dtd to be found
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenI create a new catalog file at the top of the XML directory created on
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenThis file has one line:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"
e6f0cbdb1eb604f21a65cd45072febe678187054Timo SirainenThen in the main "catalog" I have it include this XML catalog:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenOn your systems you need to replace "/usr/local/share" with your
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenprefix root (probably /usr/pkg under NetBSD.)
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenNOTE: The URL used above is supposed to the be the proper one for this
8d80659e504ffb34bb0c6a633184fece35751b18Timo SirainenXML DocBook DTD.. but there is nothing at that URL so you really do
40a5aeebf6b4858b93f0ddff0bf12fba769cf903Timo Sirainenneed the "SYSTEM" identifier mapping in your catalog (or make the
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenSYSTEM identifier in your document refer to the real location of the
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenfile on your local system.)
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenHOW TO VALIDATE A DOCUMENT:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenI use the sgmltools "nsgmls" document validator. Since we are using
c5794838af9995f50bfecb06a3cd4f9a0ac77858Timo SirainenXML we need to use the XML declarations, which are installed as part
8d80659e504ffb34bb0c6a633184fece35751b18Timo Sirainenof the modular DSSL style sheets:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainennsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenThe SGML tools can be found at:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenFreeBSD package for these is:
5ada3f57a970f226eb29956d30f66afc3537200dTimo SirainenHOW TO RENDER A DOCUMENT AS HTML or TeX:
a94936bafd127680184da114c6a177b37ff656e5Timo Siraineno Generate html doc with:
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen -v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
439942f89a77180719644e7af3752a8329259eb9Timo Siraineno Generate TeX documentation:
439942f89a77180719644e7af3752a8329259eb9Timo Sirainenjade -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen -v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenTo convert the resulting TeX file in to a DVI file you need to do:
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo SirainenYou can also directly generate the pdf file via:
5d1833b98fa85d8061626aa986f38dcbcd70553eTimo Sirainen pdftex "&pdfjadetex" Bv9ARM-book.tex
5d1833b98fa85d8061626aa986f38dcbcd70553eTimo SirainenYou will need to up both the "pool_size" and "hash_extra" variables in
5d1833b98fa85d8061626aa986f38dcbcd70553eTimo Sirainenyour texmf.cnf file and regenerate them. See below.
5d1833b98fa85d8061626aa986f38dcbcd70553eTimo SirainenYou can see that I am using a DSSSL style sheet for DocBook. Actually
5d1833b98fa85d8061626aa986f38dcbcd70553eTimo Sirainentwo different ones - one for rendering html, and one for 'print'
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenNOTE: For HTML we are using a Nominum DSSSL style instead of the
1f68b6db9b8d02b0f4116e42ac82c4aac5579574Timo Sirainendefault one (all it does is change the chunking to the chapter level
1f68b6db9b8d02b0f4116e42ac82c4aac5579574Timo Sirainenand makes the files end with ".html" instead of ".htm" so far.) If you
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainenwant to use the plain jane DSSSL style sheet replace the:
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo SirainenThis style sheet will attempt to reference the one above.
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo SirainenI am currently working on fixing these up so that it works the same on
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainenour various systems. The main trick is knowing which DTD's and DSSSL
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainenstylesheets you have installed, installing the right ones, and
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainenconfiguring a CATALOG that refers to them in the same way. We will
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainenprobably end up putting our CATALOG's in the same place and then we
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainenshould be able to generate and validate our documents with a minimal
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainennumber of command line arguments.
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo SirainenWhen running these commands you will get a lot of messages about a
9404a7b90dcb80d31bd37ee2493f03751acdb1bdTimo Sirainenbunch of general entities not being defined and having no default
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainenentity. You can ignore those for now.
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo SirainenAlso with the style sheets we have and jade as it is you will get
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainenmessages about "xref to title" being unsupported. You can ignore these
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainenfor now as well.
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen=== Getting the various tools installed on FreeBSD
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen(NetBSD coming soon..)
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Siraineno On freebsd you need to install the following packages:
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Siraineno on freebsd you need to make some entities visible to the docbook xml
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen dtd by making a symlink (can probably be done with a catalog too)
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen ln -s /usr/local/share/xml/entity /usr/local/share/xml/dtd/docbook/ent
5e40ed3f0a2c2acddc9b8eab59670c7a850114c5Timo Siraineno you may need to edit /usr/local/share/sgml/catalog and add the line:
a94936bafd127680184da114c6a177b37ff656e5Timo Sirainen CATALOG "/usr/local/share/sgml/openjade/catalog"
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Siraineno add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen o edit the lines in texmf.cnf with these keys to these values:
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen main_memory = 1100000
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen hash_extra = 15000
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen pool_size = 500000
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen string_vacancies = 45000
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen max_strings = 55000
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen pool_free = 47500
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen nest_size = 500
db87d16551d1081ada01f787ea21aa3ed1402c31Timo Sirainen param_size = 1500
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen save_size = 5000
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen stack_size = 1500
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen sudo texconfig init
439942f89a77180719644e7af3752a8329259eb9Timo Sirainen o For the jadetex macros you will need I recommend you get a more
439942f89a77180719644e7af3752a8329259eb9Timo Sirainen current version than what is packaged with openjade or jade.
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen Checkout http://www.tug.org/applications/jadetex/
46c31f64b9f0949f00b7819f45b22f2d64b2ea27Timo Sirainen Unzip the file you get from there (should be jadetex-2.20 or
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen In the directory you unzip:
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen sudo make install