DITA OT and DITA OT PDF2 Plugin Overview

DITA-OT

DITA-OT is an open-source publishing engine for XML content authored in DITA. It processes a set of DITA files and transforms them into various output formats, including:

• HTML5 or XHTML
• PDF
• Eclipse Help
• Java Help

DITA-OT has an extensible plug-in mechanism that allows you to add your own transformations and customize the default output.

DITA-OT PDF plugin

The DITA-OT processor comes bundled with several plugins, including the DITA-OT PDF plugin. Like DITA-OT, the DITA-OT PDF plugin is implemented in Java, Ant, and XSLT.

The DITA to PDF transformation is a multi-step transformation, as you can see in this diagram:

• DITA-OT pre-processing steps

  The pre-processing steps typically run at the beginning of every DITA-OT transformation. At the end, they produce a _merged.xml file that contains all referenced topics merged into one XML file. You can read more about the pre-processing steps in the DITA-OT documentation.

• PDF plugin processing steps

  The PDF plugin processing phase is a set of steps that convert the _merged.xml file to a topic.fo XSL-FO file. These steps are described in the DITA-OT documentation.

  The most important step is the transform.topic2fo.main process, which is implemented with an XSLT transformation. It processes the stage1.xml file (an improved version of the merged file that contains DITA elements with additional information for the TOC or index) and produces a stage2.fo XSL-FO file. This step is important because the majority of PDF customizations are XSLT extensions of this transformation.

• XSL-FO to PDF step

  This step processes the topic.fo XSL-FO file and converts it to the final PDF output. There are three XSL-FO processors that you can use for this step:

  • Apache FOP - (This is what we used in our customization)
  • Antenna House
  • [RenderX XEP] (http://www.renderx.com/tools/xep.html)

Technologies to understand before customizing your own PDF

There are some technologies that you may want to explore before starting to create your own PDF customization:

• XSLT

  The majority of the PDF processing modules are implemented in XSLT. Also, most of the customizations requires good knowledge of XSLT. See the XSLT 2.0 specification.

• XSL-FO

  As you can see in the diagram above, the last step of the PDF transformation converts an XSL-FO file to PDF output.

  Here are some good resources to help you learn about XSL-FO:

  • XSL, XSL-FO FAQ published on Dave Pawson's site
  • Antenna House XSL&FO Samples
  • XSL Formatting Objects Tutorial published by RenderX
  • XSL-FO specification.

• DITA-OT PDF plugin

  You need to understand how the PDF plugin is organized and how to create one. A good starting point can be found here: DITA-OT Customizing PDF output.

  If you have a problem with the PDF transformation, you can browse or submit a question on the DITA Users List.

  Since you are customizing the PDF transformation for DITA documents, you may also want to consult the DITA 1.3 specification.