/contrib/bind9/doc/arm/README-SGML

https://bitbucket.org/freebsd/freebsd-head/ · #! · 329 lines · 228 code · 101 blank · 0 comment · 0 complexity · 3f540e000b02c25049d2a823b17b9355 MD5 · raw file

  1. Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
  2. Copyright (C) 2000, 2001 Internet Software Consortium.
  3. See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
  4. The BIND v9 ARM master document is now kept in DocBook XML format.
  5. Version: $Id: README-SGML,v 1.17 2004/03/05 05:04:43 marka Exp $
  6. The entire ARM is in the single file:
  7. Bv9ARM-book.xml
  8. All of the other documents - HTML, PDF, etc - are generated from this
  9. master source.
  10. This file attempts to describe what tools are necessary for the
  11. maintenance of this document as well as the generation of the
  12. alternate formats of this document.
  13. This file will also spend a very little time describing the XML and
  14. SGML headers so you can understand a bit what you may need to do to be
  15. able to work with this document in any fashion other than simply
  16. editing it.
  17. We will spend almost no time on the actual tags and how to write an
  18. XML DocBook compliant document. If you are at all familiar with SGML
  19. or HTML it will be very evident. You only need to know what the tags
  20. are and how to use them. You can find a good resource either for this
  21. either online or in printed form:
  22. DocBook: The Definitive Guide
  23. By Norman Walsh and Leonard Muellner
  24. ISBN: 156592-580-7
  25. 1st Edition, October 1999
  26. Copyright (C) 1999 by O'Reilly & Associates, Inc. All rights reserved.
  27. The book is available online in HTML format:
  28. http://docbook.org/
  29. and buried in:
  30. http://www.nwalsh.com/docbook/defguide/index.html
  31. A lot of useful stuff is at NWalsh's site in general. You may also
  32. want to look at:
  33. http://www.xml.com/
  34. The BIND v9 ARM is based on the XML 4.0 DocBook DTD. Every XML and
  35. SGML document begins with a prefix that tells where to find the file
  36. that describes the meaning and structure of the tags used in the rest
  37. of the document.
  38. For our XML DocBook 4.0 based document this prefix looks like this:
  39. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
  40. "/usr/local/share/xml/dtd/docbook/docbookx.dtd">
  41. This "DOCTYPE" statement has three parts, of which we are only using
  42. two:
  43. o The highest level term that represents this document (in this case
  44. it is "book"
  45. o The identifier that tells us which DTD to use. This identifier has
  46. two parts, the "Formal Public Identifier" (or FPI) and the system
  47. identifier. In SGML you can have either a FPI or a SYSTEM identifier
  48. but you have to have at least one of them. In XML you have to have a
  49. SYSTEM identifier.
  50. FP & SYSTEM identifiers - These are names/lookups for the actual
  51. DTD. The FPI is a globally unique name that should, on a properly
  52. configured system, tell you exactly what DTD to use. The SYSTEM
  53. identifier gives an absolute location for the DTD. In XML these are
  54. supposed to be properly formatted URL's.
  55. SGML has these things called "catalogs" that are files that map FPI's
  56. in to actual files. A "catalog" can also be used to remap a SYSTEM
  57. identifier so you can say something like: "http://www.oasis.org/foo"
  58. is actually "/usr/local/share/xml/foo.dtd"
  59. When you use various SGML/XML tools they need to be configured to look
  60. at the same "catalog" files so that as you move from tool to tool they
  61. all refer to the same DTD for the same document.
  62. We will be spending most of our configuration time making sure our
  63. tools use the same "catalog" files and that we have the same DTD's
  64. installed on our machines. XML's requirement of the SYSTEM identifier
  65. over the FPI will probably lead to more problems as it does not
  66. guarantee that everyone is using the same DTD.
  67. I did my initial work with the "sgmltools" the XML 4.0 DocBook DTD and
  68. "jade" or "openjade."
  69. You can get the 4.0 XML DocBook DTD from:
  70. http://www.docbook.org/xml/4.0/
  71. (download the .zip file.) NOTE: We will eventually be changing the
  72. SYSTEM identifier to the recommended value of:
  73. http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
  74. NOTE: Under FreeBSD this is the package:
  75. /usr/ports/textproc/docbook-xml
  76. NetBSD instructions are coming soon.
  77. With packages listed below installed under FreeBSD the "catalog" file
  78. that all the tools refer to at least one is in:
  79. /usr/local/share/sgml/catalog
  80. In order for our SYSTEM identifier for the XML DocBook dtd to be found
  81. I create a new catalog file at the top of the XML directory created on
  82. FreeBSD:
  83. /usr/local/share/xml/catalog
  84. This file has one line:
  85. SYSTEM "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" "/usr/local/share/xml/dtd/docbook/docbookx.dtd"
  86. Then in the main "catalog" I have it include this XML catalog:
  87. CATALOG "/usr/local/share/xml/catalog"
  88. On your systems you need to replace "/usr/local/share" with your
  89. prefix root (probably /usr/pkg under NetBSD.)
  90. NOTE: The URL used above is supposed to the be the proper one for this
  91. XML DocBook DTD... but there is nothing at that URL so you really do
  92. need the "SYSTEM" identifier mapping in your catalog (or make the
  93. SYSTEM identifier in your document refer to the real location of the
  94. file on your local system.)
  95. HOW TO VALIDATE A DOCUMENT:
  96. I use the sgmltools "nsgmls" document validator. Since we are using
  97. XML we need to use the XML declarations, which are installed as part
  98. of the modular DSSL style sheets:
  99. nsgmls -sv /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
  100. Bv9ARM-book.xml
  101. A convenient shell script "validate.sh" is now generated by configure
  102. to invoke the above command with the correct system-dependent paths.
  103. The SGML tools can be found at:
  104. ftp://ftp.us.sgmltools.org/pub/SGMLtools/v2.0/source/ \
  105. ftp://ftp.nllgg.nl/pub/SGMLtools/v2.0/source/
  106. FreeBSD package for these is:
  107. /usr/ports/textproc/sgmltools
  108. HOW TO RENDER A DOCUMENT AS HTML or TeX:
  109. o Generate html doc with:
  110. openjade -v -d ./nominum-docbook-html.dsl \
  111. -t sgml \
  112. /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
  113. Bv9ARM-book.xml
  114. A convenient shell script "genhtml.sh" is now generated by configure to
  115. invoke the above command with the correct system-dependent paths.
  116. On NetBSD there is no port for "openjade" however "jade" does still
  117. work. However you need to specify the "catalog" file to use for style
  118. sheets on the command line AND you need to have a default "catalog"
  119. mapping where to find various DTDs. It seems that "jade" installed out
  120. of the box on NetBSD does not use a globally defined "catalog" file
  121. for mapping PUBLIC identifiers in to SYSTEM identifiers.
  122. So you need to have a "catalog" file in your current working directory
  123. that has in it this: (these are probably more entries than you need!)
  124. CATALOG "/usr/pkg/share/sgml/iso8879/catalog"
  125. CATALOG "/usr/pkg/share/sgml/docbook/2.4.1/catalog"
  126. CATALOG "/usr/pkg/share/sgml/docbook/3.0/catalog"
  127. CATALOG "/usr/pkg/share/sgml/docbook/3.1/catalog"
  128. CATALOG "/usr/pkg/share/sgml/jade/catalog"
  129. CATALOG "/usr/local/share/xml/catalog"
  130. (These would all be "/usr/local" on FreeBSD)
  131. So the command for jade on NetBSD will look like this:
  132. jade -v -c /usr/pkg/share/sgml/catalog -t sgml \
  133. -d ./nominum-docbook-html.dsl \
  134. /usr/pkg/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
  135. ./Bv9ARM-book.xml
  136. Furthermore, since the style sheet subset we define has in it a hard
  137. coded path to the style sheet is based, it is actually generated by
  138. configure from a .in file so that it will contain the correct
  139. system-dependent path: where on FreeBSD the second line reads:
  140. <!ENTITY dbstyle SYSTEM "/usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
  141. On NetBSD it needs to read:
  142. <!ENTITY dbstyle SYSTEM "/usr/pkg/share/sgml/docbook/dsssl/modular/html/docbook.dsl" CDATA DSSSL>
  143. NOTE: This is usually solved by having this style sheet modification
  144. be installed in a system directory and have it reference the style
  145. sheet it is based on via a relative path.
  146. o Generate TeX documentation:
  147. openjade -d ./nominum-docbook-print.dsl -t tex -v \
  148. /usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \
  149. Bv9ARM-book.xml
  150. If you have "jade" installed instead of "openjade" then use that as
  151. the command. There is little difference, openjade has some bug fixes
  152. and is in more active development.
  153. To convert the resulting TeX file in to a DVI file you need to do:
  154. tex "&jadetex" Bv9ARM-book.tex
  155. You can also directly generate the pdf file via:
  156. pdftex "&pdfjadetex" Bv9ARM-book.tex
  157. The scripts "genpdf.sh" and "gendvi." have been added to simply
  158. generating the PDF and DVI output. These substitute the correct paths
  159. of NetBSD & FreeBSD. You still need to have TeX, jadeTeX, and pdfTeX
  160. installed and configured properly for these to work.
  161. You will need to up both the "pool_size" and "hash_extra" variables in
  162. your texmf.cnf file and regenerate them. See below.
  163. You can see that I am using a DSSSL style sheet for DocBook. Actually
  164. two different ones - one for rendering html, and one for 'print'
  165. media.
  166. NOTE: For HTML we are using a Nominum DSSSL style instead of the
  167. default one (all it does is change the chunking to the chapter level
  168. and makes the files end with ".html" instead of ".htm" so far.) If you
  169. want to use the plain jane DSSSL style sheet replace the:
  170. -d ./nominum-docbook-html.dsl
  171. with
  172. -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl
  173. This style sheet will attempt to reference the one above.
  174. I am currently working on fixing these up so that it works the same on
  175. our various systems. The main trick is knowing which DTD's and DSSSL
  176. stylesheets you have installed, installing the right ones, and
  177. configuring a CATALOG that refers to them in the same way. We will
  178. probably end up putting our CATALOG's in the same place and then we
  179. should be able to generate and validate our documents with a minimal
  180. number of command line arguments.
  181. When running these commands you will get a lot of messages about a
  182. bunch of general entities not being defined and having no default
  183. entity. You can ignore those for now.
  184. Also with the style sheets we have and jade as it is you will get
  185. messages about "xref to title" being unsupported. You can ignore these
  186. for now as well.
  187. === Getting the various tools installed on FreeBSD
  188. (NetBSD coming soon..)
  189. o On freebsd you need to install the following packages:
  190. o print/teTeX
  191. o textproc/openjade
  192. o textproc/docbook
  193. o textproc/docbook-xml
  194. o textproc/dsssl-docbook-modular
  195. o textproc/dtd-catalogs
  196. o on freebsd you need to make some entities visible to the docbook xml
  197. dtd by making a symlink (can probably be done with a catalog too)
  198. ln -s /usr/local/share/xml/entity /usr/local/share/xml/dtd/docbook/ent
  199. o you may need to edit /usr/local/share/sgml/catalog and add the line:
  200. CATALOG "/usr/local/share/sgml/openjade/catalog"
  201. o add "hugelatex," Enlarge pool sizes, install the jadetex TeX driver
  202. file.
  203. cd /usr/local/share/texmf/web2c/
  204. sudo cp texmf.cnf texmf.cnf.bak
  205. o edit the lines in texmf.cnf with these keys to these values:
  206. main_memory = 1100000
  207. hash_extra = 15000
  208. pool_size = 500000
  209. string_vacancies = 45000
  210. max_strings = 55000
  211. pool_free = 47500
  212. nest_size = 500
  213. param_size = 1500
  214. save_size = 5000
  215. stack_size = 1500
  216. sudo tex -ini -progname=hugelatex -fmt=hugelatex latex.ltx
  217. sudo texconfig init
  218. sudo texhash
  219. o For the jadetex macros you will need I recommend you get a more
  220. current version than what is packaged with openjade or jade.
  221. Checkout http://www.tug.org/applications/jadetex/
  222. Unzip the file you get from there (should be jadetex-2.20 or
  223. newer.)
  224. In the directory you unzip:
  225. sudo make install
  226. sudo texhash
  227. NOTE: In the most uptodate "ports" for FreeBSD, jadetext is 2.20+
  228. so on this platform you should be set as of 2001.01.08.