The only prerequisite to perform the DocBook to PDF conversion is a Java Development Kit (JDK), which includes the Java runtime (and, naturally, an internet connection). You can use any recent JDK (i.e., Java SE 8 or better).

If Java runtime (JVM) is setup correctly, you should be able to type:

or

and see output that looks like:

If the Java Devlopment Kit (JDK) is setup correctly, you should be able to type:

or

and see output that looks like:

If not, you can install a JDK using your system’s package manager or by downloading a distribution from the Java for developers download site.

Next, you need to retrieve the asciidoctor-fopub project.

You can retrieve the asciidoctor-fopub project in one of two ways:

1. Clone the git repository

2. Download a zip archive of the repository

Option 1: Fetch using git clone

$ git clone https://github.com/asciidoctor/asciidoctor-fopub

$ cd asciidoctor-fopub

Option 2: Download the archive

If you don’t already have a DocBook file, you can generate one using Asciidoctor (or your tool of choice).

To create a DocBook file using Asciidoctor, first create an AsciiDoc file named sample.adoc in the current directory and populate it with the sample content below.

Convert the AsciiDoc file to DocBook using the asciidoctor (or asciidoc) command:

After executing this command, you should now see a new file named sample.xml in the current directory.

It’s time to convert it to PDF!

We’re now ready to do the conversion! It’s as simple as running the fopub script in the current directory on our DocBook file.

On Unix-based systems (e.g., Linux, OSX), run:

On Windows, run:

When it’s all said and done, you should now see the file sample.pdf in the current directory. Open that file with a PDF viewer to see the result.

As you can see, all the details of the conversion are hidden behind the scenes. You get to focus on getting the job done, not worry about the mess that has to be sorted out to use Apache FOP correctly and get a decent-looking document.

Any arguments that follow the source file name are passed directly to the Apache FO processor (fop). This feature allows you to assign XSL parameters, among other things.

Let’s say you want to set the orientation of the PDF to landscape. The DocBook XSL templates recognize the parameter named page.orientation. Here’s how you would pass that through fopub to fop.

You’ll now notice that the PDF generated is rendered in landscape mode.

When you work on many documentations projets in parallel, you will probably need different outputs.

structure

1. One needs a picture in the book title page

2. The other needs a special text at the bottom of this page

style

1. One needs the default Asciidoctor style

2. The other uses the Colony style

In order to work on different documentation projects in parallel, you need to have different docbook-xsl directories.

How it works:

1. Copy the docbook-xsl directory from the fopub install directory to your documentation path, /path/to/custom/fopub.

   

   Figure 2. Content of the docbook-xsl directory

2. Update the files you want in this directory

   For example if you want to use Colony style

   You delete Asciidoctor theme, Foundation theme and you uncomment Colony theme in the common.xsl file.

3. Then you specify this directory when you launch the output generation :

   $ /path/to/fopub/fopub -t /path/to/custom/fopub/docbook-xsl sample.xml

-t <path>

tells fopub which docbook-xsl directory to use (optional, defaults to location inside fopub installation)

-f [pdf|ps|fo|xhtml]

tells fopub which output to produce (optional, defaults to pdf)

-h

prints usage

The main goal of this project is to download, configure and execute Apache FOP to handle the conversion from DocBook to PDF using the DocBook XSL stylesheets. You can see from the first part of the DocBook XSL book what a complex proposition this is.

DocBook XSL

The purpose of DocBook XSL is to provide a standard set of XML transformations (XSLT) from DocBook to several presentational formats, one of which is XSL-FO.

Apache FOP

Apache FOP (Formatting Objects Processor) is a print formatter driven by XSL formatting objects (XSL-FO) and an output independent formatter. It is a Java application that reads a formatting object (FO) tree and renders the resulting pages to a specified output. The primary output target is PDF.

Apache FOP also includes an XSLT processor (Xalan) that handles the conversion from DocBook into the intermediatory XSL-FO format that the print formatter uses to create the PDF.

When the software is all setup, we are ultimately running a command in the fopub script similar to this one:

In reality, it’s more complex. You can see the full command at the bottom of the fopub script.

Readers have come to expect source code to be highlighted so it looks the same way in the document as it does in their source code editors. XSLTHL provides source highlighting for PDF output.

XSLTHL integration is a well-hidden feature in the DocBook XSL project. It requires a Java-based XSLT processor (like the one embedded in Apache FOP) to use it. Activating it requires passing special parameters to the processor that specify the location of the configuration file and a flag to turn it on.

When everything falls into place, as it does with the fopub script, you get nice syntax highlighting in your PDF file and happy readers.

If you have MathML in your DocBook, it will be rendered using the JEuclid plugin for Apache FOP.

Asciidoctor automatically converts AsciiMath to MathML when the asciimath gem is available.

First, install the asciimath gem.

Then, enable the stem attribute when converting to DocBook using Asciidoctor.

Finally, run fopub on the DocBook file as documented above.

Setting up a Java application is no small feat. So what fetches the software and puts it all in the right place? That handywork is performed by Gradle.

Gradle is a Java-based automation and build tool that specializes in setting up Java applications (among other capabilities). Gradle can fetch files from remote repositories, move them around, create start scripts and assemble an application distribution.

We are using Gradle to prepare a Java application into the build/fopub directory that the fopub script can execute.

You may be wondering why Gradle isn’t a prerequisite of this project. The answer is that the Gradle project provides a tool that can bootstrap Gradle from nothing. That tool, gradlew, is included with the project. It gets invoked the first time you run the fopub script. Magic.

And that’s essentially what this project is all about, magic. Converting from DocBook to PDF shouldn’t be hard. We are doing our best to hide those details so that it’s as simple as it should be.