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 work well for the author and that the various tutorials and how-to sections are defined in terms of.

The development and maintenance of DITA systems requires the following types of tools:
General DITA development and the tutorials in this book require the following specific tools:

XML-Aware and DITA-Aware Editing Environment

At the time of writing I use the OxygenXML editor as my primary XML development environment and heads-down authoring tool. As of the time of writing, OxygenXML provides unmatched support for DITA 1.2 features. It integrates with the DITA Open Toolkit and is as easy to configure for new DITA vocabulary modules as it is possible for a DITA-aware tool to be. For those reasons I strongly recommend OxygenXML as an XML and DITA development environment. While OxygenXML is a commercial product and is not free, it offers a tremendous value in terms of the features provided. OxygenXML is provided as a standalone tool and as an Eclipse plugin. The two versions of OxygenXML are functionally equivalent and the same license will work for either. I personally use the standalone version of OxygenXML for largely historical reasons and also to avoid having to close down my OxygenXML session when I have to close Eclipse, which is fairly often due to the type of development I typically do.

You can also use Eclipse alone for DITA-aware XML development using Eclipse's various XML-related support components and available plugins. Eclipse can be integrated with the Open Toolkit so that you can run the Toolkit from within Eclipse (see Setting Up Eclipse to Work With the Open Toolkit).

Other XML development environments, such as XML Spy, can of course be used to develop DITA-related components but they do not, at the time of writing, offer the same degree of built-in DITA support or integration with the Open Toolkit as provided by OxygenXML.

Configuring OxygenXML For DITA Development

To make OxygenXML ready for DITA development you need only do one thing after installing the product: Turn on use of external DTDs for determination of document type association. You also have a choice in how you use OxygenXML in relation to the DITA Open Toolkit.

OxygenXML has a general feature by which it can determine the document type associated with a given document, and thereby determine the set of features to use for that document. OxygenXML has built-in DITA-specific features and it will turn those on for any document that it recognizes as being a DITA document, regardless of the specific vocabulary the document uses. It does this by looking for the @ditaarch:DITAArchVersion attribute, which all conforming DITA documents must have and which serves to unambiguously identify a document as being a DITA document.

However, most DITA documents do not literally specify the @ditaarch:DITAArchVersion attribute because it is defaulted in the DTDs and schemas. Thus, in order to recognize a document as a DITA document the document must be parsed with respect to its DTD or schema.

OxygenXML can do this but it does not do it by default, because there is a performance cost in parsing documents in order to then determine what general type of docuemnt they are. So you must turn this feature on in order for Oxygen to automatically process your specialized DITA documents, or even documents that use local document type shells, as DITA document.

To turn this feature on go to Preferences->Document Type Association to bring up the Document Type Association panel. On that panel make sure that the "Enable DTD/XML Schema processing in document type detection" check box is checked and that the "Only for local DTDs/XML schemas" checkbox is checked. Save the new preference settings.

Once you have made this change, OxygenXML will automatically apply to DITA-specific editor features to all DITA documents regardless of specialization.

OxygenXML includes a copy of the Open Toolkit, usually the latest released version current at the time the OxygenXML version is released. The OxygenXML-provided Toolkit includes some small patches to the Toolkit that improve it's interaction with OxygenXML but that are not essential for use of the Toolkit with Oxygen.

OxygenXML uses, or can use, the master entity resolution catalog that is maintained by the Open Toolkit to resolve DITA DTDs and schemas. If you deploy your local shells and specialized vocabulary modules to Oxygen's built-in Toolkit then your DITA documents that use those shells and modules will just work with no additional configuration actions required. Because OxygenXML is fully specialization aware it provides all its out-of-the-box DITA features to all DITA documents once it is able to parse them, which it can do if the DTDs and schemas are resolvable.

OxygenXML's built-in Open Toolkit is in frameworks/dita/DITA-OT below the OxygenXML installation directory.

To ensure that the master Toolkit catalog is being used, go to Preferences->Document Type Association to bring up the Document Type Association panel. Select the entry for "DITA" and select the "Edit" button to edit the document type association. Select the "Catalogs" tab to see the list of associated catalogs. You should see an entry for "${frameworks}/dita/catalog.xml". The string "${frameworks}" is a reference to the OxygenXML-defined variable that resolves to the location of the OxygenXML frameworks directory. If you want Oxygen to use a Toolkit installed at a different location on your computer you can change this setting to reflect the location of that Toolkit.

Depending on your Toolkit needs you have three choices for how to use OxygenXML with the DITA Open Toolkit:
  1. You can use the OxygenXML-provided Toolkit and simply deploy new plugins to it as needed. This ensures that you get full advantage of OxygenXML's patches to the Toolkit. This limits you to the use of the Toolkit version OxygenXML provides out of the box.
  2. You can replace the OxygenXML-provided Toolkit with another Toolkit version in the same location on the file system. This loses the OxygenXML Toolkit patches but means all existing Toolkit-related transformation scenarios and catalog configurations will work without modification.
  3. Use a Toolkit installed elsewhere on your computer and set the value of the dita.dir parameter used in OxygenXML transformation scenarios as well as updating the catalog configuration for the DITA document type association. This preserves the OxygenXML-provided Toolkit but requires changes to any transformation scenarios you want to use with the non-Oxygen Toolkit.

I use option (2) most of the time because I find it easiest and most reliable to have my Toolkit be in an invariant location and use Ant scripts or manual moving and copying to configure that Toolkit instance with whatever I need at the moment. This reflects in part the fact that my daily job involves working with many different Toolkit configurations and versions for specific clients. I find it easier to have a consistent process and supporting scripts (Ant scripts in my case) that swap into the that one location the Toolkit versions and plugins I need for a specific project. It allows me to have exactly one Toolkit location that all my Toolkit-related activities use, removing the chance of accidentally doing things in the wrong location.

If you are working with just one Toolkit version or configuration most or all of the time but you can't use the OxygenXML-provided version for whatever reason (for example, you need to use an older version or newer version of the Toolkit) then option (3) is probably the best practice since you only have to configure the DITA document type association and each transformation scenario once to reflect the Toolkit location. It does mean that you have to remember to change the default value for the dita.dir parameter whenever you create a new DITA transformation scenario.

Setting Up Eclipse to Work With the Open Toolkit

Eclipse is a general development environment that offers many handy features for doing DITA development, including the ability to develop and run Ant scripts. Eclipse includes both an Ant editor for editing Ant scripts and an Ant "view" that makes it easy to run different Ant scripts.

I use Ant scripts from Eclipse mostly for development related activities, such as scripts to manage source code compilation, packaging, and deployment of project components to my local working environment. For example, for all my DITA-related projects I have a standard Ant target that deploys that project's Toolkit plugins to my local Toolkit instance (which is normally the Toolkit that Oxygen uses).

Setting up Eclipse so it can run the Open Toolkit's Ant scripts you can also use Eclipse to run Ant scripts that run the Toolkit. For example, you can create Ant scripts that will run multiple Toolkit transformations on a given input DITA map or process a whole set of documents and then do something with the generated results, such as publish them to a Web site.

To set this up you must add the Toolkit's custom Java JAR files to the list of Jar files that Ant uses when it is run by Eclipse. This does essentially the same thing that the Toolkit's startup.sh and startup.bat scripts do, namely set up the appropriate Java class path so the custom Toolkit Ant processing will work.

You must also configure an ant property that specifies the location of the Open Toolkit on your machine. By convention I call this property dita-ot-dir and that's the name used in all the samples in this book. While you can hard-code this property in the various Ant scripts you use, it's much better to set up your Ant scripts to get the property from a separate configuration file so that you can change it one place. This also makes it easier to do collaborative development of DITA projects where each developer needs to have a different value for the Toolkit location but the scripts are managed in a common code repository.

To set up a property file for defining the dita-ot-dir Ant property, do the following:
  1. Create a file named build.properties or .build.properties your home directory. If you are on a Unix or Linux system, using .build.properties offers more security because the file will be hidden by default, making it safer to hold sensitive values like passwords.
  2. Edit the build.properties file and add a line like this:
    dita-ot-dir=/Applications/oxygen/frameworks/dita/DITA-OT

    Where the value to the right of the "=" is the actual location of the Open Toolkit you want to use on your machine.

  3. In your Ant scripts include these three lines before any other property definitions:
      <property file="build.properties"/>
  <property file="${user.home}/.build.properties"/>
  <property file="${user.home}/build.properties"/>

    These three property file inclusions will look for build.properties in the same directory as the Ant script itself, .build.properties in your home directory, and build.properties in your home directory, in that order. Whichever of these files has the first definition of a given property will set the value of that property. This organization allows you to have global defaults for properties in your user-specific properties file and override those defaults in a project-specific properties file.

To add the Toolkit-related JAR files to Eclipse's Ant configuration, do the following:
  1. Go to Preferences->Ant->Runtime to bring up the Ant runtime settings. Select the Classpath tab.
  2. Select "Global Entries" item in the classpath list. Expand the item to see what JAR files are already listed.
  3. Assuming that the Toolkit's JAR files are not listed, with "Global Entries" selected in the tree view, select "Add external JARs" and navigate to the lib directory underneath the Toolkit installation you want to use (e.g., the Toolkit installed with OxygenXML).
  4. Select all the .JAR files in the lib directory add them to the list under "Global Entries".
  5. Select "Add external JARs" again and navigate down into the saxon directory under the lib directory.
  6. Select all the .JAR files in the saxon directory and add those to the list under "Global Entries".

You may also need to add the two jars "xercesImpl.jar" and "xml-apis.jar", which are part of the Apache Xerces2 Java project. If you don't already have them on your system somewhere, you can download them from http://xerces.apache.org and put them in the lib directory of your Toolkit installation.

With this Ant configuration in place you should be able to run Ant scripts that use the Open Toolkit from within Eclipse.

This Ant script tests the ability to run the Toolkit from Ant:
<?xml version="1.0" encoding="UTF-8" ?>
<project name="dita.build.demo" default="demo.book" basedir=".">
  <!-- Simple Build script to test the ability to call the
       DITA Open Toolkit from Ant.
    -->
  
  <property file="build.properties"/>
  <property file="${user.home}/.build.properties"/>
  <property file="${user.home}/build.properties"/>

  <property name="dita-ot-dir" location="c:\DITA-OT1.5"/>
  <property name="dita.demo.book.dir"
      value="${dita-ot-dir}${file.separator}samples"/>

  <property name="dita.output.demo.book.dir" location="${basedir}/temp/demo"/>

  <target name="demo.book"
    description="build the book demo">
    <mkdir dir="${dita.output.demo.book.dir}"/>
    <ant antfile="${dita-ot-dir}/build.xml"
      target="dita2xhtml">
      <property name="args.input"
        value="${dita.demo.book.dir}${file.separator}taskbook.ditamap"/>
      <property name="output.dir"
        value="${dita.output.demo.book.dir}"/>
      <property name="transtype" value="xhtml"/>
    </ant>
  </target>
  
</project>

To run this script yourself you will need to either create a build.properties file that sets the value of the dita-ot-dir Ant property or change the value in the script itself. (The first definition of a property is the effective value in Ant, so a value for dita-ot-dir set in one of the included build.properties file would take precedence over the value specified in the Ant script itself.

If you want to be able to run this type of Ant script from the command line outside of Eclipse you must either do so from a command window created using the Toolkit-provided startup.sh or startup.cmd script or you must configure Ant's classpath using normal Ant configuration facilities. For this type of configuration there are many possible approaches, all of which are beyond the scope of this book.