Dawid Weiss
ANT & DocBook styler suite
http://www.cs.put.poznan.pl/dweiss/xml/projects/ant-docbook-styler/index.xml
What is it?
File inclusion extension to DocBook allows easier syntax highlighting in JEdit

I started this small project when I needed to render certain documentation in DocBook [outlink] using ANT. Although DocBook is a set of XSLT stylesheets and ANT has a built-in XSLT task, I wanted some more functionality that was difficult to achieve with pure ANT. Specifically I wanted to:

  • Process DocBook using ANT's default XSLT processor in Java if no other options were available, or automatically detect the presence of XSLTPROC processor and use it instead of Java's one. XSLTPROC is much faster at processing XSLT and DocBook's stylesheets are huge, so the gain is significant.
  • Simplify the process of rendering -- I wanted all resources, such as figures or CSS stylesheets, to be copied automatically to the destination folder.
  • I wanted certain level of customization to the default DocBook, namely, inclusion of XML files using extension XML elements, not entity inclusion mechanism. In such approach, each chapter or section can be a separate file and all files can have their own DTD headers -- a neat thing if you're using an XML editor with syntax helpers (such as JEdit, see figure on the right).
  • Capability to render to various formats using one script and one set of ANT tasks -- HTML, HTML chunked into sections, PDF... all these are simple to use with the styler package (although at a price of limited customization capabilities).
  • I also changed some of the default docbook CSS stylesheets so that the rendered documentation looks... well, it seems nicer to me at least. The same applies to XSL:FO customization layer.
How to use the package?
  1. Download and unzip the styler to some directory.
  2. You can try if all the required Java elements are installed on your machine by going to example folder and starting the build script there (simply type ant). You should see some information on the console about the fact that DocBook stylesheets are being unpacked, then the example documentation should be rendered to tmp folder.
    Buildfile: build.xml
    
    test:
    
    clean:
        [mkdir] Created dir: F:\tmp2\example\tmp\build
        [mkdir] Created dir: F:\tmp2\example\tmp\chunked
    
    check.required-properties:
    
    xsltprocessor:
         [echo] xsltproc available: true
    
    displayXsltProcessorInfo:
         [echo]
         [echo]
         [echo] #####################################################
         [echo] XSLTProc has been found in your path and will be used
         [echo] for processing XSLT transformations. If you experience
         [echo] any problems, you can switch to Java's default XSLT
         [echo] processor by defining 'disable.xsltproc' property.
         [echo] #####################################################
         [echo]
         [echo]
    
    check.expand.zips:
    
    expand.zips:
         [echo]
         [echo]     #####################################################
         [echo]         UNPACKING OR UPGRADING DOCBOOK DISTRIBUTION
         [echo]     #####################################################
         [echo]
        [unzip] Expanding: F:\tmp2\docbook\docbook.zip into F:\tmp2\docbook
        [touch] Creating F:\tmp2\docbook\docbook.zip.tstamp
    [...]
    Sample output from the styler example
  3. The styler does not come with an XSLT processor -- it is preinstalled in newest JDK versions. XSLTPROC can be found here. [outlink]
  4. To use the styler in your own projects, modify the example ANT script -- it is the simplest way. In general, the styler is invoked as an external ANT script's task using the following code:
    <ant antfile="${ant.docbook.styler}" inheritall="false"
         target="html.single">
         <property name="docbook.xml.dir" location="xml" />
         <property name="docbook.resources.dir" location="figures" />
         <property name="distribution.dir" location="tmp/single" />
         <property name="build.dir" location="tmp/build" />
    </ant>
    ANT code to invoke the styler.
    Of course you should replace variables such as ${ant.docbook.styler}, xml or figures with paths appropriate in your project. See the header of the styler ANT file for customisation properties.
Download the styler

Download the styler as a ZIP package here: ANT-DocBook-Styler downloads directory

Updates history:

  1. (25/05/2004) Added PDF generation capabilities to the styler. The PDF is generated using Apache FOP. The PDF generation is a separate download -- a module to extract over an existing installation of the styler.
  2. (15/05/2004) Some minor fixes that remove external DTD links, which caused the script to fail on computers with no network access. Also, some clarifications in the readme file.
  3. (19/03/2004) Greatly refactored new release. Thanks to Matthias Marschall, this time DocBook Website stylesheets are also compressed and auto-unpacked. Folders structure has been redesigned, so that new styles can be easily added. Enjoy.
  4. (16/02/2004) Problem with catalogs in Windows has been hopefully solved. Also, added "--nonet" option so that XSLTPROC doesn't resolve external dependencies.
  5. (31/10/2003) A bug fixed in XsltProcLiaison class that caused weird bugs under Linux.


(c) Dawid Weiss. All rights reserved unless stated otherwise.