README-SGML revision cffe50abf66495ee08084f8e1081278a9b589985
cffe50abf66495ee08084f8e1081278a9b589985Brian WellingtonCopyright (C) 2000 Internet Software Consortium.
cffe50abf66495ee08084f8e1081278a9b589985Brian WellingtonSee COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThe BIND v9 ARM master document is now kept in DocBook XML format.
cffe50abf66495ee08084f8e1081278a9b589985Brian WellingtonVersion: $Id: README-SGML,v 1.12 2000/11/18 02:57:24 bwelling 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:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson DocBook: The Definitive Guide
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson By Norman Walsh and Leonard Muellner
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson ISBN: 156592-580-7
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson 1st Edition, October 1999
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric LuceThe book is available online in HTML format:
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceand buried in:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson http://www.nwalsh.com/docbook/defguide/index.html
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:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson "/usr/local/share/xml/dtd/docbook/docbookx.dtd">
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.
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceWith packages listed below installed under FreeBSD the "catalog" file
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric Lucethat all the tools refer to at least one is in:
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceIn order for our SYSTEM identifier for the XML DocBook dtd to be found
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceI create a new catalog file at the top of the XML directory created on
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceThis file has one line:
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric Luce SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceThen in the main "catalog" I have it include this XML catalog:
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceOn your systems you need to replace "/usr/local/share" with your
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric Luceprefix root (probably /usr/pkg under NetBSD.)
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceNOTE: The URL used above is supposed to the be the proper one for this
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas GustafssonXML DocBook DTD... but there is nothing at that URL so you really do
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric Luceneed the "SYSTEM" identifier mapping in your catalog (or make the
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric LuceSYSTEM identifier in your document refer to the real location of the
fafd1d771905532e8dc3efa2ce90ce4c9e74af61Eric Lucefile on your local system.)
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:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas GustafssonA convenient shell script "validate.sh" is now generated by configure
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafssonto invoke the above command with the correct system-dependent paths.
c71787bd6356c92e9c7d0a174cd63ab17fcf34c6Eric LuceThe SGML tools can be found at:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson ftp://ftp.nllgg.nl/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:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson openjade -v -d ./nominum-docbook-html.dsl \
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas GustafssonA convenient shell script "genhtml.sh" is now generated by configure to
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafssoninvoke the above command with the correct system-dependent paths.
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceOn NetBSD there is no port for "openjade" however "jade" does still
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucework. However you need to specify the "catalog" file to use for style
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucesheets on the command line AND you need to have a default "catalog"
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucemapping where to find various DTDs. It seems that "jade" installed out
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luceof the box on NetBSD does not use a globally defined "catalog" file
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucefor mapping PUBLIC identifiers in to SYSTEM identifiers.
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceSo you need to have a "catalog" file in your current working directory
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucethat has in it this: (these are probably more entries than you need!)
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luce CATALOG "/usr/pkg/share/sgml/docbook/2.4.1/catalog"
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luce CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog"
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luce CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog"
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luce(These would all be "/usr/local" on FreeBSD)
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceSo the command for jade on NetBSD will look like this:
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucejade -v -c /usr/pkg/share/sgml/catalog -t sgml \
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luce /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceFurthermore, since the style sheet subset we define has in it a hard
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafssoncoded path to the style sheet is based, it is actually generated by
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafssonconfigure from a .in file so that it will contain the correct
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafssonsystem-dependent path: where on FreeBSD the second line reads:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson <!ENTITY dbstyle SYSTEM "/usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceOn NetBSD it needs to read:
01f8e2b2bf6cc60b806984e2bf860221d5988e53Andreas Gustafsson <!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceNOTE: This is usually solved by having this style sheet modification
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucebe installed in a system directory and have it reference the style
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucesheet it is based on via a relative path.
55c73d07349b0be7d800f39fcc30eba6ab760129Eric Luceo Generate TeX documentation:
99e8cdc499b7d0fc96f88d0a6a3ccc0624d46854Eric Luceopenjade -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 \
f3cdacd7645772686420f7eadcc85b4c18301adeEric LuceIf you have "jade" installed instead of "openjade" then use that as
f3cdacd7645772686420f7eadcc85b4c18301adeEric Lucethe command. There is little difference, openjade has some bug fixes
f3cdacd7645772686420f7eadcc85b4c18301adeEric Luceand is in more active development.
7d7c5eee345bf4a62764cbce55868a6c09568543Eric LuceTo convert the resulting TeX file in to a DVI file you need to do:
7d7c5eee345bf4a62764cbce55868a6c09568543Eric Luce tex "&jadetex" Bv9ARM-book.tex
9b26804b581d11dc845e96073bda32f739581aeeEric LuceYou can also directly generate the pdf file via:
9b26804b581d11dc845e96073bda32f739581aeeEric Luce pdftex "&pdfjadetex" Bv9ARM-book.tex
7d7c5eee345bf4a62764cbce55868a6c09568543Eric LuceYou will need to up both the "pool_size" and "hash_extra" variables in
9b26804b581d11dc845e96073bda32f739581aeeEric Luceyour texmf.cnf file and regenerate them. See below.
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.
9b26804b581d11dc845e96073bda32f739581aeeEric Luce=== Getting the various tools installed on FreeBSD
9b26804b581d11dc845e96073bda32f739581aeeEric Luce(NetBSD coming soon..)
9b26804b581d11dc845e96073bda32f739581aeeEric Luceo On freebsd you need to install the following packages:
9b26804b581d11dc845e96073bda32f739581aeeEric Luceo on freebsd you need to make some entities visible to the docbook xml
9b26804b581d11dc845e96073bda32f739581aeeEric Luce dtd by making a symlink (can probably be done with a catalog too)
9b26804b581d11dc845e96073bda32f739581aeeEric Luce ln -s /usr/local/share/xml/entity /usr/local/share/xml/dtd/docbook/ent
9b26804b581d11dc845e96073bda32f739581aeeEric Luceo you may need to edit /usr/local/share/sgml/catalog and add the line:
9b26804b581d11dc845e96073bda32f739581aeeEric Luceo add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
9b26804b581d11dc845e96073bda32f739581aeeEric Luce o edit the lines in texmf.cnf with these keys to these values:
9b26804b581d11dc845e96073bda32f739581aeeEric Luce main_memory = 1100000
9b26804b581d11dc845e96073bda32f739581aeeEric Luce hash_extra = 15000
9b26804b581d11dc845e96073bda32f739581aeeEric Luce pool_size = 500000
9b26804b581d11dc845e96073bda32f739581aeeEric Luce string_vacancies = 45000
9b26804b581d11dc845e96073bda32f739581aeeEric Luce max_strings = 55000
9b26804b581d11dc845e96073bda32f739581aeeEric Luce pool_free = 47500
9b26804b581d11dc845e96073bda32f739581aeeEric Luce nest_size = 500
9b26804b581d11dc845e96073bda32f739581aeeEric Luce param_size = 1500
9b26804b581d11dc845e96073bda32f739581aeeEric Luce save_size = 5000
9b26804b581d11dc845e96073bda32f739581aeeEric Luce stack_size = 1500
9b26804b581d11dc845e96073bda32f739581aeeEric Luce sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx
9b26804b581d11dc845e96073bda32f739581aeeEric Luce sudo texconfig init
9b26804b581d11dc845e96073bda32f739581aeeEric Luce o For the jadetex macros you will need I recommend you get a more
9b26804b581d11dc845e96073bda32f739581aeeEric Luce current version than what is packaged with openjade or jade.
9b26804b581d11dc845e96073bda32f739581aeeEric Luce Unzip the file you get from there (should be jadetex-2.20 or
9b26804b581d11dc845e96073bda32f739581aeeEric Luce In the directory you unzip:
9b26804b581d11dc845e96073bda32f739581aeeEric Luce sudo make install
9b26804b581d11dc845e96073bda32f739581aeeEric Luce sudo texhash