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 in various outputs, 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 bundle 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 the next diagram:

• DITA-OT pre-processing steps

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

• PDF plugin processing steps

  These steps are converting the _merged.xml file to the topic.fo XSL-FO file. They are part of the PDF plugin and all of they are described in the DITA-OT documentation.

  The most important step is transform.topic2fo.main implemented with an XSLT transformation. It takes as input the stage1.xml (an improved version of merged file that contain DITA elements with additional information for TOC or index) file and produces the stage2.fo. This step is important because the majority of PDF customizations are XSLT extensions of this transformation.

• XSL-FO to PDF step

  This step outputs the final PDF file by processing the topic.fo XSL-FO file. There are three XSL-FO processor that you can use in this step:

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

Requirements, before to start writing your own PDF plugin

As you already noticed, there are some technologies that you may want to explore before to start writing your own PDF customization plugin:

• XSLT

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

• XSL-FO

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

  Very good resources to learn XSL-FO are:

  • 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, how to create a PDF plugin. A good starting point can be found here: DITA-OT Customizing PDF output

  Also, whenever you have a problem regarding to the PDF transformation you can browse or put question on the DITA Users List

  Because you are customizing the PDF transformation for DITA documents, you may be interested on the DITA 1.3 specification.