Setting Up Your Development Environment

There are many ways to set up a productive DITA development environment. This chapter describes a set of tools that works well for me, and which I use in describing the tutorials and how-to sections in this book.

The development and maintenance of DITA systems requires the following types of tools:

An XML-aware editing environment for working with DITA documents, DTDs, XSDs, XSLT, XQuery, and other XML-specific artifacts. This book recommends the SyncRO Soft OxygenXML product for the simple reason that it offers the most functionality at the lowest price, reflects excellent engineering quality, excellent service, and the most complete DITA implementation of any authoring environment at the time of writing.
A Java development environment for compiling and deploying Java code (optional). Many DITA systems never require the implementation of custom Java code but it can still be useful to be able to examine or modify the Java code that underlies the Open Toolkit. If you are integrating with a component management system you will likely need to write custom Java code. This book uses the Eclipse IDE, although similar systems, such as NetBeans, are comparable. Eclipse and similar tools can be useful simply as a way to run and manage Ant scripts even if you do not do any Java development.
A Web browser.
Output-specific viewers, including PDF readers, EPUB readers, Windows help viewers, etc.
A source code control system, such as Subversion, GIT, or VCC, for managing your project’s source components. A source code control system can manage DITA content quite effectively.
Note: You should not use CVS with DITA content because it cannot handle Unicode documents properly (CVS is ASCII only).

General DITA development and the tutorials in this book require the following specific tools:

A Java development kit (SDK), which is required by the DITA Open Toolkit and Java development. At the time of writing the latest Java version is Java 7, but Java 6 is the minimum version required by most of the tools you will be using. You should use Sun (Oracle) Java, as some tool components will not work with other Java distributions.
The DITA Open Toolkit. Even if your system does not use the Toolkit itself, it is still useful for testing and validating DITA processing. The DITA Open Toolkit is the only free, open-source, and cross-platform general-purpose DITA implementation and serves as a reference implementation for the DITA standard (while it is not a product of OASIS or the DITA Technical Committee, the Open Toolkit developers coordinate with the Technical Committee so that new DITA features are implemented as quickly and correctly as possible upon final or near-final approval of new versions of the DITA specification). Many commercial DITA-related tools integrate the Open Toolkit. Even if the Toolkit will not be your primary processing environment, it is still useful for testing and managing access to document type shells and specialization vocabulary modules . You should expect to use the Toolkit for that purpose if for no other.
Apache Ant. Ant is a general-purpose scripting system used to manage the building and deployment of software projects. It is used by the DITA Open Toolkit and is generally useful for lots of tasks. While Ant is included in the main Open Toolkit package, it is useful to have a separate standalone copy.