README-SGML revision c71787bd6356c92e9c7d0a174cd63ab17fcf34c6
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThe BIND v9 ARM master document is now kept in DocBook XML format.
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceVersion: $Id: README-SGML,v 1.4 2000/09/11 17:54:44 scanner Exp $
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThe entire ARM is in the single file:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceAll of the other documents - HTML, PDF, etc - are generated from this
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucemaster source.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThis file attempts to describe what tools are necessary for the
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucemaintenance of this document as well as the generation of the
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucealternate formats of this document.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThis file will also spend a very little time describing the XML and
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceSGML headers so you can understand a bit what you may need to do to be
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceable to work with this document in any fashion other than simply
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceWe will spend almost no time on the actual tags and how to write an
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceXML DocBook compliant document. If you are at all familiar with SGML
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceor HTML it will be very evident. You only need to know what the tags
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceare and how to use them. You can find a good resource either for this
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceeither online or in printed form:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce DocBook: The Definitive Guide
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce By Norman Walsh and Leonard Muellner
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce ISBN: 156592-580-7
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce 1st Edition, October 1999
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThe book is available online in HTML format:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceand buried in:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceA lot of useful stuff is at NWalsh's site in general. You may also
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucewant to look at:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceSGML document begins with a prefix that tells where to find the file
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucethat describes the meaning and structure of the tags used in the rest
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceof the document.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceFor our XML DocBook 4.0 based document this prefix looks like this:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThis "DOCTYPE" statement has three parts, of which we are only using
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceo The highest level term that represents this document (in this case
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce it is "book"
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceo The identifier that tells us which DTD to use. This identifier has
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce two parts, the "Formal Public Identifier" (or FPI) and the system
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce identifier. In SGML you can have either a FPI or a SYSTEM identifier
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce but you have to have at least one of them. In XML you have to have a
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce SYSTEM identifier.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceFP & SYSTEM identifiers - These are names/lookups for the actual
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceDTD. The FPI is a globally unique name that should, on a properly
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceconfigured system, tell you exactly what DTD to use. The SYSTEM
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceidentifier gives an absolute location for the DTD. In XML these are
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucesupposed to be properly formatted URL's.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceSGML has these things called "catalogs" that are files that map FPI's
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucein to actual files. A "catalog" can also be used to remap a SYSTEM
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceidentifier so you can say something like: "http://www.oasis.org/foo"
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceWhen you use various SGML/XML tools they need to be configured to look
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceat the same "catalog" files so that as you move from tool to tool they
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceall refer to the same DTD for the same document.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceWe will be spending most of our configuration time making sure our
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucetools use the same "catalog" files and that we have the same DTD's
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceinstalled on our machines. XML's requirement of the SYSTEM identifier
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceover the FPI will probably lead to more problems as it does not
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceguarantee that everyone is using the same DTD.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceI did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce"jade" or "openjade."
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceYou can get the 4.0 XML DocBook DTD from:
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric Luce(download the .zip file.) NOTE: We will eventually be changing the
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceSYSTEM identifier to the recommended value of:
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric Luce http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceNOTE: Under FreeBSD this is the package:
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceNetBSD instructions are coming soon.
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceAs soon as I figure out the proper "catalog" files to change and how
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric Luceto change them for this to do the proper re-mapping.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceHOW TO VALIDATE A DOCUMENT:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceI use the sgmltools "nsgmls" document validator. Since we are using
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceXML we need to use the XML declarations, which are installed as part
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceof the modular DSSL style sheets:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucensgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceThe SGML tools can be found at:
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric Luce ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceFreeBSD package for these is:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceHOW TO RENDER A DOCUMENT AS HTML or TeX:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceo Generate html doc with:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce -v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceo Generate TeX documentation:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucejade -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luce -v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
7d7c5eee345bf4a62764cbce55868a6c09568543Eric LuceTo convert the resulting TeX file in to a DVI file you need to do:
7d7c5eee345bf4a62764cbce55868a6c09568543Eric Luce tex "&jadetex" Bv9ARM-book.tex
7d7c5eee345bf4a62764cbce55868a6c09568543Eric LuceYou will need to up both the "pool_size" and "hash_extra" variables in
7d7c5eee345bf4a62764cbce55868a6c09568543Eric Luceyour texmf.cnf file and regenerate them. Stay tuned for instructions
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceYou can see that I am using a DSSSL style sheet for DocBook. Actually
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucetwo different ones - one for rendering html, and one for 'print'
4317b4c0cf3f37deef20413f438e03603ca78e14Eric LuceNOTE: For HTML we are using a Nominum DSSSL style instead of the
4317b4c0cf3f37deef20413f438e03603ca78e14Eric Lucedefault one (all it does is change the chunking to the chapter level
4317b4c0cf3f37deef20413f438e03603ca78e14Eric Luceand makes the files end with ".html" instead of ".htm" so far.) If you
4317b4c0cf3f37deef20413f438e03603ca78e14Eric Lucewant to use the plain jane DSSSL style sheet replace the:
4317b4c0cf3f37deef20413f438e03603ca78e14Eric Luce -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThis style sheet will attempt to reference the one above.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceI am currently working on fixing these up so that it works the same on
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceour various systems. The main trick is knowing which DTD's and DSSSL
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucestylesheets you have installed, installing the right ones, and
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceconfiguring a CATALOG that refers to them in the same way. We will
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceprobably end up putting our CATALOG's in the same place and then we
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceshould be able to generate and validate our documents with a minimal
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucenumber of command line arguments.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceWhen running these commands you will get a lot of messages about a
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucebunch of general entities not being defined and having no default
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceentity. You can ignore those for now.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceAlso with the style sheets we have and jade as it is you will get
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucemessages about "xref to title" being unsupported. You can ignore these
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Lucefor now as well.