Transforms Eclipse cheat sheets to PDF via the DITA Open Toolkit, Eclipse, Apache FOP, Saxon, Apache Ant, XSL, XML

View project on GitHub

Eclipse cheat sheets to DITA to PDF

I worked on the open source Java based project Debrief the leading maritime analysis tool. This project is based on some parts of the document publishing that I did in the Debrief project. The list of resources at the bottom of this README describe the technologies being used.

The original project created a set of DITA XML files and one highly customized PDF and there are a couple of example PDFs that can be seen in the root of this repository. Recently I added support for other output formats that are not customized including HTMLHelp, TocJS and XHTML.

This program runs inside Eclipse, an integrated development environment (IDE) and is mainly a Java based project in that all the code libraries use Java (Apache FOP, Saxon, DITA Open Toolkit, Apache ANT, Eclipse) and it also uses XSL and XML heavily. Using Eclipse allows us to create a publishing pipeline creating all the working output formats one after the other, in one click by building the project. Development was originally done in oXygen XML Editor then ported to Eclipse.

Since Java is now ranked number one on the TIOBE Index, this project aims to be a easy to follow tutorial on all the technologies listed.

Wait until this webpage fully loads and then jump ahead to the various sections in this by using the links below:

The roadmap for this project is to keep the "info.debrief" custom DITA-OT plugin up to date with the latest current version of DITA-OT, in depth instructions on how to get up and running inside Eclipse and lots more.

When built and run this project takes a set of Eclipse cheat sheets and transforms them to PDF. Eclipse cheat sheets are obviously best viewed inside Eclipse. Using PDF allows us to print nicely formatted cheat sheets on paper which allows the user to work through the cheat sheets with a pen and check off each item as they go. Using cheat sheets physically on paper was seen as a new way to learn and was the original concept of the Debrief cheat sheets publishing project I worked on.

Darwin Information Typing Architecture (DITA) is an XML data model for authoring and using DITA-OT you can publish those ideas. The DITA standard is maintained by the OASIS DITA Technical Committee. Some of the largest and most successful companies in the world use DITA. The next link is an informal list of companies using DITA.

It's a two-step process first the DITA XML is created from the Eclipse cheat sheets (XML files) and then you use the DITA-Open Toolkit to create the PDF from the auto created DITA files.

The two parts of the transformation and rendering comprise of:

    • This is the transformation step and it uses cheatsheet-to-dita.xsl which requires an XSLT 2.0 compliant processor.
    • I used the open source product Saxon from Saxonica which came included with the DITA-OT 2.2.1 library.
    • This file takes as input a collection on XML files (Eclipse cheat sheets) and creates multiple output files - a parent DITA Map and some associated tasks.
    • The "output/debrief" and sub "dita" folder contains the dynamically created (transformed) DITA files from this step.
    • This is the rendering (printing) step and the 'info.debrief' custom DITA-OT plugin produces the PDF via the DITA-OT base libraries and a XSL - Formatting Objects Processor (FO Processor)
    • The "output/debrief/pdf" folder contains the resulting PDF output from this step
    • I used Apache FOP 2.1 for the FO Processor

If you are not already Gung-Ho on Java and all things tech, then try a few short online courses:

And then come train in the REAL DOJO and reach your highest potential, become faster, stronger and more powerful......JEDI MASTER LEVEL.....!??!?!!

Yo let's the Star Wars build run on Youtube....BrisVegas Jedi Master Style...

See the build run full screen in 1080p

Build Instructions

The project was originally developed on OS X and the documentation below lists the instructions on how to set up and build the project for OS X.

The Windows build instructions for this project will be soon on this repositories wiki.

Build Instructions Mac OS X

Install Git

On OS X, open your Applications folder, then open the Utilities folder. Open the Terminal application.

OS X terminal

In the terminal type:

git --help

This will either print the usage of the git command if git is already installed, or trigger the Command Line Tools (OS X) for Xcode to install.

After the Command Line Tools are installed go back to the terminal and type:

man git

man git

Use the up and down arrows to navigate through the man page and press 'q' to quit.

You can then type:

which git

which git

You can run the next command after you have cloned this project:

git status

git status

Install Java

First you should check if Java is already installed on your system.

In a terminal type the following commands:


If Java is installed you will see the Java help message like the image below.


If Java is not installed you need to install the Java Development Kit (JDK) as Eclipse needs Java to run so you should first read the Java Platform, Standard Edition Installation Guide

So then go to:

Choose the JDK version for your Operating System.

If it's installed you can read up about Java more by typing:

java -version

java -version

man java

man java

Install Eclipse

Go to: Eclipse Downloads

Eclipse Downloads

In the box near top labelled "Try the Eclipse Installer", click on "64 bit" under "Mac OS X".

Download Eclipse installer application.

You should check the checksum of the Eclipse file you download.

Depending on which type of checksum you choose: MD5, SHA1, SHA-512 the commands are slightly different:

First you should click on the checksum type in the image below:

Eclipse checksums

I used SHA-512 so in a terminal in the directory or folder where you downloaded the Eclipse package to, the command to type would be:

shasum -a 512 eclipse-inst-mac64.tar.gz

eclipse shasum

You should check the output of the shasum command matches what's displayed on the Eclipse website for the type of checksum you choose. You can select the text in the terminal, copy it and then find it on the Eclipse website.

For more information on the shasum or md5 command open a terminal and type:

man shasum

man shasum

man md5

man md5

Use the up and down arrows on the keyboard to navigate through the man page documentation.

To exit from the man pages type: q

Unzip resulting download (eclipse-inst-mac64.tar.gz) by double-clicking on it if downloader did not already unzip it.

Run "Eclipse Installer" application.

Choose "Eclipse IDE for Java Developers" option. (Other options and Eclipse modules are not necessary for this build.)

Eclipse installer

This option allows you to specify an "Installation Folder." The default option may be a folder within your individual directory.

Eclipse Installer install location

It will be more useful to change this and install Eclipse within a directory titled "Eclipse" within the system's main Application directory.

Click on the folder icon to navigate to the Applications directory and create an "Eclipse" target sub-directory before installing.

Applications - Eclipse folder

Eclipse Installer install location

Then click the "Install" button.

You will be presented with the Eclipse Foundation Software User Agreement, so click "Accept Now" after reading it.

Eclipse Foundation Software User Agreement

The installation process may take a few minutes and you will be presented with a green "installing" loading bar style indicator.

Installing Eclipse

When Eclipse has finished installing you will be presented with the "Launch" green button.

Eclipse is now installed

Launch Eclipse for the first time. Doing so will ask you to Select a "workspace." The default option "/Users/[your username]/Documents/workspace" will work fine.

Eclipse select workspace

Quit Eclipse for now.

Install GitHub Desktop

The build's repository is found within GitHub, and the "GitHub Desktop for Mac" application will allow you to clone and work on the build more easily, while retaining a link to the primary source, and thus obtaining updates and having the option to submit modifications which could be candidates for inclusion. GitHub Desktop is currently available for both OS X and Windows.

Go to: GitHub Desktop

GitHub Desktop

Click on the "Download GitHub Desktop" button.

Unzip the resulting file: GitHub Desktop

This expands to: GitHub Desktop

Move this to your system's Applications directory.

Applications directory

Clone the project to your desktop computer

Go to the GitHub repository for this project:

Click on the icon just to left of "Download ZIP" that when you hover your mouse over it, it will display "Save jbampton/eclipse-cheatsheets-to-dita-to-pdf to your computer and use in GitHub Desktop"

Clone my repository

You will be presented with a dialog box that will ask if you want to open the link with GitHub Desktop. The dialog box will look different depending on which web browser you are using. Below is how the dialog boxes look like:

Google Chrome

Chrome dialog

You will need to click launch application.


Firefox dialog

You will need to select "GitHub Desktop" then click "OK"

In the "Clone As:" dialog box, accept the default option, which is to create a clone with the same name as the original: eclipse-cheatsheets-to-dita-to-pdf

Click the "Clone" button.

You will see a progress bar indicating the progress of files being downloaded from GitHub onto your desktop computer, into a local repository directory.

Quit GitHub Desktop.

Install Homebrew and Apache Ant

The project uses Homebrew and I installed Apache Ant inside Homebrew with the Ant Homebrew formula. Towards the bottom of this there is some information on Homebrew usage.

Import project into Eclipse

Launch Eclipse.

In menu bar, choose: File > Import

File import

Then > General > Existing Projects into Workspace -> click "Next"

General -> Existing Projects

You will be presented with the next dialog

Import projects

Click "Browse" next to "Select root directory"

Navigate to the "eclipse-cheatsheets-to-dita-to-pdf" project, which (by default) should be within the "Users/[your user name]/GitHub" directory (or wherever you put it when you cloned it to your desktop).

GitHub folder

This will bring the project into Eclipse.

If you have not already done so, click on the "Workspace" button so that you can view the project.

You must add the JAR files from DITA-OT to Ant inside Eclipse.

Go to Eclipse -> Preferences

Eclipse Preferences

Then -> Ant -> Runtime -> Classpath tab -> click "Global Entries"

Ant Runtime Classpath Global Entries

Then -> click "Add JARs" - you will be presented with the next dialog

Add JARs

Then-> expand 'eclipse-cheatsheets-to-dita-to-pdf' and navigate to "src/libs/dita-ot-2.2.1/lib" and add all the JAR files from that directory. Make sure to click "Apply" and then click "Ok".

Right click on build.xml and select -> Run As -> Ant Build -> (first one)

Run the build

This should run and build all tasks, creating all working output formats in one go.

This process re-creates the DITA XML output in the "output" directory. There should be five DITA files, one parent Ditamap at and 4 task files with the Ditamap at the root of the "output/debrief" folder with task files together in the sub folder "dita"

The final resulting PDF should be called map.pdf and located in the "pdf" folder.

There are currently 4 other output formats (Docbook, HTMLHelp, TocJS, XHTML) as seen by the names of the folders in the "output/debrief" directory. The PDF output is vastly superior to the others which have no customization. The Docbook output is a work in progress.

If you want to choose which output formats to render, you can right click on "build.xml" and select -> Run As -> Ant Build -> (second one).

Ant Build

Then select which output format you would like on the "Targets" tab under "Check targets to execute".

The base target is "xslt2", this creates the DITA-XML files from the input Eclipse cheat sheets (XML). You must have the "xslt2" target checked if you are running any other targets other than "TransformALL"

Finally click "Run".

Ant Edit Config

How DITA-OT PDF Plugins work

Plugins are placed in the DITA-OT plugins directory. You can see the plugin I built in this directory named "info.debrief".

info.debrief plugin location

When ready a plugin must be integrated into DITA-OT using Apache Ant. I built this project using OS X and I installed Ant through Homebrew.

On the command line from inside the root DITA-OT folder it would be -> ant -f integrator.xml

You can also run the integrator inside Eclipse as an Ant build by right clicking on "src/libs/DITA-OT1.8.5/integrator.xml" and selecting -> Run As -> Ant Build (first one) and this should integrate the plugin with the toolkit.

Run DITA-OT integrator inside eclipse with Ant

Every DITA-OT PDF plugin has a file name plugin.xml at its root where you set the configuration values. The plugin id must match the folder name of the plugin. Every plugin has a "transtype" -> this plugins transtype is "debrief". You can see the plugin.xml file and where to set the plugin id and transtype in the next image:


PDF Plugins are comprised of some XML config files, some artwork and some custom XSL (XSLT/XSL-FO/XPath) code DITA-OT provides that base XSL code that you 'override' with your custom work.

The two main files that configure plugins are plugin.xml and integrator.xml which should be in the root of the plugin folder. The "cfg" folder contains the rest of the customization.

Custom XSL can be placed in two XSL files both named "custom.xsl". I placed all the custom code at "src/libs/DITA-OT1.8.5/plugins/info.debrief/cfg/fo/xsl/custom.xsl" for this project. The other file is seen in the adjacent "attrs" directory.


Placing the custom code only in these two files follows best practice techniques on how to build a DITA-OT PDF plugin.

Homebrew usage

Homebrew is an amazing package management system for OS X that installs the stuff you need that Apple didn't.

Homebrew Formula are written in Ruby.

You install Homebrew via the command line as shown in my short Homebrew install video.

If you install Homebrew you should try to run brew update daily.

I made another video on Homebrew which runs for under minute that shows the typical brew update command.

Once you have installed Homebrew you can run through the basic commands below.

Open a terminal and type:

brew -v

brew -v

man brew

man brew

Before using Homebrew you should ensure it's up to date. Run the next command:

brew doctor

brew doctor

brew update

brew update

Example output of running a brew install command. The image shows pouring brews from their bottles

pouring brews

brew list

brew list

List of resources and technologies used on this GitHub project

Eclipse -

Eclipse cheat sheets -

The Apache Software Foundation -

Apache FOP -

Apache ANT -

Saxon XSLT -

Saxon -

Saxonica -

Online community for the Darwin Information Typing Architecture OASIS Standard -


DITA-Open Toolkit -

W3C - The Extensible Stylesheet Language Family (XSL) -

W3C XSLT 2.0 -

XSL Formatting Objects -

XSL-FO Processors -


Adobe PDF -

Adobe Acrobat Reader DC -


Dublin Core Metadata Initiative -

Microsoft HTML Help 1.4 -

The Organization for the Advancement of Structured Information Standards (OASIS) -

oXygen XML Editor -

DITA to TocJS -

DITA-OT installing plugins -

Generate sample DITA-OT plugin -

Creating DITA-OT plugins -

Customizing PDF output -

XSLT FAQ. Docbook FAQ. Braille. -

Homebrew — The missing package manager for OS X -

Install Ant with Homebrew -

Installing Apache Ant -

Codecademy - Learn the Command Line -

Codecademy - Learn Java -

Got 15 minutes and want to learn Git?

Ruby regular expression editor -

Essential programmer training -

Mastering Markdown -

GitHub Desktop -

Microsoft File Checksum Integrity Verifier -

TechSmith Camtasia -

MD5 -

sha1sum -

IDE - Integrated Development Environment -

Git (software) -

man page -

Terminal (OS X) -


The DITA Open Toolkit and Apache FOP are licensed for use under the the Apache Software Foundation License v2.0.

Saxon uses the Mozilla Public License Version 2.0.


Fork and pull request. Simple.