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

# Installing the DITA Open Toolkit

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

Parent topic: DITA Open Toolkit User Guide

## 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:
   - It is recommended to download the latest version of the DITA Open Toolkit for stable usage.
   - If you use DITA Open Toolkit full distribution, follow instructions in Installing DITA-OT Full Easy Install package in Windows.
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:
   - It is recommended to download the latest version of the DITA Open Toolkit for stable usage.
   - If you use DITA Open Toolkit full distribution, follow instructions in Installing DITA-OT Full Easy Install package in Linux or OS X.
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