Sample use case: Add a new customization plugin to the DITA Open Toolkit

To create a new transformation scenario that uses the DITA Open Toolkit, you create a plugin that contains a new transtype and the customization for the DITA-OT transformation.

For example, you may want to add a new plugin to the DITA Open Toolkit to integrate a new transformation scenario or to add open source plugins such as the DITA for Publishers plugin or QA Plugin for DITA-OT.

Note: This procedure assumes that the plugin was created using the procedure in the DITA Open Toolkit documentation. See the DITA Open Toolkit User Guide for more information.
In general, there are three main steps involved in adding a new plugin:
  • Install the plugin
  • Link the plugin to the IXIASOFT Output Generator by creating a target
  • Make it visible to your users

To illustrate this process, the following procedure shows how to add the QA plugin for DITA-OT to the IXIASOFT Output Generator. This plugin checks your DITA content and provides a Quality Assurance (QA) report that lists errors in the DITA usage in your files (incorrect DITA tagging, language standards, etc.).

Note: This procedure assumes that you have downloaded the open source plug-in called QA plugin for DITAOT from the web.

To add a new plugin to the IXIASOFT Output Generator:

  1. Extract the plugin to the %OutputGenDir%/data/%OT_Dir%/plugins directory.
    For example:
    C:\ixiasoft\OutputGenerators\Prod_[version]\data\DITA-OT1.8.5\plugins\

    Where [version] is replaced by the release version number.

  2. Run the DITA-OT integrator.
    This step depends on the DITA-OT family:
    DITA-OT 1.x family:
    • On Windows: In the %OutputGenDir%/data/ directory, double-click the _DITA-OT-1.8.5-integrator.bat file.
    • On Linux:
      1. In the %OutputGenDir%/data/%OT_Dir%/ directory, run the following command as root:
        startcmd.sh
      2. At the command prompt, enter:
        ant -f integrator.xml

    The integration build runs and you should soon see BUILD SUCCESSFUL.

    DITA-OT 2.x family:
    • On Windows: In the %OutputGenDir%/data/ directory, double-click the _DITA-OT-2.3.1-integrator.bat file.
    • On Linux: In the %OutputGenDir%/data/%OT_Dir%/bin directory, enter the following command:
      ./ant -f ../integrator.xml (Linux)

    The integration build runs and you should soon see BUILD SUCCESSFUL.

  3. Create a target in your client conductor file (for example, %OutputGenDir%/data/conductor-acme.xml), as described in Create a transformation target.
    Note: You can use the client.FooBarwrapper target in the %OutputGenDir%/data/conductor-client.xml.orig file as a template to create your target.
    The target should be similar to the following:
    <target name="qa_for_ot" depends="default_dependencies, flatten, resolve_container_keyref, extract_HiRes_images">
        <echostart>qa_for_ot</echostart>
    		
        <property name="outgen.job.build.filename" location="${outgen.job.dir}/build.xml"/>
        <property name="outgen.job.build.template.filename" location="${outgen.resources.dir}/job-build-template.xml"/>
        <property name="outgen.job.build.otlog.filename" location="${outgen.job.ot.log.dir}/${outgen.job.source.name.noext}.ot.log"/>
    
        <antcall target="ot_build_create"/>
        <antcall target="ot_build_add_ditaval_ifpresent"/>
        <antcall target="ot_build_clean_ot_temp"/>
    
        <update-ot-build-file buildfile="${outgen.job.build.filename}">
            <param name="transtype" value="qa"/>
        </update-ot-build-file>
    
        <antcall target="dita_startcmd_ot_build"/>
    
        <antcall target="clean_ot_output"/>
    
        <!-- Set the property job.keep.temp to preserve the completed temp folder of the task -->
        <!--<property name="job.keep.temp" value="yes"/>-->
    
        <echoend>qa_for_ot</echoend>
    </target>
    Note:

    The parameters in bold above are specific to the QA Plugin for DITA-OT. See the documentation at the following URL for more information:

    http://ditanauts.org/2012/05/04/installing-and-customizing-the-qa-plugin/

  4. Create a preprocessor for the plugin in the %OutputGenDir%/conf/client/preprocessors.xml file, as described in Add a new preprocessor.
    The preprocessor should be similar to the following:
    <preprocessor name="QA_for_OT" class="com.ixiasoft.outputgenerator.preprocessor.AntProcessor" >
        <parameters>
            <system>
                <parameter name="outputfile" value=".html"/>
                <parameter name="buildfile" value="/conductor-client.xml"/>
                <parameter name="target" value="qa_for_ot"/>
                <parameter name="clean" value="job_postprocess"/>
                <parameter name="keep.log.files" value="true"/>
            </system>
        </parameters>
    </preprocessor>
  5. Create an output type for the plugin in the %OutputGenDir%/conf/client/outputtypes.xml file, as described in Add a new output type.
    The output type should be similar to the following:
    <outputtype name="QA_for_OT" timeout="120000" system="false">
        <preprocessing>
            <preprocessor name="QA_for_OT" />
        </preprocessing>
        <renderer/>
    </outputtype>
  6. Restart the IXIASOFT Output Generator service.
    You can now use the new transformation scenario.