Installing the DITA Toolkit

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

Prerequisite for installation:
The recommended use of the DITA Toolkit components is inside of the Java environment because its pre-process architecture needs Java and Java-based tools. Therefore, before installing the DITA 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
Provides the basic environment for most tools used in this toolkit.

You can download and install the Java Development Kit (JDK) 1.5 (available onhttp://java.sun.com/j2se/index.jsp) into a directory of your choice.

XSLT 1.0 compliant transformation engine
Provides the main transformation services via the advanced XSLT processor Saxon 6.5 (or greater) or Xalan-J 2.6 (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.
See Setting up Ant for more information.

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

  1. Download the DITA Toolkit package file from SourceForge .
    Note:
    • It is recommended to download the latest version of the DITA Toolkit for stable usage.
    • If you use DITA Open Toolkit full distribution, click here to continue.
    • If you use Linux, click here to continue the setting up process.
  2. Extract the package file into a directory of your choice.

    For example: c:\pkg\DITA-OT1.0

  3. Set up your environment variable JAVA_HOME to your installation directory for JDK or JRE.
    For example:
    set JAVA_HOME=<JDK_dir> 
  4. Set up the XSLT processor.
    Option Description
    If you use the Saxon,
    • Set up CLASSPATH to include the saxon.jar file.

      set CLASSPATH=%CLASSPATH%; <saxon_dir>\saxon.jar

    • Set up ANT_OPTS.

      set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl

      Attention: if you do not use Saxon, please remove the saxon.jar file and ANT_OPTS from the environment variable.
    If you use the Xalan,
    • Set up CLASSPATH to include the xalan.jar file and the xercesImpl.jar file.
      set CLASSPATH=%CLASSPATH%;<xalan_dir>\bin
      Attention: if you don't use the Xalan, please remove jar files related to the Xalan from the environment variable CLASSPATH.
  5. If you need to build compiled JavaHelp, PDF output and compiled HTML Help, you should install some build tools for these formats of outputs

    JavaHelp is free software that can build online help for operating systems, applications, and devices. If you have set up JavaHelp, the DITA Open Toolkit can build online Java help by invoking JavaHelp software. To download and install JavaHelp software, go to http://java.sun.com/products/javahelp/download_binary.html

    FOP (Formatting Objects Processor) is a Java application and is the print formatter driven by XSL formatting objects (XSL-FO). FOP reads a formatting object tree and transforms the object to PDF output. If you have set up FOP, the DITA Open Toolkit can build PDF output by invoking FOP. To download and install the binary distribution for FOP, go to http://xml.apache.org/fop/download.html

    Microsoft HTML Help Workshop is a program designed to create and compile .CHM help files using HTML source files. If you have set up Microsoft HTML Help Workshop, the DITA Open Toolkit can build .CHM help files by invoking the Workshop. To download and install Microsoft HTML Help Workshop, go to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

    If you have installed one or more of these optional build tools, you should choose the following options to set up.

    Option Description
    If you have installed the JavaHelp, set up the environment variable JHHOME to your installation directory for JavaHelp. For example:

    set JHHOME=<javahelp_dir>

    If you have installed the FOP, set up your environment variable CLASSPATH to include the fop.jar, batik.jar and avalon.jar files in the FOP directory. For example:

    set CLASSPATH=%CLASSPATH%;<fop_dir>\build;<fop_dir>\lib

    If you want to build HTML Help output, install Microsoft HTML Help Workshop to the default directory.
  6. Test the DITA Toolkit when you complete above steps.

    You can do the following steps under the command prompt to test whether the DITA Toolkit and the XSLT engine are successfully installed.

    • Using the Xalan-Java/ LotusXSL-Java:

      For example:c:\pkg\DITA-OT1.0\doc>java org.apache.xalan.xslt.Process -in DITA-readme.xml -xsl ..\xsl\pretty.xsl -out ..\DITA-readme.xml

    • Using the Saxon:

      For example:c:\pkg\DITA-OT1.0\doc>java com.icl.saxon.StyleSheet DITA-readme.xml ..\xsl\pretty.xsl > ..\DITA-readme.xml

    • Using the Ant :

      Run all demo in the DITA Toolkit directory.

      For example: c:\pkg\DITA-OT1.0>ant all

      Or you can run specific file individually.

      For example:c:\pkg\DITA-OT1.0\ant samples.web

      Tip: Input ant -projecthelp to see the list of tasks
      Note: If you can pass this test, it means that all of the tools are installed correctly.

Installing DITA OT Full Distribution

The software that DITA OT depend on are redistributed. The full distribution 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 JDK 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 full DITA OT package.
  2. Run the batch file "startcmd.bat" for Windows or "startcmd.sh" for Linux to set up the necessary environment variables.
  3. Run the transformation in the command-line window by using Java command line or ANT.
You can still use the standard package to install DITA OT:
  • Download the standard package.
  • Configure the system environment of DITA OT, but add two more paths %DITA_HOME%\lib;%DITA_HOME%\lib\resolver.jar; to the CLASSPATH parameter.
  • Run the package by using Java command line or Ant.

Set up DITA Toolkit in Linux

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

  1. Extract the package file into a Linux home directory.
    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.
  2. Set up your environment variable JAVA_HOME.

    export JAVA_HOME=<JDK_dir>

  3. Set up your environment variable PATH.

    export PATH=$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$PATH

  4. Set up your environment variable CLASSPATH

    export CLASSPATH=$CLASSPATH:$JAVA_HOME/lib:$JAVA_HOME/jre/lib:<dita_dir>/lib/dost.jar

  5. Set up the XSLT processor.
    Option Description
    If you use the Saxon,
    • Set up CLASSPATH to include the saxon.jar file.

      export CLASSPATH=$CLASSPATH:<saxon_dir>/saxon.jar

    • Set up ANT_OPTS.

      export ANT_OPTS=$ANT_OPTS -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl

      Note: if you don't use Saxon, please remove the saxon.jar file and ANT_OPTS from the environment variable.
    If you use the Xalan,
    • Set up CLASSPATH to include the xalan.jar file and the xercesImpl.jar file.

      export CLASSPATH=$CLASSPATH:<xalan_dir>/bin

      Attention: if you don't use the Xalan, please remove jar files related to the Xalan from the environment variable CLASSPATH.
  6. If you have installed build tools for compiled JavaHelp, PDF output and compiled HTML Help, you should choose the following options to set up.
    Option Description
    If you have installed the JavaHelp, set up the environment variable JHHOME to your installation directory for JavaHelp. For example:

    export JHHOME=<javahelp_dir>

    If you have installed the FOP, set up your environment variable CLASSPATH to include the fop.jar, batik.jar and avalon.jar files in the FOP directory. For example:

    export CLASSPATH=$CLASSPATH:<fop_dir>/build:<fop_dir>/lib

    If you want to build HTML Help output, install Microsoft HTML Help Workshop to the default directory.
  7. Test the DITA Toolkit when you complete above steps.