Login | Register
My pages Projects Community openCollabNet

2.1.  System Requirements

[ fromfile: userguide.xml id: systemrequirements ]

Slacker's Docbook is built on top of 100% open source software, and therefore, should work on all platforms. It has been tested on MacOS, Linux and Windows7/XP.

To use Slacker's Docbook to build the documentation, you need to install yourself:

  • Java Developer's Kit, Standard Edition 1.6 or later

  • A full Installation of Python 2.7 including distutils. Warning: pyRXP and therefore these scripts are not yet compatible with Python 3.1.

    On Linux distros, distutils are included in the separately installed python "devel" package, called something like python-dev.

You also need to install the PyRXP library:

[Tip] Installing PyRXP

Includced with Slacker's Docbook is a source tarball of "pyRXP", a Python library. On Linux/Mac, this tarball needs to be extracted, and then from the pyRXP directory, installed via the Python distlibs step as superuser:

  python setup.py install
  

On Windows, with Python 2.7, you can unzip Win32 Python27 dlls of pyRXP into C:\Python27\dll, and that should be sufficient. Builds for other versions of Python are in the same directory on that ftp site.

I've tried to compile pyRXP myself, but to do that, you need to match compiler versions with the people who built your version of Python, and on Windows, that's not always feasible.

Finally, you need the gnu xml libs and tools. In particular, xsltproc, and xmllint, built on the gnu XML libs, available on all *nix platforms, and also as a Win32 binary.

[Tip] Installing xml tools

The 4 Windows XML packages you need for Slacker's Docbook are: iconv, libxml2, libxslt, and zlib. Unzip them into the same place and add that folder to your PATH. On Debian/Ubuntu, a simple apt-get install xsltproc libxml2-utils should be sufficient.

There are other processors available, but since docbook-xml is a very complicated stylesheet, it stretches them to (and sometimes beyond) their limits.

[Tip] Trying to use cygwin?

Let me know how far you get - I keep getting path mismatch problems whenever I try to use non-cygwin versions of Java or Python with cygwin versions of xsltproc. Don't waste your time trying to get this combo working unless you really know what you are doing.

Producing PDF

To build PDF, you need to also install Apache FOP.

Producing EPUB

To build an EPUB version, simply type "ant epub". As part of the build process, it generates HTML and zips it up with the proper file structure and metadata, along with the code examples.

Directory Structure

Here is a tour of the directory structure:

  • doc - contains the source XML documents which were used to generate what you are reading now.

  • bin - contains some executable shell scripts for ant, as well as the python scripts that comprise Slacker's Docbook, the XML docbook generator used for the documentation you are reading right now.

  • lib - Libraries needed by the ant build script or any of the classes it invokes. Also contains tarballs of the docbook stylesheets and pyRXP.

  • doc/uml - some UML diagrams I drew to describe the process of getting from XML to HTML/PDF.

  • settings - some settings and scripts I use on various platforms. You can safely ignore this directory.

  • xsl - a docbook customization layer. Stylesheets: xsl and css files are here. Custom headers/footers can be found in htmlstyle.xsl.

  • icons - Callout graphics, navigation graphics, used by the stylesheets.

  • xsd - W3C XML Schema to describe (and validate) Slacker's Docbook, plus an XML catalog file.

  • www - The web root, also containing generated docbook and HTML files, as well as a copy of many other files in the source tree.

    [Note] Note

    the svn repo has files under revision control in this directory, but that's only because a folder in the svn repo trunk is used for the webspace at http://slackerdoc.tigris.org. You can wipe out this directory and all files should be re-created there on the next rebuild.

Build properties for configuration

There is a file called build.properties in this project.:

build.properties contains variables used by ant and as well as the python XML preprocessor:

Example 2. ../build.properties.sample

#@version@ gets replaced by this in the .xml source:
version=3.3
# example docbook directories on various platforms:
# Fink (Mac OS-x) location:
#docbook.dir=/sw/share/xml/xsl/docbook-xsl/
# Cygwin (Windows) location:
docbook.dir=/usr/share/docbook-xsl
# location of plugin.py - optional plugin extensions path:
plugins.dir=/home/ezust/workspace/oopdocbook/bin


These variables will be substituted for their values inside the XML documentation by using @keyname@ syntax, and they are replaced with their values in Ant build.xml with ${keyname} syntax. The important one is docbook.dir, which must point to the root of the unzipped docbook-xsl tarball (or the system location, if you installed docbook-xsl that way).