diff --git a/doc/arm/README-SGML b/doc/arm/README-SGML index a03deaade5..d299adb357 100644 --- a/doc/arm/README-SGML +++ b/doc/arm/README-SGML @@ -1,6 +1,6 @@ The BIND v9 ARM master document is now kept in DocBook XML format. -Version: $Id: README-SGML,v 1.10 2000/11/06 23:11:04 scanner Exp $ +Version: $Id: README-SGML,v 1.11 2000/11/16 03:47:32 gson Exp $ The entire ARM is in the single file: @@ -24,24 +24,24 @@ or HTML it will be very evident. You only need to know what the tags are and how to use them. You can find a good resource either for this either online or in printed form: - DocBook: The Definitive Guide - By Norman Walsh and Leonard Muellner - ISBN: 156592-580-7 - 1st Edition, October 1999 - Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved. + DocBook: The Definitive Guide + By Norman Walsh and Leonard Muellner + ISBN: 156592-580-7 + 1st Edition, October 1999 + Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved. The book is available online in HTML format: - http://docbook.org/ + http://docbook.org/ and buried in: - http://www.nwalsh.com/docbook/defguide/index.html + http://www.nwalsh.com/docbook/defguide/index.html A lot of useful stuff is at NWalsh's site in general. You may also want to look at: - http://www.xml.com/ + http://www.xml.com/ The BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and SGML document begins with a prefix that tells where to find the file @@ -50,8 +50,8 @@ of the document. For our XML DocBook 4.0 based document this prefix looks like this: - + This "DOCTYPE" statement has three parts, of which we are only using two: @@ -128,7 +128,7 @@ On your systems you need to replace "/usr/local/share" with your prefix root (probably /usr/pkg under NetBSD.) NOTE: The URL used above is supposed to the be the proper one for this -XML DocBook DTD.. but there is nothing at that URL so you really do +XML DocBook DTD... but there is nothing at that URL so you really do need the "SYSTEM" identifier mapping in your catalog (or make the SYSTEM identifier in your document refer to the real location of the file on your local system.) @@ -139,26 +139,32 @@ I use the sgmltools "nsgmls" document validator. Since we are using XML we need to use the XML declarations, which are installed as part of the modular DSSL style sheets: -nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \ - Bv9ARM-book.xml + nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \ + Bv9ARM-book.xml + +A convenient shell script "validate.sh" is now generated by configure +to invoke the above command with the correct system-dependent paths. The SGML tools can be found at: - ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \ - ftp://ftp.nllgg.nl/pub/SGMLtools/v2.0/source/ + ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \ + ftp://ftp.nllgg.nl/pub/SGMLtools/v2.0/source/ FreeBSD package for these is: - /usr/ports/textproc/sgmltools + /usr/ports/textproc/sgmltools HOW TO RENDER A DOCUMENT AS HTML or TeX: o Generate html doc with: -openjade -d ./nominum-docbook-html.dsl \ - -t sgml \ - -v /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \ - Bv9ARM-book.xml + openjade -v -d ./nominum-docbook-html.dsl \ + -t sgml \ + /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \ + Bv9ARM-book.xml + +A convenient shell script "genhtml.sh" is now generated by configure to +invoke the above command with the correct system-dependent paths. On NetBSD there is no port for "openjade" however "jade" does still work. However you need to specify the "catalog" file to use for style @@ -187,17 +193,15 @@ jade -v -c /usr/pkg/share/sgml/catalog -t sgml \ ./Bv9ARM-book.xml Furthermore, since the style sheet subset we define has in it a hard -coded path to the style sheet is based on you need to modify the -second line of this file (this needs to be done via configure so we -are not tripping over each other.) - -Where on FreeBSD the second line reads: - - +coded path to the style sheet is based, it is actually generated by +configure from a .in file so that it will contain the correct +system-dependent path: where on FreeBSD the second line reads: + + On NetBSD it needs to read: - + NOTE: This is usually solved by having this style sheet modification be installed in a system directory and have it reference the style