DOCS/xml/README

   1 Tools required for building the documentation
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 * GNU make 3.80 or later
   5 * DocBook 4.1.2 or later
   6 * The DocBook XML DTD (also known as DocBk XML)
   7 * DocBook XSL stylesheets -- version 1.50.0 or later is recommended.
   8
   9 I am not quite sure which tools work, but I used the following
  10 ones successfully, so they are required:
  11
  12 * xmllint (part of libxml2) is used for validation.
  13 * xsltproc (part of libxslt1) is used for transforming XML files into HTML
  14   files. Version 1.0.18 or later is recommended.
  15
  16 It's also possible to use the Saxon XSLT Processor. The Russian translator
  17 used it (version 6.4.4) for a while. If you have a suitable JavaVM and a
  18 saxon.jar installed somewhere, configure will try to detect them. If
  19 autodetection fails, try to tweak DOCS/xml/configure to get it working and
  20 send us a patch :)
  21
  22 On Red Hat systems you need the following packages:
  23 libxml2, libxslt, docbook-dtds, docbook-style-xsl
  24
  25 On Debian Sarge you will need these packages:
  26 docbook-xml, docbook-xsl, xsltproc, libxml2-utils
  27
  28
  29 Installing the required tools from source
  30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  31
  32 1) Download libxslt AND libxml2 packages from
  33    http://xmlsoft.org/XSLT/downloads.html
  34
  35    Installing them should be straightforward, execute the usual "./configure"
  36    and "make" then "make install" commands.
  37
  38
  39 2) Download the docbook-xml package from http://www.oasis-open.org/docbook/xml/
  40    Use the newest version. The URL will be something like this:
  41
  42         http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip
  43
  44    Extract this package into a directory, enter it, and execute the following
  45    commands:
  46
  47         mkdir -p /usr/share/sgml/docbook/dtd/xml/4.2/
  48         cp -r * /usr/share/sgml/docbook/dtd/xml/4.2/
  49
  50
  51 3) Download the docbook-xsl package from
  52    http://prdownloads.sourceforge.net/docbook/
  53
  54    Use the newest version. The URL will be something like this:
  55
  56         http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.62.0.tar.gz
  57
  58    Extract this package into a directory, enter it, and execute the following
  59    commands:
  60
  61         mkdir -p /usr/share/sgml/docbook/stylesheet/xsl/nwalsh
  62         cp -r VERSION common html lib \
  63                 /usr/share/sgml/docbook/stylesheet/xsl/nwalsh
  64
  65
  66 Building the documentation
  67 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  68
  69 Before trying to build the documentation, run
  70
  71         make help
  72
  73 to see all available build targets and make your choice. If something goes
  74 wrong, check the Configuration section of the toplevel Makefile and adjust
  75 the variables.
  76
  77
  78 A few words about SGML catalog files
  79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  80
  81 As far as I know, the document type declaration in XML files requires
  82 both a public and a system identifier. For example:
  83
  84 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  85         "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">
  86
  87 where
  88
  89         "-//OASIS//DTD DocBook XML V4.1.2//EN"
  90
  91 is the public, and
  92
  93         "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"
  94
  95 is the system identifier.
  96
  97 The problem is that the system identifier is most probably system-dependent.
  98 To avoid the need to manually fix the system identifiers before building the
  99 documentation, I've decided to use SGML catalogs. If you have your catalogs
 100 set up correctly, xmllint and xsltproc will use them to find the DTDs
 101 based on the public identifiers.
 102
 103 Note that this works only if public identifiers override system identifiers
 104 (i.e. the catalog file must contain 'OVERRIDE YES'). (I had no problem with
 105 these on my system, since the Debian people took care of everything. ;-))