DITA Processing in the Open Toolkit

...or, What's all that scrolling through the command window when I run a build?

Short explanation

When you run a build in the DITA Open Toolkit, a lot of processing goes on before your topics are built to XHTML, PDF, or your favorite output format. A big chunk of that processing is collectively known as the "preprocess" step; most DITA builds consist of the common preprocess, followed by output specific processing. For example, a build to XHTML runs the preprocess, followed by a final rendering step to convert each topic to XHTML. A build to Eclipse XHTML runs the preprocess, followed by that rendering step and a step to create Eclipse indexing and navigation. During the preprocess steps, your files are copied to a temporary directory and modified several times.

Detailed explanation

The following steps take place during the typical preprocessing stage. If you know that you do not use some aspects of DITA processing, such as inline linking, it is possible that you could skip those stages to optimize your process. Note that in many cases the order is significant; changing the order may produce different results. Also note that this information is not yet considered complete (we are actively updating this info for DITA-OT 1.5):

• Generate file lists - these lists determine what files are used by the following steps
• Filter based on ditaval and insert debug information; updated files are placed in the temp directory
• Evaluate conref push in maps and topics (new for DITA-OT 1.5)
• Evaluate conref in maps and topics
• Move metadata from maps to topics
• Evaluate keyref (new for DITA-OT 1.5)
• Pull in <coderef> references (new for DITA-OT 1.5)
• Evaluate references from one map to another; merge to a single map
• Mappull step - pull metadata into the map (updated titles, short descriptions)
• Chunking - process both the map and the topic to resolve chunk commands
• Maplink step - generate links based on the map - navigational, reltable, etc. Makes use of the updated titles and short descriptions pulled in with mappull.
• Move generated links into referenced topic
• Topicpull step - resolve references within topics. For example, resolves link text for in-line cross references that were specified without text. Runs on every topic.

After the preprocess, processing branches based on the selected output type. XHTML processing converts every individual DITA file to XHTML, and may convert the map to some form of navigation. PDF processing merges all of the DITA content into a single file with the "topicmerge" process, and then converts that file to XSL-FO for rendering with your favorite FO processor. Other output formats may make use of the merge or XHTML process, and may add their own additional steps to generate entirely new formats.