Installing the DITA Open Toolkit

This topic explains how to install the DITA Open Toolkit processing environment.

Installing DITA-OT Full Easy Install package in Windows

The software that DITA-OT depend on are redistributed. The Full Easy Install package of DITA-OT after 1.3 includes the software, so the configuration process is streamlined.

Before installing DITA Open Toolkit full distribution, you need to complete the following steps:

  • Download and configure JRE properly.
  • (Optional) Download and configure HTMLHelp Compiler properly for HTMLHelp transformation.
  • (Optional) Download and configure JavaHelp Compiler properly for JavaHelp transformation.

Then, you need to complete the following steps:

  1. Download the DITA-OT Full Easy Install package.
  2. Unzip DITA-OT1.5.4_full_easy_install_bin.zip into the installation directory.
  3. Run the batch file "startcmd.bat" to set up the necessary environment variables. A new Command Prompt window will open up, with the environment variables already set to enable DITA-OT to run within that shell.
  4. Run the transformation in the Command Prompt window by using Ant or command-line tool.

Installing DITA-OT Full Easy Install package in Linux or OS X

The software that DITA-OT depend on are redistributed. The Full Easy Install package of DITA OT after 1.3 includes the software, so the configuration process is streamlined.

Before installing DITA Open Toolkit full distribution, you need to complete the following steps:

  • Download and configure JRE properly.
  • (Optional) Download and configure JavaHelp Compiler properly for JavaHelp transformation.

Then, you need to complete the following steps:

  1. Download the DITA-OT Full Easy Install package.
  2. Extract DITA-OT1.5.4_full_easy_install_bin.tar.gz into the installation directory.
  3. Run shell script "startcmd.sh" to set up the necessary environment variables. A new Terminal window will open up, with the environment variables already set to enable DITA-OT to run within that shell.
  4. Run the transformation in the Terminal window by using Ant or command-line tool.

Set up DITA Open Toolkit in Windows

The recommended use of the DITA Open Toolkit components is inside of the Java environment because its pre-process architecture needs Java and Java-based tools. Therefore, before installing the DITA Open Toolkit processing environment, ensure that you have installed the following prerequisite tools :
Note: See Tested platforms and tools for detailed information about versions of these tools that have been successfully tested with the current toolkit release.
Java runtime or development environment 1.5
Provides the basic environment for most tools used in this toolkit.

You can download and install the Java Runtime Environment (JRE) 1.5 (or greater) (available onhttp://www.oracle.com/technetwork/java/javase/overview/index.html) into a directory of your choice.

XSLT 1.0 compliant transformation engine
Provides the main transformation services via the advanced XSLT processor Saxon 9.1 (or greater) or Xalan-J 2.7.1 (or greater) in the toolkit.

You can download and extract Saxon (available at http://saxon.sourceforge.net/) or the Xalan-J (available at http://xml.apache.org/xalan-j/downloads.html) into a directory of your choice.

Ant 1.7.1 build tool
Provides the standard setup and sequencing of processing steps.

The following steps guide you to set up the DITA Open Toolkit processing environment.

  1. Download the DITA Open Toolkit package file from SourceForge .
    Note:
  2. Unzip the package file into a installation directory of your choice.

    For example C:\pkg\DITA-OT1.5.4

  3. Verify that the environment variable JAVA_HOME has been set.
    set JAVA_HOME=<JRE_dir>
  4. Verify that the environment variable ANT_HOME has been set.
    set ANT_HOME=<Ant_dir>
  5. Verify that the environment variable PATH includes Java and Ant executables.
    set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%
  6. Set up DITA_HOME environment variable to point to DITA-OT installation directory.
    set DITA_HOME=<DITA-OT_dir>
  7. Set up your environment variable CLASSPATH.
    set CLASSPATH=%DITA_HOME%\lib\dost.jar;%CLASSPATH%
    set CLASSPATH=%DITA_HOME%\lib;%CLASSPATH%
    set CLASSPATH=%DITA_HOME%\lib\resolver.jar;%CLASSPATH%
    set CLASSPATH=%DITA_HOME%\lib\commons-codec-1.4.jar;%CLASSPATH%
  8. Set up the XSLT processor.
    • If you use the Saxon, set up CLASSPATH to include Saxon JAR files.

      set CLASSPATH=<saxon_dir>\saxon9.jar;<saxon_dir>\saxon9-dom.jar;%CLASSPATH%

      Set up ANT_OPTS.

      set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
    • If you use the Xalan, set up CLASSPATH to include Xalan JAR files.

      set CLASSPATH=<xalan_dir>\xalan.jar;%CLASSPATH%
  9. Optional: If you need JavaHelp output, set up you environment variable JHHOME.
    set JHHOME=<javahelp_dir>
  10. Optional: If you need Compiled HTML Help output, add Microsoft HTML Help Workshop installation directory to local.properties as hhc.dir property.
    hhc.dir=C:\\Program Files (x86)\\HTML Help Workshop
  11. Optional: If you use FOP for PDF processing, add FOP installation directory to local.properties as fop.home property.
    fop.home=C:\\Program Files\\fop
  12. Optional: If you use RenderX for PDF processing, add RenderX installation directory to local.properties as xep.dir property.
    xep.dir=C:\\Program Files\\xep
  13. Optional: If you use AntennaHouse Formatter for PDF processing, add AH Formatter installation directory to local.properties as axf.path property.
    axf.path=C:\\Program Files\\AHFormatterV6
  14. Test the DITA-OT installation with the demo conversions.

    Run all demos in the DITA Open Toolkit directory.

    C:\pkg\DITA-OT1.5.4>ant -f samples\ant_sample\sample_all.xml

Set up DITA Open Toolkit in Linux or OS X

The following steps guide you to set up the DITA Open Toolkit processing environment in Linux or OS X.

The recommended use of the DITA Open Toolkit components is inside of the Java environment because its pre-process architecture needs Java and Java-based tools. Therefore, before installing the DITA Open Toolkit processing environment, ensure that you have installed the following prerequisite tools :
Note: See Tested platforms and tools for detailed information about versions of these tools that have been successfully tested with the current toolkit release.
Java runtime or development environment 1.5
Provides the basic environment for most tools used in this toolkit.

You can download and install the Java Runtime Environment (JRE) 1.5 (or greater) (available onhttp://www.oracle.com/technetwork/java/javase/overview/index.html) into a directory of your choice.

XSLT 1.0 compliant transformation engine
Provides the main transformation services via the advanced XSLT processor Saxon 9.1 (or greater) or Xalan-J 2.7.1 (or greater) in the toolkit.

You can download and extract Saxon (available at http://saxon.sourceforge.net/) or the Xalan-J (available at http://xml.apache.org/xalan-j/downloads.html) into a directory of your choice.

Ant 1.7.1 build tool
Provides the standard setup and sequencing of processing steps.
  1. Download the DITA Open Toolkit package file from SourceForge .
    Note:
  2. Extract the package file into a installation directory of your choice.
    Note: You can extract all package files and toolkits either to your private home directory for exclusive usage or to /usr/local/share/ directory for sharing.
  3. Verify that the environment variable JAVA_HOME has been set.
    export JAVA_HOME=<JRE_dir>
  4. Verify that the environment variable ANT_HOME has been set.
    export ANT_HOME=<Ant_dir>
  5. Verify that the environment variable PATH includes Java and Ant executables.
    export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
  6. Set up DITA_HOME environment variable to point to DITA-OT installation directory.
    export DITA_HOME=<DITA-OT_dir>
  7. Set up your environment variable CLASSPATH.
    export CLASSPATH=$DITA_HOME/lib/dost.jar:$CLASSPATH
    export CLASSPATH=$DITA_HOME/lib:$CLASSPATH
    export CLASSPATH=$DITA_HOME/lib/resolver.jar:$CLASSPATH
    export CLASSPATH=$DITA_HOME/lib/commons-codec-1.4.jar:$CLASSPATH
  8. Set up the XSLT processor.
    • If you use the Saxon, set up CLASSPATH to include Saxon JAR files.

      export CLASSPATH=<saxon_dir>/saxon9.jar:<saxon_dir>/saxon9-dom.jar:$CLASSPATH

      Set up ANT_OPTS.

      export ANT_OPTS=$ANT_OPTS -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
    • If you use the Xalan, set up CLASSPATH to include Xalan JAR files.

      export CLASSPATH=<xalan_dir>/xalan.jar:$CLASSPATH
  9. Optional: If you need JavaHelp output, set up you environment variable JHHOME.
    export JHHOME=<javahelp_dir>
  10. Optional: If you use FOP for PDF processing, add FOP installation directory to local.properties as fop.home property.
    fop.home=/usr/share/java/fop
  11. Optional: If you use RenderX for PDF processing, add RenderX installation directory to local.properties as xep.dir property.
    xep.dir=/usr/share/java/xep
  12. Optional: If you use AntennaHouse Formatter for PDF processing, add AH Formatter installation directory to local.properties as axf.path property.
    axf.path=/usr/share/java/AHFormatterV6
  13. Test the DITA-OT installation with the demo conversions.

    Run all demos in the DITA Open Toolkit directory.

    /usr/local/share/DITA-OT1.5.4$ ant -f samples/ant_sample/sample_all.xml