source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/dev_ref/plugins-installing.dita@ 99507

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="plugins-installing" xml:lang="en">
  <title>Installing plug-ins</title>
  <shortdesc>Plug-ins are generally distributed as zip files. There are two steps to installing a
    plug-in: unzipping and integrating.</shortdesc>
  <taskbody>
    <context>
      <p>It is possible to define a plug-in so that it may be installed anywhere, although most
        expect to be placed in <filepath>plugins/</filepath> directory inside of the DITA-OT. Most
        plug-ins do not require a specific install directory and can go in either of the default
        locations, but some may come with instructions for a particular install directory.</p>
    </context>
    <steps>
      <step>
        <cmd>The unzip the plug-in file to <filepath>plugins</filepath> subdirectory.</cmd>
        <info>The plug-in directory should be named after plug-in ID and version, for example
            <filepath>plugins/com.example.xhtml_1.0.0</filepath>.</info>
      </step>
      <step>
        <cmd>Run plug-in integration process.</cmd>
        <choices>
          <choice>From the toolkit directory, run the following command to integrate all installed
            plug-ins: <codeblock>ant -f integrator.xml </codeblock></choice>
          <choice>Any build that uses the Java command line interface automatically runs the integrator
            before processing begins.</choice>
          <choice>Ant based builds may import the <codeph>integrator.xml</codeph> file, and add
              <codeph>integrate</codeph> to the start of the dependency chain for the build. <note
              type="note">The integration process in considered part of the installation process and
              running it before each conversion will incur a performance penalty.</note></choice>
        </choices>
        
        
        <info>
          <p>The integration process has two modes, lax and strict. In the strict mode the integration process will immediately fail if it encounters errors in plug-in configurations or installation process. In the lax mode, the integration process will continue to finish regardless of errors; the lax mode does not imply error recovery and may leave the DITA-OT installation into a broken state. The default mode is lax due to backwards compatibility, to run the integration in strict mode:</p>
          <codeblock>ant -f integrator.xml strict</codeblock>
          <p>To get more information about the integration process, run Ant in verbose mode:</p>
          <codeblock>ant -f integrator.xml -verbose strict</codeblock>
        </info>
      </step>
    </steps>
  </taskbody>
</task>