This README explains how to convert "teams-and-tools.xml" to an HTML or PDF file. Although it is a chapter in a book ("Beautiful Teams", O'Reilly Media, 2008, http://beautifulteams.oreillynet.com/), it is written using the DocBook "article" DTD, so it can also stand alone. Docbook has a tortured, confusing history. Before you do anything, take a look at Eric Raymond's excellent "Docbook Demystification HOWTO": http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/ It's very short and clears up many things. You'll need a tools/ subdirectory containing various XML build tools. I don't keep that under version control here, but you can grab one from http://svn.red-bean.com/repos/producingoss/trunk/tools/. Compiling --------- 1. Fetch XSL stylesheets for Docbook and place them in tools/xsl The "Docbook Open Repository" on Sourceforge has a large collection of XSL stylesheets that specifically operate on Docbook. Download and install the latest 'docbook-xsl' package from this page: http://sourceforge.net/project/showfiles.php?group_id=21935 Download the latest version of docbook-xsl, unpack it, then rename the unpacked directory to tools/xsl, something like this: $ cd tools $ tar zxvf docbook-xsl-X.YY.Z.tar.gz $ mv docbook-xsl-X.YY.Z xsl The default build process expects to the stylesheets to be in tools/xsl/. 2. Use XSLT to transform the book. XSLT applies an .xsl stylesheet to an .xml file, and produces some new markup document. * Get libxslt, a C library for XSLT, from http://xmlsoft.org/XSLT/. (If you're having trouble finding a source package to compile, try ftp://archive.progeny.com/GNOME/sources/libxslt/1.0/.) Install it: $ tar zxvf libxslt-1.0.22.tar.gz $ cd libxslt-1.0.22 $ ./configure $ ./make # make install (Note: you may discover that you need to install libxml2 first. Find it at ftp://archive.progeny.com/GNOME/sources/libxml2/) If you don't want to compile libxslt, you can just fetch the appropriate OS binary package. * From the book directory, do make all-html This produces a monolithic HTML version in book.html. 3. Make a PDF file. Formatting Objects (FO) is a layout language, kind of like postscript, dvi or css. People are quickly standardizing on it. * Fetch FOP, a java program which converts .fo files into PDF: http://xml.apache.org/fop/index.html There are approximately 17577 ways to install FOP. Rather than describe them all, we will recommend one way. If you've already installed FOP some other way, that's fine, then you can ignore the following recipe: 1. Download the latest from http://www.apache.org/dyn/closer.cgi/xml/fop, for example, fop-0.20.4-bin.tar.gz. Just get a binary distribution, there's no need for the Java source. 2. Unpack it into tools/fop/ $ cd tools $ tar zxvf fop-0.20.4-bin.tar.gz $ mv fop-0.20.4 fop That should be enough. The Makefile will actually invoke tools/bin/run-fop.sh. That script attempts to find FOP already installed on your system, but falls back to the FOP unpacked into tools/fop/ if there's no other FOP available. Of course, to run FOP at all, you also need a Java runtime environment. Try java.sun.com or www.blackdown.org if you don't already have that. Sometimes building the book can use more memory than Java is willing to allocate by default, and you may need to increase the default heap size. With Sun's JVM, this is accomplished by passing the arguments "-Xms100m -Xmx200m" (known to work with versions 1.2.x-1.4.x, and likely different for JVMs from other vendors). To tell fop.sh about these arguments, pass them via the environment variable FOP_OPTS (which is also configurable in your ~/.foprc). $ export FOP_OPTS="-Xms100m -Xmx200m" * If you want images to be included in the PDF, you'll need to use the JIMI image processing library. Grab the latest release from http://java.sun.com/products/jimi/, then cp the jar file into the same place as the FOP jar files: $ cd tools/ $ tar zxvf jimi1_0.tar.Z $ cp Jimi/examples/AppletDemo/JimiProClasses.jar fop/lib/ Poof! You now have PNG support. * From the top directory, run 'make' to produce an HTML file. For PDF or PostScript, run 'make pdf' or 'make ps' respectively.