Introducing Document Generation

Learning the mechanics of document generation with DITA OT.

Your documentation project uses an Ant build script, which calls a target in another Ant build script in the DITA-OT root directory, which imports another Ant build script, which itself imports several more Ant build scripts. Sound confusing? This topic explains this interaction and explains how to identify targets in these scripts related to errors in your document generation.

Each target in the build script for this Quick Start Guide contains the following code snippet.

<ant antfile="${toolkit_dir}/build.xml" target="init">

The toolkit_dir directory is the root directory where you installed DITA-OT.

The build file you should understand is build.xml, located in toolkit.dir. The Ant targets defined and imported into this script are the same targets that you see on the console as your build script runs.

DITA-OT Build Script	Description
`build_init.xml`	starts the document transformation, initializes the DITA-OT logger, verifies that the toolkit can locate the files and directories that you specified in your build file, and prints these values to the console and the log file, if you have specified one.
`build_preprocess.xml`	Validates your content files, generates lists of input files, including internal elements distributed across all content, such as index and conref entries. Moves copies of these files and elements into the the directory specified by `output.dir` property in your build script.
`build_general.xml`	Generates XHTML and HTML output from your input files.
`build_dita2wordrtf.xml`, `build_dita2xhtml.xml`, `build_dita2eclipsehelp.xml` `build_dita2javahelp.xml`, `build_dita2htmlhelp.xml`, `build_dita2pdf`	Generate output-specific content from your content files.

Your console displays the name of each Ant target called inside the build scripts, including the output-specific script. For example, the following screen shot displays the names of Ant targets contained in the output-specific build_dita2pdf.xml script.

When you see an error in the output, you should read the Ant target that generated it for clues to solve the problem. To learn more about what caused the INFO, SEVERE, and WARNING errors in the image above, you should read the transform.fo2pdf.fop Ant target to learn what the Toolkit was doing when the error occurred and which xsl file generated the error.

Note: The DITA-OT build scripts sometimes continue to run even if they are unable to generate a temporary file for one of your content files. The build later displays an error message stating that a DITA-OT build script cannot find a generated file. This error is often misleading; the problem may be that your content file contains an error other than XML validation, which would stop the DITA-OT build from proceeding.

DITA-OT uses a separate set of Ant targets to process your PDF if you specify a value for the args.fo.userconfig property in your document's build script. See Ant Properties for DITA-OT for more information about this property.