Makefiles

You may have noticed that processing DocBook with the XSL stylesheets may require several steps and options. If you have to run the commands often, you can save typing by using a make utility to execute the commands for you. If you are familiar with the Java Ant utility, you can use it instead for similar purposes.

A Makefile is like a script or batch file, but it can have several make "targets" to run different command sequences from the same file. It can also track which files are dependent on others and process them in the right order. To use make effectively, you will need to read its documentation. The make utility is generally available on Linux and UNIX systems. It can be installed in Cygwin on Windows as well.

A very basic Makefile for automating the use of xsltproc and FOP might look like this:

html:  
         xsltproc  \
            --output  myfile.html  \
            ../docbook-xsl-1.68.1/html/docbook.xsl  \
            myfile.xml

pdf:   
         xsltproc  \
            --output  myfile.fo  \
            ../docbook-xsl-1.68.1/fo/docbook.xsl  \
            myfile.xml

         fop.sh  -fo  myfile.fo  -pdf  myfile.pdf
        

The words html and pdf are make targets, while the indented lines are the commands that are executed if that target is selected. There are tab characters indenting the commands, and you must use tabs, not spaces. Once this file is set up, you can generate your HTML output by just typing make html, and your PDF output by typing make pdf.

A more complete example uses make variables and dependencies:

XSLSTYLE=../docbook-xsl/html/docbook.xsl
%.html:  %.xml 
        xsltproc  --output  $@  $(XSLSTYLE)  $<

html:  myfile.html

This example has these features:

An alternative to Makefiles is Apache Ant, which is written in Java so it runs on all platforms. It is described at http://ant.apache.org/. For help in using Ant with DocBook, see Dave Pawson's article Docbook and Ant.