<?xml version='1.0' encoding='UTF-8'?>
<!-- This file is part of the DITA Open Toolkit project hosted on 
     Sourceforge.net. See the accompanying license.txt file for 
     applicable licenses.-->
<!-- (C) Copyright IBM Corporation 2005, 2006. All Rights Reserved. -->
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "..\..\..\dtd\task.dtd" []>
<task xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/" id="useplugin" xml:lang="en-us">
  <title>Download, install and use a plug-in</title>
  <shortdesc>DITA Open Toolkit 1.2 and above provides a new function to help users to download, install and use plug-ins for DITA Open Toolkit. You can download, install and use a created plug-in. DITA Open Toolkit loads the plug-ins each time when a build is invoked.</shortdesc>
  <taskbody>
    <prereq>Before using a plug-in, ensure you have accomplished two tasks below:<ul>
        <li>Follow the installation instructions to install DITA OT to your local workstation. DITA OT root directory is installed. </li>
        <li>Config DITA OT and DITA OT basic function to see if there is any problems.</li>
      </ul></prereq>
    <context/>
    <steps>
      <step>
        <cmd>Go to the available Web site, such as the DITA OT SourceForge Web site, to download the DITA OT base binary file. Download a DITA OT plug-in binary file, such as apiref.zip.</cmd>
      </step>
      <step>
        <cmd>Extract the plug-in package to /demo directory of DITA OT root directory.</cmd>
        <stepxmp>For example, extract apiref.zip to /demo directory.</stepxmp>
      </step>
      <step>
        <cmd>On the command line of the DITA OT root directory, enter either the Ant or Java command line to execute the new function provided by the plug-in.</cmd>
        <stepxmp>For example, under the DITA OT root directory, type <userinput>java -jar lib\dost.jar /i:demo\apiref\sample\apiPackage1.ditamap /ditaext:.dita /transtype:xhtml</userinput> on the command line. The messages displayed on the screen will show the building process of apiPackage1.ditamap file in sample folder. If this plug-in is installed successfully, a message <msgph>BUILD SUCCESSFUL</msgph> appears on the screen when building ends.</stepxmp>
        <info>If the plug-in is not installed or cannot function, the message <msgph>BUILD FAILED</msgph> displays.</info>
      </step>
      <step>
        <cmd>If you want to remove the plug-in, remove the directory containing the plug-in files. </cmd>
      </step>
    </steps>
    <postreq>
      <note>The plug-in is integrated to toolkit every time when a build is invoked. You only need to unzip the package to the specific directory. </note>
      <p> If the implemented plug-in depends on another plug-in, which is not installed in your local workstation, the installed plug-in cannot work. Thus a dependency track checks whether the installed plug-in is about to be loaded or not when the transformation pipeline is invoked.</p>
      <p>There is no function provided by plug-ins in default build.xml file. You need to customize build.xml file if you want to use plug-in&apos;s function in it. Before running customized build.xml file with plug-in&apos;s function, you need to execute an installer program to update and integrate the installed plug-ins. Otherwise, the plug-ins you want to use might not be loaded. </p>
      <p>Here is how to execute the installer program under the DITA OT root directory. Type <userinput>java -cp lib\dost.jar org.dita.dost.platform.Integrator</userinput> on the command line or use <userinput>ant -f integrator.xml</userinput> to execute the ANT script. The installer program will be invoked to integrate the plug-ins with DITA OT.</p>
    </postreq>
  </taskbody>
</task>
