 | Level: Introductory Bob DuCharme (bob@snee.com), Solutions Architect, Innodata Isogen
08 Jan 2008 The DITA Open Toolkit can transform your DITA files into a wide variety
of output types. When you first install it, it's easy to get the impression that you
need to know Ant well to use it, but you can pack most of its available options into a
single Java™ command line.
Introduction
The Document Information Typing Architecture (DITA) is a set of XML document types for
topic-oriented authoring. DITA also includes a set of mechanisms to create specialized versions of these
document types if you want to customize the DITA DTDs or schemas for a closer fit to the structure of your particular content. As with many standards, part of DITA's appeal is that conforming to it lets you take advantage of commercial and free software built around the standard.
The most popular free DITA software is the DITA Open Toolkit (or "DITA OT"), a Java-based environment for processing DITA files. Once you install it, it can take your DITA XML documents (or, even better, documents that conform to your own customized specializations of the DITA schemas) and create versions in HTML, PDF, RTF, troff, Eclipse Help, and several other formats.
The first time I installed it, I ran the build demo as described in the installation
instructions under "Verifying the installation" (see Resources). I saw all the output formats that it could create from the sample source DITA files, and I was impressed. Then, I must admit, I was at a bit of a loss—the build demo was driven by an Ant script that was over 800 lines long and included another Ant build file that included a dozen more files. My Ant skills are pretty rudimentary, so I had very little idea which parts to pull out into a separate file to do a simple transformation of one of my own DITA documents to XHTML or PDF.
Eventually, I discovered how to tell the DITA OT to convert a particular DITA document to any of its output formats with just a single line at the command prompt, with no need to even look at an Ant script.
What does the DITA Open Toolkit automate?
If you tell an XSLT processor such as Xalan or Saxon "run DITA OT stylesheet whatever.xsl on DITA document mydoc.xml"
it won't necessarily work. You must set several environment variables and identify other
relationships so the pieces of the DITA OT all work together properly. This is
especially important when you use specializations. Suppose the ingredients element in your recipe document type is a specialization
of the DITA prereq element and you ask the DITA OT to make an
HTML version of your recipe. If it can't find any specialized handling for the ingredients element, DITA OT needs to do the necessary lookups to
find out whether it to use the prereq processing on the ingredients element.
The setup for this is much of what the Ant script for the build demo automates, and you
need an Ant script to automate the DITA OT's conversion of your files into the output
formats you need. For Ant novices with no near-term time to upgrade Ant
skills, the good news is that you can automate the creation of the Ant build file as well. If you
tell the dost.jar file of DITA OT which source DITA file to transform and the output format you want, it can do the rest.
Using the dost.jar file
As with most well-behaved jar files, if you start the Java environment with a switch of
-jar, the name of the jar file, and no other parameters, you
can view a list of the parameters that you can supply to dost.jar. There are about thirty, and while it says that only two are required, I've found that you can get away with just one: the name of your input file. When I executed the following command line from the DITA OT's home directory, the toolkit put an XHTML version of currywurst.xml into the default out subdirectory:
java -jar lib/dost.jar /i:C:/temp/currywurst.xml
|
Because the documentation says that both the /i input file parameter and the /transtype translation type parameters are required, I wouldn't assume that XHTML will always be the default value for the latter.
The real fun starts when you supply other arguments for this parameter, like this:
java -jar lib/dost.jar /i:C:/temp/currywurst.xml /transtype:pdf
|
This creates an XSL-FO file from your DITA input file. If you have Apache FOP installed and the right variables set properly as described in the DITA Open Toolkit installation documentation, it creates a PDF file from that—all from this one relatively short command line.
I won't repeat what the documentation tells you about every single command line option,
but I will you something very important for you to gain a full understanding of your
options: While no single DITA Open Toolkit documentation page fully explains all of the DITA OT's command line options, two pages taken together do. "Processing from the Java command line" (see Resources) lists the command line parameters such as /i and /transtype and the equivalent Ant script parameters, and "Ant processing parameters" (see Resources) details what the script parameters do and their default values.
Even then, you won't have a complete list of acceptable /transtype values. But when you provide a bad one as the argument to /transtype, dost.jar responds with a list of acceptable ones:
| Parameter | Creates |
|---|
xhtml
| HTML conforming to the W3C XHTML standard. |
eclipsehelp
| XHTML and accompanying files necessary to provide help for a plugin used with the Eclipse IDE. |
eclipsecontent
| Files that can be installed as an Eclipse plugin so that Eclipse can render the information dynamically. |
javahelp
| Input for the Java help processor. |
htmlhelp
| Input for the Windows HTML help compiler. |
pdf
| XSL-FO and then PDF output using Apache FOP. This is now deprecated in favor of the pdf2 option. |
pdf2
| XSL-FO and then PDF using RenderX's XEP FO
engine and the Idiom plugin. This is only available after you install the FO plugin. You
can reconfigure it to use other processors besides XEP. |
troff
| The troff format, a venerable set of
formatting codes originally developed for AT&T's early UNIX® systems. |
docbook
| XML conforming to the DocBook DTD, a popular standard for technical documentation. |
wordrtf
| The Rich Text Format (from
Microsoft®), a text-based format once popular for interchange in and out of Microsoft's Word word processor. |
| |
If you set up a large, complex production environment that uses the DITA Open Toolkit,
it makes sense to take advantage of everything that Ant has to offer to manage that
complexity. You have to have it installed when you use the DITA OT anyway, so for large
projects it's worthwhile to learn Ant and then build some Ant scripts around the ones
included with the DITA OT. If you're just getting started with the DITA OT, though,
dost.jar is a great way to try out all of the DITA OT's features. Just type a single line at the command line and get quick feedback about the effect of each of the parameters that you can pass to it. Have fun!
Resources Learn
-
Installing the DITA Tookit full package distribution: Install and test the DITA Open Toolkit.
-
Ant processing parameters: Review the details, including valid values, defaults, and usage, in this alphabetical list of Ant processing parameters.
-
Processing
from the Java command line: Find directions and supported parameters to run the Toolkit build code by invoking the Java JVM from the command line rather than invoke Ant.
-
Introduction to the Darwin
Information Typing Architecture (developerWorks; Don Day, Michael Priestley, David Schell; September 2005): Learn what DITA is and how to apply it to technical documentation, such as online help and product support portals on the Web.
-
Frequently Asked Questions about the Darwin Information Typing Architecture(developerWorks; Don Day, Michael Priestley, Gretchen Hargis; September 2005): Find answers, tips, and techniques for the XML-based Darwin Information Typing Architecture (DITA) for documentation.
-
Apache Ant 101: Make Java builds a snap (developerWorks; Matt Chapman; December 2003): In this tutorial, write a build file for a simple Java project, and then look at more other useful Ant functions, including filesystem operations and pattern matching. Also, write your own Java class to add features to Ant.
-
IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
-
XML technical library: See the developerWorks XML Zone for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
-
developerWorks technical events and webcasts: Stay current with technology in these sessions.
- The technology
bookstore: Browse for books on these and other technical topics.
Get products and technologies
-
DITA Open Toolkit sourceforge home page: Transform DITA content (maps and topics) into deliverable formats with this Java-based implementation of the OASIS DITA Technical Committee's specification for DITA DTDs and schemas (useable in the Windows, Linux/UNIX, and Mac OS operating environments).
-
IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
Discuss
About the author | 
| | Bob DuCharme, a solutions architect at Innodata Isogen, was an XML "expert" when XML was a four-letter word. He's written four books and nearly one hundred online and print articles about information technology without using the word "functionality" in any of them. See http://www.snee.com/bob for more and www.snee.com/bobdc.blog for his weblog. |
Rate this page
| |
