newxml/README

   1 README for the newxml module
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 Requirements
   5 ~~~~~~~~~~~~
   6
   7 DocBook XML DTD 4.3CR2 - this is required as the 4.2 version doesn't properly
   8                          support XIncludes
   9
  10 DocBook XSL Stylesheets 1.64.1 - older versions of the stylesheets had a bug
  11                                  which caused broken hyperlinks (they pointed to
  12                                  the wrong directory).
  13
  14 libxml2-2.6.4 & libxslt-1.1.2 - these releases have a couple of XInclude related
  15                                 bugfixes in them
  16
  17
  18 Setting up the DTD
  19 ~~~~~~~~~~~~~~~~~~
  20
  21 The new XML sources point to the canonical URL where the DTD can be found in
  22 case it isn't installed locally.  In order to use our local copy we have to set
  23 up 2 XML catalog files (/etc/xml/catalog and /etc/xml/docbook) so that the
  24 canonical URLs are mapped to local files.
  25
  26 The easiest way to do this is to follow the BLFS instructions for the 4.2
  27 version of the DTD.  Simply substitute 4.3CR2 in place of every occurence of 4.2
  28 in the commands given.
  29
  30 After this, run just the commands listed under the "In order to install
  31 ScrollKeeper" section again, but this time replace every occurence of
  32 4.1.2 with 4.2.  This will allow any documents requiring the 4.2 version
  33 of the DTD to be processed against the newer version of the DTD.
  34
  35 Additionally there's just two more commands to run:
  36
  37   xmlcatalog --noout --add "delegateSystem" \
  38     "http://www.docbook.org/xml/" \
  39     "file:///etc/xml/docbook" /etc/xml/catalog &&
  40   xmlcatalog --noout --add "delegateURI" \
  41     "http://www.docbook.org/xml/" \
  42     "file:///etc/xml/docbook" /etc/xml/catalog
  43
  44 These are required as www.oasis-open.org only host official versions of the DTD,
  45 www.docbook.org host the beta/work-in-progress versions.  The commands above
  46 tell the XML processors that any requests to the www.docbook.org domain should
  47 be routed through the local /etc/xml/docbook file (which subsequently rewrites
  48 those URIs to our local copy of the DTD).  This step won't be required once the
  49 official 4.3 release is made.
  50
  51
  52 Processing the sources
  53 ~~~~~~~~~~~~~~~~~~~~~~
  54
  55 In order to process this version of the book simply use the following command:
  56
  57 xsltproc --nonet --xinclude -stringparam base.dir ~/lfs-book/ \
  58   stylesheets/lfs-chunked.xsl index.xml
  59
  60 This will produce chunked XHTML output in the directory specified by the base.dir command line parameter (~/lfs-book/ in the example above).
  61
  62 In time there will be other XSL files in the stylesheets directory to process the sources into formats such as LaTeX, Text, nALFS profiles.
  63
  64
  65 TODO
  66 ~~~~
  67
  68 1. Further split the XML sources up
  69 2. Reintroduce some entities that were removed during the cleanup
  70 3. Provide a css file to provide nicer output than whatever the UA's default is.
  71    * Started - needs some comments regarding layout.
  72 4. Decide whether we want to use the strict or traditional XHTML DTD.  Note in
  73    particular http://www.sagehill.net/docbookxsl/OtherOutputForms.html#d0e23340.
  74 5. Move the legalinfo off the titlepage.
  75      * Started
  76      * It generates it's own hyperlink ("Legal Notice") but the current book has
  77        it linked to via the "Copyright" message above
  78      * It writes the legalnotice out to a randomly named file under ${base.dir}
  79        instead of the more preferable ${base.dir}/prologue/legalnotice.html.
  80 6. Decide on what levels the TOCs should go down to.
  81    * Section elements now no longer have a TOC generated for them - the book TOC
  82      remains unchanged as do the part and appendix level TOCs.
  83 7. Incorporate Alex's restructuring?