Understanding PDF Transformations

Learning how DITA OT uses the FO plugin to generate PDF documents.

DITA-OT performs PDF transformations differently than other output types. A separate software program, known as XSL formatter, is used to generate the PDF documents. By default, that engine is the FO Plugin, which also uses an Ant build script to generates several files and place them in the directory you specify with the dita.temp.dir property in your script. Several of these files are useful for debugging PDF-related transformation errors. However, the FO Plugin build script also deletes them by default. You can override this behavior by setting the value of the clean.temp ant property in your build script to "no," as shown in the following code snippet.
< property name="clean.temp" value="no"/>
Note: The FO Plugin ant build script is located in the following directory: DITA-OT1.5.3\demo\fo\build.xml.

The following table describes the auto-generated files relevant to debugging PDF transformation errors.

File Name Description


Contains FO processing information related to your index entries.
stage2.fo, stage3.fo Contains FO processing information related to your internationalization files.
buildfile_MERGED.xml Contains all the processing information from the generated files and your content in a format that the FO Plugin can use to generate your PDF file.

Examine the content of these files to determine the cause of PDF transformation errors.

Note: The Apache FOP formatter does not support the indexlist element for PDF. You can try using a different PDF renderer or engine by specifying a different value for the pdf.formatter ant property in the FO plugin build file, or add a topicref element in your build file with that links to a manually-created index file.