DITA Open Toolkit Architecture

The DITA Open Toolkit is an open source implementation of the OASIS DITA Technical Committee's specification for Darwin Information Typing Architecture (DITA) DTDs and schemas. The toolkit is a major upgrade from its predecessor, the developerWorks version known as "dita132." The toolkit uses open source solution of ANT, XSLT (currently 1.0) and Java to implement transformation functions from DITA content (maps and topics) into different deliverable formats

Pipeline structure

There are 2 stages of transformation,

Pre-processing
Main transformation

The whole process works like a pipeline. The pipeline input is DITA map, DITA XML files and property files. And the pipeline output is XHTML, Eclipse help, PDF, JavaHelp, etc. depending on what output user selects. The pipeline consists of various modules which performs different functions. Interface between modules are files in different format. Here is the overview chart of the two-stage transformation.

The whole pipeline is now controlled by one major Ant script named 'conductor.xml'. Pipeline modules are implemented using Ant tasks, XSLT stylesheet or a Java Program. Most modules are implemented using XSLT stylesheet. For those modules in the pipeline which are impossible or very difficult to be implemented using XSLT stylesheet and Ant tasks, we choose to use Java to implement them.

Ant script

There are four main Ant script files in DITA-OT. The relationship of the files is illustrated as below.

Conductor.xml acts as the interface that user customized Ant script can call the targets in it.

Table 1. Targets in conductor.xml
Target Name	Usage
dita2pdf	Transform DITA to PDF output (need FOP)
dita2docbook	Transform DITA files to DOCBOOK
dita2xhtml	Transform DITA to XHTML output
dita2javahelp	Transform DITA to Java help output (based on HTML and need Java help builder)
dita2eclipsehelp	Transform DITA to eclipse help output (based on HTML)
dita2htmlhelp	Transform DITA to HTML help

Conductor.xml calls the targets in the following three Ant script files.

Pretargets.xml contains all the targets that run in the preprocess.

Ditatargets.xml contains all the targets that run in the main transformation.

Catalog-Ant.xml contains the xml catalog in Ant's style which is used by Ant.

XSLT modules

Here is the XSLT modules structure.

The shell xsl files act like an interface for users or for Ant to call. All of the shell xsl files lies in xsl directory. They are dita2docbook.xsl, dita2fo-shell.xsl, dita2html.xsl, dita2xhtml.xsl, topic2fo-shell.xsl and map2docbook.xsl.

The xsl files which are responsible for Implentation and specialized transformation are in the following directories under xsl directory.

Table 2.
Directory Name	Specification
xslhtml	Contains the files that implement the transformation to html
xslfo	Contains the files that implement the transformation to XSL-FO
docbook	Contains the files that implement the transformation to docbook

Implementation files are responsible for transforming normal elements and specialized transformation files are responsible for transforming elements which are only specified in different domains.

Common utility is contained in common directory under xsl directory. It provides common function that will be called in transformation to each output such as output error message, convert string to lower or upper case and convert specified string to different language.

Other xsl files in the xsl directory

Table 3. Other xsl files
File Name or Directory Name	Usage
generalize.xsl	Generalize a DITA topic file. For example, making a concept file back to topic file.
normalize.xsl	Make the hidden attributes, such as class attribute, appear in the topic file.
pretty.xsl	The reverse action to normalize.
specialize.xsl	The reverse action to generalize.
topicmerge.xsl	Merge the ditamap and topic files into one big topic file. (Used in transforming a ditamap to PDF)
map2eclipse.xsl	Transform the ditamap file to table of content file in eclipse help output.
map2hhc.xsl	Transform the ditamap file to hhc file in HTML help output.
map2hhp.xsl	Transform the ditamap file to hhp file in HTML help output.
map2htmtoc.xsl	Transform the ditamap file to the table of content file in XHTML output.
map2JavaHelpMap.xsl	Transform the ditamap file to jhm file in Java help output.
map2JavaHelpTOC.xsl	Transform the ditamap file to table of content file in Java help output.
preprocess (directory)	This directory contains the xsl files that used in preprocess as preprocess modules.

Java modules

Java modules are organized loosely by a Java class named 'PiepleFacade' which acts as an interface to enable modules can be called from command line, another Java program or Ant script.

Here is a detail description of how a GenList module in the preprocessing stage is implemented in Java