Skip to content

Latest commit

 

History

History
160 lines (122 loc) · 6.49 KB

README.md

File metadata and controls

160 lines (122 loc) · 6.49 KB
Raw

Building the User Manual

The user manual is written in XML DocBook format, version 4.2. It uses the official DocBook XSL stylesheets, and will build with versions as old as 1.61.2. (Why these versions? They're what comes with CentOS 3, the oldest system I still use.)

To make the HTML version of the user manual, just type make in this directory. (Or make html if you want to be pedantic.) To make the PDF version of the manual, say make pdf. To make both versions, say make all.

Required Tools

The most likely cause of build failures is not having the right processing programs installed. The DocBook processing model looks like this:

DocBook --[XSLT proc.]-+-> HTML
               ^       |
               |       +-> XSL-FO --[XSL-FO proc.]--> PDF
               |
       {XSL stylesheets}

"DocBook" above is a file in DocBook XML format. In this case, it's in userman.dbx.

There are many alternatives for the tools in the square brackets:

  1. An XSLT processor, which translates XML into other text formats, such as HTML or other varieties of XML.

    We use xsltproc from the Gnome project. There are numerous alternatives, but each supports different extensions to the standard, so it's simplest if everyone uses the same processor for a given document.

    We use the XSLT processor to do two transforms. One is directly to HTML. The other is to XSL-FO, an XML-based page layout language. We do this intermediary transform because XSLT is not good at creating binary formats like PDF.

  2. An XSL-FO processor, which converts XSL-FO to a more directly useful page layout format, like PDF.

    The libtabula user manual build system supports several alternatives.

    The build system relies on a simple script in this directory — fo2pdf — to find an XSL-FO formatter and run it.

    fo2pdf looks first for RenderX's XEP, which comes in a free-as-in-beer version for personal use. If you're in a commercial environment, RenderX wants you to use their commercial trial version which will format this manual without complaint, but it puts watermarks and blank pages into the output. They want $300 for the single-user to get clean output. It's the same as the free personal version, just with a different license. You don't need the higher-end versions of XEP; they don't do anything we need here.

    If fo2pdf can't find XEP, it then looks for Antenna House's XSL Formatter. It's pretty much the same deal as XEP: crippled demo version for testing, and a single-user version for $300. There is no free version for personal use, however.

    Failing all that, fo2pdf falls back to the only free-as-in-speech XSL-FO formmatter, Apache FOP. FOP isn't yet available through most Unixy package download systems, so you'll have to download it directly from the source. The Debian repositories do have it, so on any Debian based distro (e.g. Ubuntu) you can just say sudo apt-get install fop.

    You might be wondering why fo2pdf looks for FOP last, given that libtabula is itself free software and relies on a lot of other free software. It's just that it's a good bet that if there's a commercial FO processor on the system, it was put there quite purposefully by someone who paid (or caused money to be paid) for it, and so wants it to be used. The commercial vendors can still get money for their products because FOP hasn't caught up with them in several important areas. That said, don't feel that you need to go and buy an XSL-FO processor just to build the manuals. We try to always keep the manual in a state where FOP can generate adequate output.

  3. The DocBook XSL stylesheet set.

    The stylesheets are the XSLT processor's rules, controlling how the input XML gets transformed to the output format. The standard DocBook stylesheet set (link below) includes stylesheets for HTML and XSL-FO output. By default, xsltproc looks for these first on your local system, and failing to find them, tries to download them on the fly from the Internet. Because this slows processing quite a bit even if you have a fast Internet connection, and it obviously doesn't work when your net connection is down, we've disabled this option. Therefore, you must have the DocBook XSL stylesheets installed to build the user manual.

    Most Unixy type systems have pre-built DocBook XSL stylesheet packages available:

    • Red Hat/Fedora: docbook-style-xsl RPM package
    • Mac OS X: docbook-xsl Brew package (http://brew.sh) docbook-xsl Fink package (http://fink.sf.net)
    • Cygwin: docbook-xml?? package (?? = DocBook version)
    • Ubuntu/Debian: docbook-xsl, from the standard APT repository

    (Please send the name of the package for your system to the mailing list if it isn't listed above, and I'll add it to the list.)

    If you can't find a package for your system, you can get the DocBook stylesheets from the source. They're a bit tricky to set up correctly, so it's better to use a pre-built package if you can.

If you are still having problems, post the details about it to the libtabula mailing list, and I'll try to help you debug the problem. You might also find the FOP and/or DocBook mailing lists helpful.

DocBook Resources

If you're looking to hack on the manual, here are some helpful resources for getting up to speed on DocBook: