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 On Red Hat systems you need the following packages:
  17 libxml2, libxslt, docbook-dtds, docbook-style-xsl
  18
  19 On Debian you will need these packages:
  20 docbook-xml, docbook-xsl, xsltproc, libxml2-utils
  21
  22
  23 Building the documentation
  24 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  25
  26 Before trying to build the documentation, run
  27
  28   make help
  29
  30 to see all available build targets and make your choice. If something goes
  31 wrong, check the Configuration section of the toplevel Makefile and adjust
  32 the variables.
  33
  34 The documentation and its translations reside in subdirectories.
  35 When building the documentation, the generated HTML files are
  36 placed in subdirectories of the 'HTML' directory.
  37
  38 IMPORTANT: Do NOT place sensitive files under 'HTML'!
  39            It is for generated documentation only.
  40            The whole directory tree is wiped out by the Makefile
  41            when running 'make distclean' or 'make clean'.
  42
  43
  44 Adding new translations
  45 ~~~~~~~~~~~~~~~~~~~~~~~
  46
  47 1) Create a new subdirectory and copy the XML files there. main.xml must not be
  48    copied, it is autogenerated.
  49
  50 2) In each translated file after the <?xml ... ?> tag you must put a note
  51    like <!-- synced with r2 -->, where 2 is the revision of corresponding
  52    English file (see comment at the top of file).
  53
  54 That's all, in theory.
  55
  56
  57 A few words about SGML catalog files
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  59
  60 As far as I know, the document type declaration in XML files requires
  61 both a public and a system identifier. For example:
  62
  63 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  64   "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">
  65
  66 where
  67
  68   "-//OASIS//DTD DocBook XML V4.1.2//EN"
  69
  70 is the public, and
  71
  72   "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"
  73
  74 is the system identifier.
  75
  76 The problem is that the system identifier is most probably system-dependent.
  77 To avoid the need to manually fix the system identifiers before building the
  78 documentation, I've decided to use SGML catalogs. If you have your catalogs
  79 set up correctly, xmllint and xsltproc will use them to find the DTDs
  80 based on the public identifiers.
  81
  82 Note that this works only if public identifiers override system identifiers
  83 (i.e. the catalog file must contain 'OVERRIDE YES'). (I had no problem with
  84 these on my system, since the Debian people took care of everything. ;-))