README-SGML revision dafcb997e390efa4423883dafd100c975c4095d6
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseCopyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseCopyright (C) 2000, 2001 Internet Software Consortium.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThe BIND v9 ARM master document is now kept in DocBook XML format.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseVersion: $Id: README-SGML,v 1.17 2004/03/05 05:04:43 marka Exp $
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThe entire ARM is in the single file:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseAll of the other documents - HTML, PDF, etc - are generated from this
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosemaster source.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThis file attempts to describe what tools are necessary for the
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosemaintenance of this document as well as the generation of the
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosealternate formats of this document.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThis file will also spend a very little time describing the XML and
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSGML headers so you can understand a bit what you may need to do to be
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseable to work with this document in any fashion other than simply
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseWe will spend almost no time on the actual tags and how to write an
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseXML DocBook compliant document. If you are at all familiar with SGML
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseor HTML it will be very evident. You only need to know what the tags
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseare and how to use them. You can find a good resource either for this
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseeither online or in printed form:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose DocBook: The Definitive Guide
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose By Norman Walsh and Leonard Muellner
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose ISBN: 156592-580-7
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose 1st Edition, October 1999
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThe book is available online in HTML format:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseand buried in:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose http://www.nwalsh.com/docbook/defguide/index.html
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseA lot of useful stuff is at NWalsh's site in general. You may also
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosewant to look at:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSGML document begins with a prefix that tells where to find the file
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosethat describes the meaning and structure of the tags used in the rest
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseof the document.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseFor our XML DocBook 4.0 based document this prefix looks like this:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThis "DOCTYPE" statement has three parts, of which we are only using
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseo The highest level term that represents this document (in this case
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose it is "book"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseo The identifier that tells us which DTD to use. This identifier has
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose two parts, the "Formal Public Identifier" (or FPI) and the system
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose identifier. In SGML you can have either a FPI or a SYSTEM identifier
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose but you have to have at least one of them. In XML you have to have a
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose SYSTEM identifier.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseFP & SYSTEM identifiers - These are names/lookups for the actual
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseDTD. The FPI is a globally unique name that should, on a properly
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseconfigured system, tell you exactly what DTD to use. The SYSTEM
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseidentifier gives an absolute location for the DTD. In XML these are
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosesupposed to be properly formatted URL's.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSGML has these things called "catalogs" that are files that map FPI's
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosein to actual files. A "catalog" can also be used to remap a SYSTEM
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseidentifier so you can say something like: "http://www.oasis.org/foo"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseWhen you use various SGML/XML tools they need to be configured to look
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseat the same "catalog" files so that as you move from tool to tool they
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseall refer to the same DTD for the same document.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseWe will be spending most of our configuration time making sure our
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosetools use the same "catalog" files and that we have the same DTD's
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseinstalled on our machines. XML's requirement of the SYSTEM identifier
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseover the FPI will probably lead to more problems as it does not
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseguarantee that everyone is using the same DTD.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseI did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose"jade" or "openjade."
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseYou can get the 4.0 XML DocBook DTD from:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose(download the .zip file.) NOTE: We will eventually be changing the
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSYSTEM identifier to the recommended value of:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseNOTE: Under FreeBSD this is the package:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseNetBSD instructions are coming soon.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseWith packages listed below installed under FreeBSD the "catalog" file
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosethat all the tools refer to at least one is in:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseIn order for our SYSTEM identifier for the XML DocBook dtd to be found
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseI create a new catalog file at the top of the XML directory created on
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThis file has one line:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThen in the main "catalog" I have it include this XML catalog:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseOn your systems you need to replace "/usr/local/share" with your
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseprefix root (probably /usr/pkg under NetBSD.)
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseNOTE: The URL used above is supposed to the be the proper one for this
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseXML DocBook DTD... but there is nothing at that URL so you really do
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseneed the "SYSTEM" identifier mapping in your catalog (or make the
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSYSTEM identifier in your document refer to the real location of the
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosefile on your local system.)
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseHOW TO VALIDATE A DOCUMENT:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseI use the sgmltools "nsgmls" document validator. Since we are using
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseXML we need to use the XML declarations, which are installed as part
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseof the modular DSSL style sheets:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseA convenient shell script "validate.sh" is now generated by configure
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseto invoke the above command with the correct system-dependent paths.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThe SGML tools can be found at:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseFreeBSD package for these is:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseHOW TO RENDER A DOCUMENT AS HTML or TeX:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseo Generate html doc with:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose openjade -v -d ./nominum-docbook-html.dsl \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseA convenient shell script "genhtml.sh" is now generated by configure to
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseinvoke the above command with the correct system-dependent paths.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseOn NetBSD there is no port for "openjade" however "jade" does still
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosework. However you need to specify the "catalog" file to use for style
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosesheets on the command line AND you need to have a default "catalog"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosemapping where to find various DTDs. It seems that "jade" installed out
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseof the box on NetBSD does not use a globally defined "catalog" file
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosefor mapping PUBLIC identifiers in to SYSTEM identifiers.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSo you need to have a "catalog" file in your current working directory
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosethat has in it this: (these are probably more entries than you need!)
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose CATALOG "/usr/pkg/share/sgml/docbook/2.4.1/catalog"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog"
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose(These would all be "/usr/local" on FreeBSD)
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseSo the command for jade on NetBSD will look like this:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosejade -v -c /usr/pkg/share/sgml/catalog -t sgml \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseFurthermore, since the style sheet subset we define has in it a hard
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosecoded path to the style sheet is based, it is actually generated by
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseconfigure from a .in file so that it will contain the correct
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosesystem-dependent path: where on FreeBSD the second line reads:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose <!ENTITY dbstyle SYSTEM "/usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseOn NetBSD it needs to read:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose <!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseNOTE: This is usually solved by having this style sheet modification
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosebe installed in a system directory and have it reference the style
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosesheet it is based on via a relative path.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseo Generate TeX documentation:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseopenjade -d ./nominum-docbook-print.dsl -t tex -v \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseIf you have "jade" installed instead of "openjade" then use that as
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosethe command. There is little difference, openjade has some bug fixes
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseand is in more active development.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseTo convert the resulting TeX file in to a DVI file you need to do:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseYou can also directly generate the pdf file via:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose pdftex "&pdfjadetex" Bv9ARM-book.tex
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThe scripts "genpdf.sh" and "gendvi." have been added to simply
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosegenerating the PDF and DVI output. These substitute the correct paths
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseof NetBSD & FreeBSD. You still need to have TeX, jadeTeX, and pdfTeX
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseinstalled and configured properly for these to work.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseYou will need to up both the "pool_size" and "hash_extra" variables in
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseyour texmf.cnf file and regenerate them. See below.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseYou can see that I am using a DSSSL style sheet for DocBook. Actually
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosetwo different ones - one for rendering html, and one for 'print'
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseNOTE: For HTML we are using a Nominum DSSSL style instead of the
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosedefault one (all it does is change the chunking to the chapter level
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseand makes the files end with ".html" instead of ".htm" so far.) If you
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosewant to use the plain jane DSSSL style sheet replace the:
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bose -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseThis style sheet will attempt to reference the one above.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseI am currently working on fixing these up so that it works the same on
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseour various systems. The main trick is knowing which DTD's and DSSSL
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosestylesheets you have installed, installing the right ones, and
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseconfiguring a CATALOG that refers to them in the same way. We will
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseprobably end up putting our CATALOG's in the same place and then we
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseshould be able to generate and validate our documents with a minimal
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosenumber of command line arguments.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseWhen running these commands you will get a lot of messages about a
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosebunch of general entities not being defined and having no default
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Boseentity. You can ignore those for now.
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit BoseAlso with the style sheets we have and jade as it is you will get
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosemessages about "xref to title" being unsupported. You can ignore these
8ff0aba893d8da1a8163ccaf9ad2c5b6bccd121fSumit Bosefor now as well.
o you may need to edit /usr/local/share/sgml/catalog and add the line:
CATALOG "/usr/local/share/sgml/openjade/catalog"
o edit the lines in texmf.cnf with these keys to these values:
sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx