๐ŸŒ˜ Eclipse cheat sheets to DITA to PDFยถ

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 two on the TIOBE Index, this project aims to be an easy to follow tutorial on all the technologies listed.

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.

The running Ant Build is 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 consist 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

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โ€.

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.

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.