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.

Back to top

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.

Back to top

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:

Share this... Digg this story Post to del.icio.us Slashdot it!

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

• 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.
  
  

• 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.
  
  

• Participate in the discussion forum.
  
  
• DITA-Users mailing list: Join this group for discussions on technical issues related to all DITA users.
  
  
• XMetal users DITA mailing list: If you do DITA work with the XMetal editor, see this group for discussions about the use of this tool with DITA applications.
  
  
• FrameMaker users DITA mailing list: Join this group to discuss issues related to DITA work with the FrameMaker editor.
  
  
• XML zone discussion forums: Participate in any of several XML-related discussions.
  
  
• developerWorks blogs: Check out these blogs and get involved in the developerWorks community.

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.

原文链接: http://www.ibm.com/developerworks/library/x-tipditajavacmd.html?S_TACT=105AGX54&S_CMP=B0114&ca=dnx-801