Preface

Explains purpose of this guide, describes the intended audiences, and lists requirements.

This guide provides a quick start for technical writers who are new to both the DITA Open Toolkit and Ant. DITA-OT is first true single-source documentation solution; writers can produce multiple document types from the same XML source files. DITA files are just XML files that conform to the DITA standard. DITA Open Toolkit 1.5 ships with all the DTD and XSD files needed to verify that your DITA-based XML meets the standard. Once you author content that is DITA-compliant, you can include that content in a range of document types.

Ant is a popular build tool used both by software engineers to run software and documentation builds. DITA-OT uses Ant to programatically generate documentation. Most technical writers, and certainly any that write for developer audiences, should learn the basics of Ant. Such an introduction to the tool is beyond the scope of this guide. Rather, the purpose here is to provide just enough working knowledge of Ant to edit and ran DITA-OT builds.

Audience

The primary audience for the guide is technical writers with no experience using the Ant build tool, but have been tasked with evaluating or implementing the use of the DITA Open Toolkit for their organization's documentation. No prior experience with the DITA-OT is assumed.

This audience is assumed, however, to have knowledge of the following technologies:
  • XML
  • XSL
  • DTD
  • XSD

The secondary audience is engineers tasked with providing one or more build scripts for a Technical Publications department. They may already be familiar with Ant, but they do not know which Ant properties are relevant to DITA-OT.

Required Software

  • DITA-OT 1.5 Full Easy Install, available at http://sourceforge.net/projects/dita-ot/
  • A text editor

You do not need to install Ant separately; DITA-OT ships with the required version of Ant.

Guide Overview

The first chapter introduces DITA-OT and Ant and describes when you should consider using the toolkit. The second chapter describes how to edit and write your own Ant build file for documentation projects, provides a reference of Ant properties specific to DITA-OT, and how to generate DITA-based documents from the command line. The third chapter provides tips for debugging transformation errors. A list of recommended practices for writing your build files and a short glossary are also provided.

This guide was written using Notepad++, Gimp2, and DITA-OT 1.5. No proprietary software was used.

Related Documentation

  • DITA Open Toolkit User Guide
  • DITA 1.1 Language Specification
  • Apache Ant 1.7.1 Manual