asciidoctor-fopdf

asciidoctor-fopdf

DocBook-to-PDF conversion using free software made easy! (based on DocBook XSL and Apache FOP)

Using the asciidoctor-fopdf project, you can convert any DocBook file into a nicely formatted PDF with nothing more than a Java runtime (JVM). All the open source software required to perform the conversion is automatically fetched from the internet the first time you run it.

Doing is believing

Before we get into the goals and the technical details of the project, let’s see the conversion in action!

Prerequisites

The only prerequisite to perform the DocBook to PDF conversion is a Java runtime (JVM) (and, naturally, an internet connection). You can use any recent Java runtime (i.e., Java 6 or better).

If Java is setup correctly, you should be able to type:

$ java -version

or

$ "$JAVA_HOME/bin/java -version"

and see output that looks like:

java version "1.7.0_25"
OpenJDK Runtime Environment (fedora-2.3.10.3.fc17-x86_64)
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)

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

It’s not even necessary to install the Java runtime into your system. Simply set the JAVA_HOME environment variable to the location where you extract the distribution.

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

Retrieve the project

You can retrieve the asciidoctor-fopdf 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

If you want to clone the git repository, simply copy the URL of the repository on GitHub and pass it to git clone command:

$ git clone https://github.com/mojavelinux/asciidoctor-fopdf

Next, change to the project directory:

$ cd asciidoctor-fopdf

Option 2: Download the archive

If you want to download a zip archive, click on the Download Zip button on the right-hand side of the repository page on GitHub. Once the download finishes, extract the archive, open a console and change to that directory.

Next, let’s grab a file to convert.

Generate a DocBook file

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 the sample content below.

sample.adoc

= Document Title
Doc Writer <doc@example.com>

A sample http://asciidoc.org[AsciiDoc] document.

== Introduction

A paragraph followed by a simple list.

* item 1
* item 2

Here's how you say ``Hello, World!'' in Ruby.

.A basic Ruby application
[source,ruby]
puts "Hello, World!"

TIP: asciidoctor-fopdf takes the pain out of converting a DocBook file to a PDF file like this one.
All you need is a Java runtime and this project.
The rest of the software is fetched and configured by Gradle.

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

$ asciidoctor -b docbook -d book -a toc -a numbered sample.adoc

You should now see a file named sample.xml in the current directory.

It’s time to convert it to PDF!

Tip	You could also try these steps using the README.adoc file in the root directory of the project.

Convert DocBook to PDF

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

Warning

The fopdf script is known to work on Unix-based systems. The Windows batch file has been drafted, but not yet tested. Please test it if you can!

$ ./fopdf sample.xml

Important

Since we’re executing a local script, you need to prefix the name of the command with ./ as shown here:

Note	The first time you run the command, it has to retrieve the software from the repositories and setup the conversion application, so be patient.

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.

Figure 1. Sample PDF document rendered in viewer

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.

Motivation

The asciidoctor-fopdf project aims to provide a simple mechanism for converting DocBook to PDF. The plan is to use some form of this project to handle the DocBook to PDF conversion in Asciidoctor. We hope it’s generally useful outside of Asciidoctor as well.

If you’ve ever had to do this conversion, you will appreciate how overly-complex it is. It requires fetching the right combination of software (including the right versions), putting all the files in the right location and associating them together using a catalog and passing in the correct parameters. It’s boring and tedious. This project handles all that magic so you don’t have to.

In addition to making the conversion work, the project includes the following features that are often left out:

• Works with DocBook generated by AsciiDoc (supports all AsciiDoc processing instructions)

• Syntax highlights source code listings using XSLTHL (including a highlighter for AsciiDoc source)

• Scales down images to fit within the width of the page

• Applies (configurable) formatting and styling that’s consistent with the Asciidoctor themes

• Loads and embeds system fonts necessary to support the themes (Arial, Georgia and Liberation Mono)

• Applies configuration to embed SVG-based admonition icons and callout marks

• Works without an internet connection (once the initial run is complete); drastically speeds up execution

• Works from any directory (planned)

There’s a lot of research that went into making all that happen for you :)

Note

One of the most important features of this tool—​and one of the most difficult to get right—​is that it works offline. By default, XSL processors fetch all necessary resources from the internet. Since these files are large and reference many other files, fetching them from the internet is exceptionally slow and a waste of network bandwidth. The fopdf tool carefully ensures that the processor has all the files it needs (on the first run) and thus keeps it from reaching out to the internet while it performs the conversion.

Technical details

Let’s talk tech.

The conversion’s key players: Apache FOP and DocBook XSL

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 fopdf script similar to this one:

$ fop -xml sample.xml -xsl docbook-xsl/fo-pdf.xsl -pdf sample.pdf

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

Source highlighting using XSLTHL

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 fopdf script, you get nice syntax highlighting in your PDF file and happy readers.

Priming the pump with Gradle

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/fopdf directory that the fopdf 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 fopdf 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.

Software versions

Software Project	Version
Apache FOP	1.1
DocBook XSL	1.78.1
Apache Commons XML Resolver	1.2
Xalan	2.6.0
XSLTHL	2.1.0
Gradle	1.7-rc-2

Contributing

In the spirit of free software, everyone is encouraged to help improve this project.

To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.

Feel free to use the issue tracker or Asciidoctor mailing list to provide feedback or suggestions in other ways.

Authors

asciidoctor-fopdf was written by Dan Allen. It builds on prior work done by authors of the AsciiDoc, jDocBook and PressGang projects.

Copyright

Copyright © 2013 Dan Allen. Free use of this software is granted under the terms of the MIT License.

See the LICENSE file for details.