doc/HOWTO.DocBook

   1 HOW-TO:  Compiling Subversion DocBook XML Documents
   2 ===================================================
   3
   4 The Subversion project uses for some of its documentation DocBook
   5 Lite, a scaled-down version of the DocBook DTD, used by O'Reilly &
   6 Associates.
   7
   8 The goal of this document is to give simple instructions to anyone who
   9 wants to compile Subversion DocBook documents into a useful format,
  10 like HTML or PDF.  It should state *exactly* which tools to use, and
  11 how to invoke them, in simplest terms.
  12
  13 Table of Contents:
  14
  15   I. PRIMER
  16  II. COMPILING THE DOCS
  17 III. HACKING ON THE DOCS
  18
  19 I. PRIMER
  20
  21   DocBook has a tortured, confusing history.  Before you do anything,
  22   take a look at Eric Raymond's excellent "DocBook Demystification HOWTO":
  23
  24      http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/
  25
  26   It's very short and clears up many things.
  27
  28
  29 II. COMPILING THE DOCS
  30
  31
  32 1. Fetch XSL stylesheets for DocBook and place them in tools/xsl
  33
  34    The "DocBook Open Repository" on Sourceforge has a large collection
  35    of XSL stylesheets that specifically operate on DocBook.  Download
  36    and install the latest 'docbook-xsl' package from this page:
  37
  38       http://sourceforge.net/project/showfiles.php?group_id=21935
  39
  40    Download the latest version of docbook-xsl, unpack it, then rename
  41    the unpacked directory to tools/xsl, something like this:
  42
  43       $ cd doc/book/tools
  44       $ tar zxvf docbook-xsl-X.YY.Z.tar.gz
  45       $ mv docbook-xsl-X.YY.Z xsl
  46
  47    The default build process expects the stylesheets to be in
  48    tools/xsl/.
  49
  50
  51 2. Use XSLT to transform the documents.
  52
  53    XSLT applies an .xsl stylesheet to an .xml file, and produces some
  54    new markup document.
  55
  56    * Get libxslt, a C library for XSLT, from http://xmlsoft.org/XSLT/.
  57      (If you're having trouble finding a source package to compile,
  58      try ftp://archive.progeny.com/GNOME/sources/libxslt/1.0/.)
  59      Install it:
  60
  61         $ tar zxvf libxslt-1.0.22.tar.gz
  62         $ cd libxslt-1.0.22
  63         $ ./configure
  64         $ ./make
  65         # make install
  66
  67      (Note: you may discover that you need to install libxml2 first.
  68      Find it at ftp://archive.progeny.com/GNOME/sources/libxml2/)
  69
  70      If you don't want to compile libxslt, you can just fetch the
  71      appropriate OS binary package.
  72
  73    * From this directory, do
  74
  75         $ make all-html
  76
  77      This produces an HTML version for the Subversion DocBook docs in
  78      misc-docs/svn-misc-docs.html.
  79
  80
  81 3. Make a PDF file.
  82
  83    Formatting Objects (FO) is a layout language, kind of like
  84    postscript, dvi or css.  People are quickly standardizing on it.
  85
  86    * Fetch FOP, a java program which converts .fo files into PDF:
  87
  88         http://xml.apache.org/fop/index.html
  89
  90      There are approximately 17577 ways to install FOP.  Rather than
  91      describe them all, we will recommend one way.  If you've already
  92      installed FOP some other way, that's fine, then you can ignore
  93      the following recipe:
  94
  95         1. Download the latest version from
  96            http://www.apache.org/dyn/closer.cgi/xml/fop, for example,
  97            fop-0.20.5-bin.tar.gz.  Just get a binary distribution,
  98            there's no need for the Java source.
  99
 100         2. Unpack it into tools/fop/
 101
 102            $ cd doc/book/tools
 103            $ tar zxvf fop-0.20.5-bin.tar.gz
 104            $ mv fop-0.20.5 fop
 105
 106      That should be enough.  The Makefile will actually invoke
 107      tools/bin/run-fop.sh.  That script attempts to find FOP already
 108      installed on your system, but falls back to the FOP unpacked into
 109      tools/fop/ if there's no other FOP available.
 110
 111      Of course, to run FOP at all, you also need a Java runtime
 112      environment.  Try java.sun.com or www.blackdown.org if you don't
 113      already have that.
 114
 115      Sometimes building the DocBook documents can use more memory than
 116      Java is willing to allocate by default, and you may need to increase
 117      the default heap size.  With Sun's JVM, this is accomplished by
 118      passing the arguments "-Xms100m -Xmx200m" (known to work with
 119      versions 1.2.x-1.4.x, and likely different for JVMs from other
 120      vendors).  To tell fop.sh about these arguments, pass them via
 121      the environment variable FOP_OPTS (which is also configurable in
 122      your ~/.foprc).
 123
 124         $ export FOP_OPTS="-Xms100m -Xmx200m"
 125
 126    * If you want images to be included in the PDF, you'll need to use
 127      the JIMI image processing library.  Grab the latest release from
 128      http://java.sun.com/products/jimi/, then cp the jar file into the
 129      same place as the FOP jar files:
 130
 131         $ cd doc/book/tools/
 132         $ tar zxvf jimi1_0.tar.Z
 133         $ cp Jimi/examples/AppletDemo/JimiProClasses.jar fop/lib/
 134
 135      Poof!  You now have PNG support.
 136
 137    * From this directory, do
 138
 139         $ make pdf
 140
 141      This produces PDF for the Subversion DocBook documents in
 142      misc-docs/svn-misc-docs.pdf.
 143
 144
 145 III. HACKING ON THE DOCS
 146
 147 In addition to everything in section II:
 148
 149
 150 1. Get a nice editing environment for SGML/XML.
 151
 152    This isn't strictly required, but it's nice when your editor
 153    colorizes things, understands the DTD, tells you what tags you can
 154    insert, etc.
 155
 156    If you use emacs, we recommend the PSGML major-mode.  Most free
 157    operating systems package it, or its home page is here:
 158
 159          http://www.lysator.liu.se/projects/about_psgml.html
 160
 161    If you use vim, you might check out xmledit, at:
 162
 163          http://www.vim.org/scripts/script.php?script_id=301
 164
 165
 166 2. Get a validating parser.
 167
 168    Actually, if you have what you need to compile the documentation,
 169    then you almost certainly have an XML validator installed already -
 170    it is called xmllint, and comes as part of libxml2.
 171
 172    The makefile is preconfigured with a suitable invocation of it,
 173    so simply run:
 174
 175       $ make valid
 176
 177
 178 3. Read about the DocBook lite tags.
 179
 180    The tools area contains the readme-dblite.html file which describes
 181    how to write with DocBook Lite.  Familiarize yourself with these
 182    tags before changing the docs.