- Project tools
- How do I...
|Over 500 more tools...
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
You also need to install the PyRXP library:
|| 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,
xmllint, built on the gnu XML libs, available on
all *nix platforms, and also as a
|| Installing xml tools
The 4 Windows XML packages you need for Slacker's Docbook are:
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.
|| 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.
To build PDF, you need to also install Apache FOP.
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.
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
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.
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:
# example docbook directories on various platforms:
# Fink (Mac OS-x) location:
# Cygwin (Windows) location:
# location of plugin.py - optional plugin extensions path:
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
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).