2N/ACopyright (C) 2000, 2001 Internet Software Consortium.
2N/AThe BIND v9 ARM master document is now kept in DocBook XML format.
2N/AVersion: $Id: README-SGML,v 1.14 2001/02/01 20:06:14 scanner Exp $
2N/AThe entire ARM is in the single file:
2N/AAll of the other documents - HTML, PDF, etc - are generated from this
2N/AThis file attempts to describe what tools are necessary for the
2N/Amaintenance of this document as well as the generation of the
2N/Aalternate formats of this document.
2N/AThis file will also spend a very little time describing the XML and
2N/ASGML headers so you can understand a bit what you may need to do to be
2N/Aable to work with this document in any fashion other than simply
2N/AWe will spend almost no time on the actual tags and how to write an
2N/AXML DocBook compliant document. If you are at all familiar with SGML
2N/Aor HTML it will be very evident. You only need to know what the tags
2N/Aare and how to use them. You can find a good resource either for this
2N/Aeither online or in printed form:
2N/A DocBook: The Definitive Guide
2N/A By Norman Walsh and Leonard Muellner
2N/A 1st Edition, October 1999
2N/A Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
2N/AThe book is available online in HTML format:
2N/AA lot of useful stuff is at NWalsh's site in general. You may also
2N/AThe BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
2N/ASGML document begins with a prefix that tells where to find the file
2N/Athat describes the meaning and structure of the tags used in the rest
2N/AFor our XML DocBook 4.0 based document this prefix looks like this:
2N/A <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
2N/AThis "DOCTYPE" statement has three parts, of which we are only using
2N/Ao The highest level term that represents this document (in this case
2N/Ao The identifier that tells us which DTD to use. This identifier has
2N/A two parts, the "Formal Public Identifier" (or FPI) and the system
2N/A identifier. In SGML you can have either a FPI or a SYSTEM identifier
2N/A but you have to have at least one of them. In XML you have to have a
2N/ADTD. The FPI is a globally unique name that should, on a properly
2N/Aconfigured system, tell you exactly what DTD to use. The SYSTEM
2N/Aidentifier gives an absolute location for the DTD. In XML these are
2N/Asupposed to be properly formatted URL's.
2N/ASGML has these things called "catalogs" that are files that map FPI's
2N/Ain to actual files. A "catalog" can also be used to remap a SYSTEM
2N/AWhen you use various
SGML/XML tools they need to be configured to look
2N/Aat the same "catalog" files so that as you move from tool to tool they
2N/Aall refer to the same DTD for the same document.
2N/AWe will be spending most of our configuration time making sure our
2N/Atools use the same "catalog" files and that we have the same DTD's
2N/Ainstalled on our machines. XML's requirement of the SYSTEM identifier
2N/Aover the FPI will probably lead to more problems as it does not
2N/Aguarantee that everyone is using the same DTD.
2N/AI did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
2N/A"jade" or "openjade."
2N/AYou can get the 4.0 XML DocBook DTD from:
2N/A(download the .zip file.) NOTE: We will eventually be changing the
2N/ASYSTEM identifier to the recommended value of:
2N/ANOTE: Under FreeBSD this is the package:
2N/ANetBSD instructions are coming soon.
2N/AWith packages listed below installed under FreeBSD the "catalog" file
2N/Athat all the tools refer to at least one is in:
2N/AIn order for our SYSTEM identifier for the XML DocBook dtd to be found
2N/AI create a new catalog file at the top of the XML directory created on
2N/AThis file has one line:
2N/AThen in the main "catalog" I have it include this XML catalog:
2N/ANOTE: The URL used above is supposed to the be the proper one for this
2N/AXML DocBook DTD... but there is nothing at that URL so you really do
2N/Aneed the "SYSTEM" identifier mapping in your catalog (or make the
2N/ASYSTEM identifier in your document refer to the real location of the
2N/Afile on your local system.)
2N/AHOW TO VALIDATE A DOCUMENT:
2N/AI use the sgmltools "nsgmls" document validator. Since we are using
2N/AXML we need to use the XML declarations, which are installed as part
2N/Aof the modular DSSL style sheets:
2N/Ato invoke the above command with the correct system-dependent paths.
2N/AThe SGML tools can be found at:
2N/AFreeBSD package for these is:
2N/AHOW TO RENDER A DOCUMENT AS HTML or TeX:
2N/Ao Generate html doc with:
2N/AA convenient shell script "
genhtml.sh" is now generated by configure to
2N/Ainvoke the above command with the correct system-dependent paths.
2N/AOn NetBSD there is no port for "openjade" however "jade" does still
2N/Awork. However you need to specify the "catalog" file to use for style
2N/Asheets on the command line AND you need to have a default "catalog"
2N/Amapping where to find various DTDs. It seems that "jade" installed out
2N/Aof the box on NetBSD does not use a globally defined "catalog" file
2N/Afor mapping PUBLIC identifiers in to SYSTEM identifiers.
2N/ASo you need to have a "catalog" file in your current working directory
2N/Athat has in it this: (these are probably more entries than you need!)
2N/ASo the command for jade on NetBSD will look like this:
2N/AFurthermore, since the style sheet subset we define has in it a hard
2N/Acoded path to the style sheet is based, it is actually generated by
2N/Aconfigure from a .in file so that it will contain the correct
2N/Asystem-dependent path: where on FreeBSD the second line reads:
2N/AOn NetBSD it needs to read:
2N/ANOTE: This is usually solved by having this style sheet modification
2N/Abe installed in a system directory and have it reference the style
2N/Asheet it is based on via a relative path.
2N/Ao Generate TeX documentation:
2N/AIf you have "jade" installed instead of "openjade" then use that as
2N/Athe command. There is little difference, openjade has some bug fixes
2N/Aand is in more active development.
2N/ATo convert the resulting TeX file in to a DVI file you need to do:
2N/AYou can also directly generate the pdf file via:
2N/AYou will need to up both the "pool_size" and "hash_extra" variables in
2N/AYou can see that I am using a DSSSL style sheet for DocBook. Actually
2N/Atwo different ones - one for rendering html, and one for 'print'
2N/ANOTE: For HTML we are using a Nominum DSSSL style instead of the
2N/Adefault one (all it does is change the chunking to the chapter level
2N/Aand makes the files end with ".html" instead of ".htm" so far.) If you
2N/Awant to use the plain jane DSSSL style sheet replace the:
2N/AThis style sheet will attempt to reference the one above.
2N/AI am currently working on fixing these up so that it works the same on
2N/Aour various systems. The main trick is knowing which DTD's and DSSSL
2N/Astylesheets you have installed, installing the right ones, and
2N/Aconfiguring a CATALOG that refers to them in the same way. We will
2N/Aprobably end up putting our CATALOG's in the same place and then we
2N/Ashould be able to generate and validate our documents with a minimal
2N/Anumber of command line arguments.
2N/AWhen running these commands you will get a lot of messages about a
2N/Abunch of general entities not being defined and having no default
2N/Aentity. You can ignore those for now.
2N/AAlso with the style sheets we have and jade as it is you will get
2N/Amessages about "xref to title" being unsupported. You can ignore these
2N/A=== Getting the various tools installed on FreeBSD
2N/A(NetBSD coming soon..)
2N/Ao On freebsd you need to install the following packages:
2N/Ao on freebsd you need to make some entities visible to the docbook xml
2N/A dtd by making a symlink (can probably be done with a catalog too)
2N/Ao add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
2N/A o edit the lines in
texmf.cnf with these keys to these values:
2N/A main_memory = 1100000
2N/A string_vacancies = 45000
2N/A o For the jadetex macros you will need I recommend you get a more
2N/A current version than what is packaged with openjade or jade.
2N/A Unzip the file you get from there (should be jadetex-2.20 or
2N/A In the directory you unzip:
2N/A NOTE: In the most uptodate "ports" for FreeBSD, jadetext is 2.20+
2N/A so on this platform you should be set as of 2001.01.08.