<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="installation" xml:lang="en">
  <title>Installing the DITA Open Toolkit</title>
  <titlealts>
    <navtitle>Installing DITA-OT</navtitle>
  </titlealts>
  <shortdesc>This topic explains how to install the DITA Open Toolkit processing
    environment.</shortdesc>
  <task id="Fullsetup-windows" platform="windows">
    <title>Installing DITA-OT Full Easy Install package in Windows</title>
    <shortdesc>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.</shortdesc>
    <taskbody>
      <prereq>
        <p>Before installing DITA Open Toolkit full distribution, you need to complete the following
          steps:</p>
        <ul>
          <li>Download and configure JRE properly.</li>
          <li importance="optional">(Optional) Download and configure HTMLHelp Compiler properly for
            HTMLHelp transformation. </li>
          <li importance="optional">(Optional) Download and configure JavaHelp Compiler properly for
            JavaHelp transformation.</li>
        </ul>
      </prereq>
      <context>
        <p>Then, you need to complete the following steps:</p>
      </context>
      <steps>
        <step>
          <cmd>Download the DITA-OT Full Easy Install package.</cmd>
        </step>
        <step>
          <cmd>Unzip <filepath>DITA-OT<keyword keyref="release.version"
              />_full_easy_install_bin.zip</filepath> into the installation directory.</cmd>
        </step>
        <step>
          <cmd>Run the batch file "<filepath>startcmd.bat</filepath>" to set up the necessary
            environment variables.</cmd>
          <stepresult>A new <wintitle>Command Prompt</wintitle> window will open up, with the
            environment variables already set to enable DITA-OT to run within that
            shell.</stepresult>
        </step>
        <step>
          <cmd>Run the transformation in the Command Prompt window by using Ant or command-line tool.</cmd>
        </step>
      </steps>
    </taskbody>
  </task>
  <task id="Fullsetup-unix" platform="linux osx">
    <title>Installing DITA-OT Full Easy Install package in Linux or OS X</title>
    <shortdesc>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.</shortdesc>
    <taskbody>
      <prereq>
        <p>Before installing DITA Open Toolkit full distribution, you need to complete the following
          steps:</p>
        <ul>
          <li platform="linux">Download and configure JRE properly.</li>
          <li importance="optional">(Optional) Download and configure JavaHelp Compiler properly for
            JavaHelp transformation.</li>
        </ul>
      </prereq>
      <context>
        <p>Then, you need to complete the following steps:</p>
      </context>
      <steps>
        <step>
          <cmd>Download the DITA-OT Full Easy Install package.</cmd>
        </step>
        <step>
          <cmd>Extract <filepath>DITA-OT<keyword keyref="release.version"
              />_full_easy_install_bin.tar.gz</filepath> into the installation directory.</cmd>
        </step>
        <step>
          <cmd>Run shell script "<filepath>startcmd.sh</filepath>" to set up the necessary
            environment variables.</cmd>
          <stepresult>A new <wintitle>Terminal</wintitle> window will open up, with the environment
            variables already set to enable DITA-OT to run within that shell.</stepresult>
        </step>
        <step>
          <cmd>Run the transformation in the Terminal window by using Ant or command-line tool.</cmd>
        </step>
      </steps>
    </taskbody>
  </task>
  <task id="installation-windows" platform="windows">
    <title>Set up DITA Open Toolkit in Windows</title>
    <taskbody>
      <prereq id="installattion-prereq">
        <p>The recommended use of the DITA Open Toolkit components is inside of the Java environment
          because its <xref href="DITA-usingtransforms.xml#ditausingxform/preprocess">pre-process
            architecture</xref> 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 <xref href="DITA-tested.xml">Tested platforms and
              tools</xref> for detailed information about versions of these tools that have been
            successfully tested with the current toolkit release.</note></p><dl>
          <dlentry id="Prereq" platform="windows linux">
            <dt id="jdk">Java runtime or development environment <keyword keyref="tool.java.version"
              /></dt>
            <dd>Provides the basic environment for most tools used in this toolkit. <p>You can
                download and install the Java Runtime Environment (JRE) <keyword
                  keyref="tool.java.version"/> (or greater) (available on<xref format="html"
                  href="http://www.oracle.com/technetwork/java/javase/overview/index.html"
                  scope="external"/>) into a directory of your choice.</p></dd>
          </dlentry>
          <dlentry id="XSLT">
            <dt id="xslt">XSLT 1.0 compliant transformation engine</dt>
            <dd>Provides the main transformation services via the advanced XSLT processor Saxon
                <keyword keyref="tool.saxon.version"/> (or greater) or Xalan-J <keyword
                keyref="tool.xalan.version"/> (or greater) in the toolkit.<p>You can download and
                extract Saxon (available at <xref format="html" href="http://saxon.sourceforge.net/"
                  scope="external"/>) or the Xalan-J (available at <xref format="html"
                  href="http://xml.apache.org/xalan-j/downloads.html" scope="external"/>) into a
                directory of your choice.</p></dd>
          </dlentry>
          <dlentry id="antbuild">
            <dt>Ant <keyword keyref="tool.ant.version"/> build tool</dt>
            <dd>Provides the standard setup and sequencing of processing steps.</dd>
          </dlentry>
        </dl>
      </prereq>
      <steps>
        <stepsection>
          <p>The following steps guide you to set up the DITA Open Toolkit processing
            environment.</p>
        </stepsection>
        <step id="download">
          <cmd>Download the DITA Open Toolkit package file from <xref format="html"
              href="http://sourceforge.net/projects/dita-ot" scope="external">SourceForge</xref>
            .</cmd>
          <info>
            <note>
              <ul>
                <li>It is recommended to download the latest version of the DITA Open Toolkit for
                  stable usage.</li>
                <li>If you use DITA Open Toolkit full distribution, follow instructions in <xref
                    href="#Fullsetup-windows"/>.</li>
              </ul>
            </note>
          </info>
        </step>
        <step>
          <cmd>Unzip the package file into a installation directory of your choice. </cmd>
          <stepxmp>
            <p>For example <filepath>C:\pkg\DITA-OT<keyword keyref="release.version"
              /></filepath></p>
          </stepxmp>
        </step>
        <step>
          <cmd>Verify that  the environment variable <codeph>JAVA_HOME</codeph> has been set. </cmd>
          <stepxmp>
            <codeblock>set JAVA_HOME=&lt;JRE_dir></codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Verify that  the environment variable <codeph>ANT_HOME</codeph> has been set. </cmd>
          <stepxmp>
            <codeblock>set ANT_HOME=&lt;Ant_dir></codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Verify that the environment variable <codeph>PATH</codeph> includes Java and Ant
            executables.</cmd>
          <stepxmp>
            <codeblock>set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Set up <codeph>DITA_HOME</codeph> environment variable to point to DITA-OT
            installation directory.</cmd>
          <stepxmp>
            <codeblock>set DITA_HOME=&lt;DITA-OT_dir></codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Set up your environment variable <codeph>CLASSPATH</codeph>.</cmd>
          <stepxmp>
            <codeblock>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-<keyword keyref="tool.codec.version"/>.jar;%CLASSPATH%</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Set up the XSLT processor.</cmd>
          <choices>
              <choice>
                <p>If you use the Saxon, set up <codeph>CLASSPATH</codeph> to include Saxon JAR
                files. </p>
                <codeblock>set CLASSPATH=&lt;saxon_dir>\saxon9.jar;&lt;saxon_dir>\saxon9-dom.jar;%CLASSPATH%</codeblock>
                <p>Set up <codeph>ANT_OPTS</codeph>.</p>
                <codeblock>set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl</codeblock>
              </choice>
              <choice>
                <p>If you use the Xalan, set up <codeph>CLASSPATH</codeph> to include Xalan JAR
                files. </p>
                <codeblock>set CLASSPATH=&lt;xalan_dir&gt;\xalan.jar;%CLASSPATH%</codeblock>
              </choice>
          </choices>
        </step>
        <step importance="optional">
          <cmd>If you need JavaHelp output, set up you environment variable <codeph>JHHOME</codeph>.</cmd>
          <stepxmp>
            <codeblock>set JHHOME=&lt;javahelp_dir&gt;</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you need Compiled HTML Help output, add Microsoft HTML Help Workshop installation directory to
            <filepath>local.properties</filepath> as <codeph>hhc.dir</codeph> property.</cmd>
          <stepxmp>
            <codeblock>hhc.dir=C:\\Program Files (x86)\\HTML Help Workshop</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you use FOP for PDF processing, add FOP installation directory to
              <filepath>local.properties</filepath> as <codeph>fop.home</codeph> property.</cmd>
          <stepxmp>
            <codeblock>fop.home=C:\\Program Files\\fop</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you use RenderX for PDF processing, add RenderX installation directory to
            <filepath>local.properties</filepath> as <codeph>xep.dir</codeph> property.</cmd>
          <stepxmp>
            <codeblock>xep.dir=C:\\Program Files\\xep</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you use AntennaHouse Formatter for PDF processing, add AH Formatter installation directory to
            <filepath>local.properties</filepath> as <codeph>axf.path</codeph> property.</cmd>
          <stepxmp>
            <codeblock>axf.path=C:\\Program Files\\AHFormatterV6</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Test the DITA-OT installation with the demo conversions.</cmd>
          <stepxmp>
            <p>Run all demos in the DITA Open Toolkit directory. </p>
            <codeblock>C:\pkg\DITA-OT<keyword keyref="release.version"/>>ant -f samples\ant_sample\sample_all.xml</codeblock>
          </stepxmp>
        </step>
      </steps>
    </taskbody>
  </task>
  <task id="Linuxsetup" platform="linux osx">
    <title>Set up DITA Open Toolkit in Linux or OS X</title>
    <shortdesc> The following steps guide you to set up the DITA Open Toolkit processing environment
      in Linux or OS X. </shortdesc>
    <taskbody>
      <prereq conref="#installation-windows/installattion-prereq" id="prereq_2nz_y24_12"/>

      <steps>
        <step id="download">
          <cmd>Download the DITA Open Toolkit package file from <xref format="html"
              href="http://sourceforge.net/projects/dita-ot" scope="external">SourceForge</xref>
            .</cmd>
          <info>
            <note>
              <ul>
                <li>It is recommended to download the latest version of the DITA Open Toolkit for
                  stable usage.</li>
                <li>If you use DITA Open Toolkit full distribution, follow instructions in <xref
                    href="#Fullsetup-unix"/>.</li>
              </ul>
            </note>
          </info>
        </step>
        <step>
          <cmd>Extract the package file into a installation directory of your choice. </cmd>
          <info>
            <note>You can extract all package files and toolkits either to your private home
              directory for exclusive usage or to <filepath>/usr/local/share/</filepath> directory
              for sharing. </note>
          </info>
        </step>
        <step>
          <cmd>Verify that  the environment variable <codeph>JAVA_HOME</codeph> has been set. </cmd>
          <stepxmp>
            <codeblock>export JAVA_HOME=&lt;JRE_dir&gt;</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Verify that  the environment variable <codeph>ANT_HOME</codeph> has been set. </cmd>
          <stepxmp>
            <codeblock>export ANT_HOME=&lt;Ant_dir&gt;</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Verify that the environment variable <codeph>PATH</codeph> includes Java and Ant
            executables.</cmd>
          <stepxmp>
            <codeblock>export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Set up <codeph>DITA_HOME</codeph> environment variable to point to DITA-OT
            installation directory.</cmd>
          <stepxmp>
            <codeblock>export DITA_HOME=&lt;DITA-OT_dir></codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Set up your environment variable <codeph>CLASSPATH</codeph>.</cmd>
          <stepxmp>
            <codeblock>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-<keyword keyref="tool.codec.version"/>.jar:$CLASSPATH</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Set up the XSLT processor.</cmd>
          <choices>
            <choice>
              <p>If you use the Saxon, set up <codeph>CLASSPATH</codeph> to include Saxon JAR
                files.</p>
                <codeblock>export CLASSPATH=&lt;saxon_dir>/saxon9.jar:&lt;saxon_dir>/saxon9-dom.jar:$CLASSPATH</codeblock>
                <p>Set up <codeph>ANT_OPTS</codeph>.</p>
                <codeblock>export ANT_OPTS=$ANT_OPTS -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl</codeblock>
            </choice>
            <choice>
              <p>If you use the Xalan, set up <codeph>CLASSPATH</codeph> to include Xalan JAR files. </p>
              <codeblock>export CLASSPATH=&lt;xalan_dir>/xalan.jar:$CLASSPATH</codeblock>
            </choice>
          </choices>
        </step>
        <step importance="optional">
          <cmd>If you need JavaHelp output, set up you environment variable <codeph>JHHOME</codeph>.</cmd>
          <stepxmp>
            <codeblock>export JHHOME=&lt;javahelp_dir&gt;</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you use FOP for PDF processing, add FOP installation directory to
            <filepath>local.properties</filepath> as <codeph>fop.home</codeph> property.</cmd>
          <stepxmp>
            <codeblock>fop.home=/usr/share/java/fop</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you use RenderX for PDF processing, add RenderX installation directory to
            <filepath>local.properties</filepath> as <codeph>xep.dir</codeph> property.</cmd>
          <stepxmp>
            <codeblock>xep.dir=/usr/share/java/xep</codeblock>
          </stepxmp>
        </step>
        <step importance="optional">
          <cmd>If you use AntennaHouse Formatter for PDF processing, add AH Formatter installation directory to
            <filepath>local.properties</filepath> as <codeph>axf.path</codeph> property.</cmd>
          <stepxmp>
            <codeblock>axf.path=/usr/share/java/AHFormatterV6</codeblock>
          </stepxmp>
        </step>
        <step>
          <cmd>Test the DITA-OT installation with the demo conversions.</cmd>
          <stepxmp>
            <p>Run all demos in the DITA Open Toolkit directory. </p>
            <codeblock>/usr/local/share/DITA-OT<keyword keyref="release.version"/>$ ant -f samples/ant_sample/sample_all.xml</codeblock>
          </stepxmp>
        </step>
      </steps>
    </taskbody>
  </task>
</task>
