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

<?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 id="integratingwithwtp" xml:lang="en-us">
<title>Creating Eclipse help from within Eclipse</title>
<shortdesc>This topic explains how to create an Eclipse help documentation
plug-in from within the Eclipse platform. This process allows you
to set up repeatable builds directly within Eclipse, which may already
be familiar to many developers working within Eclipse. The topic was
originally written based on Eclipse 3.3, but much of the information
still applies.</shortdesc>
<taskbody>
<context>You can use a template to develop documentation plug-in with DITA in Eclipse PDE and use
      DITA-OT <keyword keyref="release.version"/> to build and pack the final plug-in. When you want to develop a documentation
      plug-in with DITA in Eclipse, you cannot use the previous releases of DITA-OT in Eclipse to
      transform DITA to HTML. Though previous releases of DITA-OT support the feature to transform
      DITA files to Eclipse documentation plug-in, they are not integrated with Eclipse. With
      DITA-OT <keyword keyref="release.version"/> integrated with WPT, you can develop document plug-ins with DITA in Eclipse PDE
      and build and pack the final plug-in by taking the following steps.</context>
<steps>
<step><cmd rev="r4">Create a new PDE project in Eclipse, and apply the DITA
template to the project by following the wizard.</cmd><info><image href="images/createlpluginproject.jpg"
placement="break"><alt>Start Eclipse and create a new plug-in project</alt>
</image></info></step>
<step id="step2"><cmd rev="r3">Set the source directory, the main ditamap file, the output directory (default value
          is root directory of project), css storage directory (used to contain<filepath>
            common.css</filepath>, <filepath>commonltr.css</filepath>, and
            <filepath>commonrtl.css</filepath>), user customized .css file name, and conditional
          processing ditaval file in the wizard. <uicontrol>Use root as output directory</uicontrol>
          is selected as the default.</cmd><info>You can also clear <uicontrol>Use root as output
directory</uicontrol> and specify another output directory. <fig>
<image href="images/specifyoutputdir.JPG" placement="break"><alt>Set directories</alt>
</image>
</fig><fig>
<image href="images/newdirectory.JPG" placement="break"><alt>Specify another directory</alt>
</image>
</fig></info></step>
<step><cmd>Create DITA files in the source directory and a ditamap to include
the topic files that you created.</cmd></step>
<step importance="optional"><cmd>Import the DITA files into the <filepath>src</filepath> directory
of the DITA plug-in project you just created.</cmd>
<substeps>
<substep><cmd>Right-click a directory that you want to put the imported files and select <menucascade>
                <uicontrol>Import</uicontrol>
                <uicontrol>File system</uicontrol>
              </menucascade>. </cmd><info><fig>
<image href="images/filesys.jpg" placement="break"><alt>Select an import file source</alt>
</image>
</fig></info></substep>
<substep><cmd>Select the directory under which you put the DITA files.</cmd>
<info><fig>
<image href="images/setdirectory.jpg" placement="break"><alt>Select a directory</alt>
</image>
</fig></info></substep>
<substep><cmd>Click Finish after you selected the DITA files under the specified
directory. The DITA files are then imported to your DITA project.</cmd></substep>
</substeps>
</step>
<step><cmd>Right click <filepath>build.xml</filepath>, select <menucascade><uicontrol>Run As</uicontrol>
  <uicontrol>Ant Build</uicontrol></menucascade>.</cmd>
 <info><note importance="high">If you're using Oracle JDK, please download and use the latest Xalan. The
            Xalan shipped with Oracle JDK has some issue that will cause the build failure. You can
            use the latest Xalan by selecting <uicontrol>ANT Build ...</uicontrol> and include the
            all of Xalan's jar files in Classpath.</note></info>
<info>After the transformation, the output is in the output directory set in
            <filepath>build.xml</filepath>. Refresh the project after the build is successful.<fig>
            <image href="images/runasant.jpg" placement="break">
              <alt>Run as Ant build</alt>
            </image>
          </fig><fig>
            <image href="images/classpath.jpg" placement="break">
              <alt>Set the Classpath</alt>
            </image>
          </fig></info></step>
<step><cmd>Edit the plug-in description of the property file <filepath>MANITEST.MF</filepath> in the
          plug-in editor after you run the Ant build successfully. </cmd>
<substeps>
<substep><cmd>Click <filepath>MANITEST.MF</filepath> to go to the <wintitle>Overview page</wintitle>.</cmd><info><fig>
<image href="images/overview.jpg" placement="break"><alt>Overview</alt></image>
</fig></info></substep>
<substep><cmd>Edit Dependencies to include <codeph>org.eclipse.help</codeph>.</cmd><info><fig>
<image href="images/org.jpg" placement="break"><alt>Edit Dependencies</alt></image>
</fig></info></substep>
<substep><cmd>Edit Extensions to add <codeph>org.eclipse.help.toc</codeph>; right click the added
                <codeph>org.eclipse.help.toc</codeph>, and select <menucascade>
                <uicontrol>New</uicontrol><uicontrol>toc</uicontrol>
              </menucascade>.</cmd><info><fig>
<image href="images/toc.jpg" placement="break"><alt>Edit Extensions</alt></image>
</fig></info></substep>
<substep><cmd>Edit the Build Configuration to include the out directory or
the directory you specified in <xref href="#integratingwithwtp/step2"><!--Step 2--></xref>.</cmd>
<info><fig>
<image href="images/buildout.JPG" placement="break"><alt>Edit Build Configuration</alt>
</image>
</fig></info></substep>
<substep rev="r3"><cmd>Save the changes you made to the property file MANITEST.MF.</cmd>
</substep>
</substeps>
</step>
<step><cmd>Export the output to a documentation plug-in. </cmd><info><note>build.xml
can be customized to meet the requirement of headless build.</note></info>
<substeps>
<substep><cmd>Select <menucascade>
                <uicontrol>File</uicontrol>
                <uicontrol rev="r3">Export</uicontrol>
              </menucascade>; select <uicontrol>Deployable plug-ins and fragments</uicontrol> and
              click <uicontrol>Next</uicontrol>.</cmd>
<info><fig>
<image href="images/export.jpg" placement="break"><alt>Export a plug-in</alt></image>
</fig></info></substep>
<substep><cmd>Select the plug-in you want to export and specify a directory
under which you want to put the plug-in package.</cmd><info><image href="images/selectplugin.jpg"
placement="break"><alt>Select a plug-in and specify the export destination</alt>
</image></info></substep>
<substep><cmd>Click <uicontrol>Finish</uicontrol> to export the plug-in package.</cmd>
</substep>
</substeps>
</step>
</steps>
</taskbody>
</task>