README-SGML revision 499b34cea04a46823d003d4c0520c8b03e8513cb
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCopyright (C) 2000, 2001 Internet Software Consortium.
11e9368a226272085c337e9e74b79808c16fbdbaTinderbox UserSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe BIND v9 ARM master document is now kept in DocBook XML format.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinVersion: $Id: README-SGML,v 1.13 2001/01/09 21:46:35 bwelling Exp $
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe entire ARM is in the single file:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAll of the other documents - HTML, PDF, etc - are generated from this
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinmaster source.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThis file attempts to describe what tools are necessary for the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinmaintenance of this document as well as the generation of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinalternate formats of this document.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThis file will also spend a very little time describing the XML and
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox UserSGML headers so you can understand a bit what you may need to do to be
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userable to work with this document in any fashion other than simply
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinWe will spend almost no time on the actual tags and how to write an
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox UserXML DocBook compliant document. If you are at all familiar with SGML
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinor HTML it will be very evident. You only need to know what the tags
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinare and how to use them. You can find a good resource either for this
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeineither online or in printed form:
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User DocBook: The Definitive Guide
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein By Norman Walsh and Leonard Muellner
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein ISBN: 156592-580-7
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 1st Edition, October 1999
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThe book is available online in HTML format:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinand buried in:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User http://www.nwalsh.com/docbook/defguide/index.html
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntA lot of useful stuff is at NWalsh's site in general. You may also
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntwant to look at:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntSGML document begins with a prefix that tells where to find the file
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userthat describes the meaning and structure of the tags used in the rest
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntof the document.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntFor our XML DocBook 4.0 based document this prefix looks like this:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis "DOCTYPE" statement has three parts, of which we are only using
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usero The highest level term that represents this document (in this case
f9ce6280cec79deb16ff6d9807aa493ff23e10d9Tinderbox Usero The identifier that tells us which DTD to use. This identifier has
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt two parts, the "Formal Public Identifier" (or FPI) and the system
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt identifier. In SGML you can have either a FPI or a SYSTEM identifier
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User but you have to have at least one of them. In XML you have to have a
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox User SYSTEM identifier.
e285c11870c6263cd79b418e104c7eb3e2d96952Tinderbox UserFP & SYSTEM identifiers - These are names/lookups for the actual
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox UserDTD. The FPI is a globally unique name that should, on a properly
46472a450e043434d78fa18edc73bca8c47f3981Tinderbox Userconfigured system, tell you exactly what DTD to use. The SYSTEM
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntidentifier gives an absolute location for the DTD. In XML these are
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usersupposed to be properly formatted URL's.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntSGML has these things called "catalogs" that are files that map FPI's
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntin to actual files. A "catalog" can also be used to remap a SYSTEM
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Useridentifier so you can say something like: "http://www.oasis.org/foo"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntWhen you use various SGML/XML tools they need to be configured to look
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntat the same "catalog" files so that as you move from tool to tool they
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntall refer to the same DTD for the same document.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserWe will be spending most of our configuration time making sure our
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usertools use the same "catalog" files and that we have the same DTD's
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntinstalled on our machines. XML's requirement of the SYSTEM identifier
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userover the FPI will probably lead to more problems as it does not
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userguarantee that everyone is using the same DTD.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserI did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User"jade" or "openjade."
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserYou can get the 4.0 XML DocBook DTD from:
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User(download the .zip file.) NOTE: We will eventually be changing the
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserSYSTEM identifier to the recommended value of:
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox User http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserNOTE: Under FreeBSD this is the package:
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserNetBSD instructions are coming soon.
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox UserWith packages listed below installed under FreeBSD the "catalog" file
8a48b6b9b6fa8486f24b22d1972b2b6ebb36a4a4Tinderbox Userthat all the tools refer to at least one is in:
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserIn order for our SYSTEM identifier for the XML DocBook dtd to be found
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserI create a new catalog file at the top of the XML directory created on
e2f974003e61b59321a99f01a6f43576d9b76231Tinderbox UserThis file has one line:
576bce9d7331498ca5453f8743f94ed8e2e59d9fTinderbox User SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"
6b7cba2b10d6cb5363d94b434b0d22ecfb33a6f3Tinderbox UserThen in the main "catalog" I have it include this XML catalog:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserOn your systems you need to replace "/usr/local/share" with your
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userprefix root (probably /usr/pkg under NetBSD.)
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserNOTE: The URL used above is supposed to the be the proper one for this
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserXML DocBook DTD... but there is nothing at that URL so you really do
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userneed the "SYSTEM" identifier mapping in your catalog (or make the
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserSYSTEM identifier in your document refer to the real location of the
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userfile on your local system.)
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserHOW TO VALIDATE A DOCUMENT:
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserI use the sgmltools "nsgmls" document validator. Since we are using
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserXML we need to use the XML declarations, which are installed as part
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userof the modular DSSL style sheets:
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserA convenient shell script "validate.sh" is now generated by configure
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox Userto invoke the above command with the correct system-dependent paths.
1ffe3f29e3cd0d8355500e9fd34de918ad9b4a01Tinderbox UserThe SGML tools can be found at:
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox User ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User ftp://ftp.nllgg.nl/pub/SGMLtools/v2.0/source/
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox UserFreeBSD package for these is:
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserHOW TO RENDER A DOCUMENT AS HTML or TeX:
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Usero Generate html doc with:
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox User openjade -v -d ./nominum-docbook-html.dsl \
3ba1f79ade054aa6a0dc5032502bcdcf357cd7bdTinderbox User /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntA convenient shell script "genhtml.sh" is now generated by configure to
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntinvoke the above command with the correct system-dependent paths.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntOn NetBSD there is no port for "openjade" however "jade" does still
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntwork. However you need to specify the "catalog" file to use for style
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usersheets on the command line AND you need to have a default "catalog"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntmapping where to find various DTDs. It seems that "jade" installed out
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntof the box on NetBSD does not use a globally defined "catalog" file
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntfor mapping PUBLIC identifiers in to SYSTEM identifiers.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntSo you need to have a "catalog" file in your current working directory
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntthat has in it this: (these are probably more entries than you need!)
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User CATALOG "/usr/pkg/share/sgml/iso8879/catalog"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt CATALOG "/usr/pkg/share/sgml/docbook/2.4.1/catalog"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User(These would all be "/usr/local" on FreeBSD)
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserSo the command for jade on NetBSD will look like this:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntjade -v -c /usr/pkg/share/sgml/catalog -t sgml \
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntFurthermore, since the style sheet subset we define has in it a hard
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntcoded path to the style sheet is based, it is actually generated by
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userconfigure from a .in file so that it will contain the correct
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usersystem-dependent path: where on FreeBSD the second line reads:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <!ENTITY dbstyle SYSTEM "/usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntOn NetBSD it needs to read:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserNOTE: This is usually solved by having this style sheet modification
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userbe installed in a system directory and have it reference the style
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntsheet it is based on via a relative path.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunto Generate TeX documentation:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Useropenjade -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User -v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntIf you have "jade" installed instead of "openjade" then use that as
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userthe command. There is little difference, openjade has some bug fixes
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntand is in more active development.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntTo convert the resulting TeX file in to a DVI file you need to do:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt tex "&jadetex" Bv9ARM-book.tex
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntYou can also directly generate the pdf file via:
9d557856c2a19ec95ee73245f60a92f8675cf5baTinderbox User pdftex "&pdfjadetex" Bv9ARM-book.tex
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntYou will need to up both the "pool_size" and "hash_extra" variables in
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntyour texmf.cnf file and regenerate them. See below.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserYou can see that I am using a DSSSL style sheet for DocBook. Actually
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunttwo different ones - one for rendering html, and one for 'print'
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntNOTE: For HTML we are using a Nominum DSSSL style instead of the
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox Userdefault one (all it does is change the chunking to the chapter level
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox Userand makes the files end with ".html" instead of ".htm" so far.) If you
76cf91b5df7a1bc450afcb9ce7585c61bb87de68Tinderbox Userwant to use the plain jane DSSSL style sheet replace the:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserThis style sheet will attempt to reference the one above.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntI am currently working on fixing these up so that it works the same on
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntour various systems. The main trick is knowing which DTD's and DSSSL
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntstylesheets you have installed, installing the right ones, and
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntconfiguring a CATALOG that refers to them in the same way. We will
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntprobably end up putting our CATALOG's in the same place and then we
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntshould be able to generate and validate our documents with a minimal
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Usernumber of command line arguments.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserWhen running these commands you will get a lot of messages about a
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userbunch of general entities not being defined and having no default
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userentity. You can ignore those for now.
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox UserAlso with the style sheets we have and jade as it is you will get
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Usermessages about "xref to title" being unsupported. You can ignore these
a1ff871f78b7d907d6fc3a382beea2a640fe8423Tinderbox Userfor now as well.
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User=== Getting the various tools installed on FreeBSD
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User(NetBSD coming soon..)
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox Usero On freebsd you need to install the following packages:
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox Usero on freebsd you need to make some entities visible to the docbook xml
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User dtd by making a symlink (can probably be done with a catalog too)
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User ln -s /usr/local/share/xml/entity /usr/local/share/xml/dtd/docbook/ent
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox Usero you may need to edit /usr/local/share/sgml/catalog and add the line:
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User CATALOG "/usr/local/share/sgml/openjade/catalog"
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox Usero add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User o edit the lines in texmf.cnf with these keys to these values:
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User main_memory = 1100000
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User hash_extra = 15000
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User pool_size = 500000
3241ddcf9354c5ab50f4df5a656e72a5c68e172bTinderbox User string_vacancies = 45000
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User max_strings = 55000
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt pool_free = 47500
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt nest_size = 500
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt param_size = 1500
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt save_size = 5000
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt stack_size = 1500
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User sudo texconfig init
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt o For the jadetex macros you will need I recommend you get a more
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt current version than what is packaged with openjade or jade.
e2b184f84e846bbcb764b6f0aef5dcd583d3d7a1Tinderbox User Unzip the file you get from there (should be jadetex-2.20 or
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User In the directory you unzip:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt sudo make install
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt sudo texhash