Difference between revisions of "Authoring Eclipse Help Using DITA"

From Eclipsepedia

Jump to: navigation, search
(Problems Integrating DITA-OT into Eclipse)
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction to DITA ==
 
== Introduction to DITA ==
  
This page contains information about how to use DITA for authoring Eclipse Help.
+
This page contains information about how to use DITA for authoring Eclipse Help. If you are using DITA in Eclipse and have questions, comments, etc., about integration, send a note to the [mailto:wtp-dev@eclipse.org WTP Dev List] or contact me, [mailto:ryman@ca.ibm.com Arthur Ryman].
  
DITA is an XML format designed especially for authoring Help information. Several WTP components have DITA-based Help, but up until know, the DITA source has not been checked into CVS. Instead the generated HTML has been checked in and privately kept in synch with the DITA source. The main reason for this cumbersome process is that the tools to process DITA have been proprietary.  
+
DITA is an XML format designed especially for authoring Help information. Several WTP components have DITA-based Help, but up until know, the DITA source has not been checked into CVS. Instead the generated HTML has been checked in and privately kept in synch with the DITA source. The main reason for this cumbersome process is that the tools to process DITA have been proprietary.
  
 
== DITA-OT ==
 
== DITA-OT ==
  
 
But all that has changed with the availability of the [http://sourceforge.net/projects/dita-ot/ DITA Open Toolkit] (DITA-OT) project at SourceForge. Now there is a freely available toolkit so anyone can author using DITA. The [http://dita-ot.sourceforge.net/ DITA Open Toolkit Home Page] contains extensive documentation about DITA-OT, including notes on how to run the [http://dita-ot.sourceforge.net/doc/DITA-ant.html Ant scripts] to build Help documentation.
 
But all that has changed with the availability of the [http://sourceforge.net/projects/dita-ot/ DITA Open Toolkit] (DITA-OT) project at SourceForge. Now there is a freely available toolkit so anyone can author using DITA. The [http://dita-ot.sourceforge.net/ DITA Open Toolkit Home Page] contains extensive documentation about DITA-OT, including notes on how to run the [http://dita-ot.sourceforge.net/doc/DITA-ant.html Ant scripts] to build Help documentation.
 +
 +
== Getting Started ==
 +
 +
You'll need to install DITA-OT on your development machine.
 +
DITA-OT1.2 does not work with Eclipse. You need DITA-OT1.2.1 which was released on April 5, 2006. Download the code from
 +
[http://umn.dl.sourceforge.net/sourceforge/dita-ot/DITA-OT1.2.1_bin-ASL.zip DITA-OT1.2.1], or some other mirror.
 +
 +
Unzip DITA-OT1.2.1_bin-ASL.zip to the root of your C: drive. This creates the directory c:/DITA-OT1.2.1. If you unzip the code to a different directory, you'll have to pass that in to the Ant build script as the property dita.ot.dir (see build.xml).
 +
 +
FYI, DITA-OT1.2.1 corrects a critical bug that prevented the scripts being run in Eclipse due to an Ant error.
 +
The critical bug is: [http://sourceforge.net/tracker/index.php?func=detail&aid=1431229&group_id=132728&atid=725074 1431229 hardcoded path in MessageUtils.java].
 +
 +
DITA-OT requires an XML parser and XSLT engine. You can use Apache Xerces. If this is not included in the JRE you use to run Ant, you'll get a Class Not Found error.
 +
Either use a JRE that includes the required classes, or add the required classes to the classpath used by Ant.
 +
 +
Once DITA-OT and the required XML classes are installed, you can run the Ant build script. Do this after you edit the DITA source to generate the HTML pages. Perhaps one day the HTML generation will be automatic and incremental, just like the Eclipse JDT.
  
 
== Initial DITA Contribution ==
 
== Initial DITA Contribution ==
  
 
The initial contribution to WTP of DITA Help source has been attached to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=131837 bug 131837].
 
The initial contribution to WTP of DITA Help source has been attached to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=131837 bug 131837].
This source and build scripts tailored to Eclipse have been committed to HEAD and will be released to WTP 1.5 M6 pending successfully testing.
+
This source and build scripts tailored to Eclipse have been commited to WTP CVS. These plugins have been released as tag v200604111302 and will be in the WTP 1.5 M6 build.
  
 
Some folks on the DITA-OT project have been asking for examples to illustrate the problems. All the code is in CVS. Here are the links to the five Help plugins we are startings with:
 
Some folks on the DITA-OT project have been asking for examples to illustrate the problems. All the code is in CVS. Here are the links to the five Help plugins we are startings with:
Line 26: Line 42:
 
* [http://dev.eclipse.org/viewcvs/index.cgi/wst/components/doc/plugins/org.eclipse.wst.doc.user/?cvsroot=WebTools_Project org.eclipse.wst.doc.user]
 
* [http://dev.eclipse.org/viewcvs/index.cgi/wst/components/doc/plugins/org.eclipse.wst.doc.user/?cvsroot=WebTools_Project org.eclipse.wst.doc.user]
  
These plugins have been released as tag v200604111302 and will be in the WTP 1.5 M6 build.
+
== Next Steps ==
 +
 
 +
* Add DITA build to WTP batch build
 +
* Delete generated HTML from CVS
 +
* Add support for multiple ditamaps per plugin
 +
* Add support for infopops
  
 
== Problems Integrating DITA-OT into Eclipse ==
 
== Problems Integrating DITA-OT into Eclipse ==
Line 46: Line 67:
  
 
When you edit the DITA source, run the
 
When you edit the DITA source, run the
build.xml Ant script to regenerate the HTML and XML. You need to install the
+
build.xml Ant script to regenerate the HTML and XML.
DITA-OT1.2.1 beta on your development machine. This version corrects a critical
+
bug that prevents the scripts being run in Eclipse due to an Ant error.
+
The critical bug is: [http://sourceforge.net/tracker/index.php?func=detail&aid=1431229&group_id=132728&atid=725074 1431229 hardcoded path in MessageUtils.java]
+
 
+
DITA-OT1.2 does not work with Eclipse. You need DITA-OT1.2.1 which is currently a beta. Download the code form the following URL:
+
 
+
[http://internap.dl.sourceforge.net/sourceforge/dita-ot/DITA-OT1.2.1-bin-ASL.200603220441.zip DITA-OT1.2.1 beta]
+
 
+
Then unzip it to C:/DITA-OT1.2.1 (see the build.xml for the property).
+
  
 
=== Generated plugin.xml is Bad ===
 
=== Generated plugin.xml is Bad ===
Line 86: Line 98:
 
The problems occurred while I was connected to my LAN with an Ethernet cable
 
The problems occurred while I was connected to my LAN with an Ethernet cable
 
but dissappeared when I was wireless!!!!!
 
but dissappeared when I was wireless!!!!!
 +
 +
Here's a snippet from my console in case anyone else sees the same behavior:
 +
 +
 +
BUILD FAILED
 +
D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\build.xml:45: The following error occurred while executing this line:
 +
C:\DITA-OT1.2.1\conductor.xml:83: The following error occurred while executing this line:
 +
C:\DITA-OT1.2.1\pretargets.xml:147: Failed to copy D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita.pull to D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita due to D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita (Access is denied)
 +
 +
I edited another file, i.e. not csoap.dita.
 +
 +
== Other DITA solutions on Eclipse ==
 +
While DITA is becoming more popular more and projects and solutions (both open source and commercial) are appearing on Eclipse platform supporting DITA. Herea re some examples:
 +
* [http://www.eclipseplugincentral.com/Web_Links-index-req-viewlink-cid-1263.html DITA Open Platform ] - GPL project which goal is to provide an enterprise platform for the edition, management and processing of DITA documents.
 +
* [http://www.eclipseplugincentral.com/Web_Links-index-req-viewlink-cid-1369.html DITAworks ] - eclipse based documentation infrastructure designed around DITA that enables modeling (DITA specialization), authoring, management and processing of DITA content. Easily integratable into any Eclipse project as documentation nature.
 +
 +
 +
[[Category:Eclipse Web Tools Platform Project]]
 +
[[Category:Architecture Council|Authoring Eclipse Help Using DITA]]

Latest revision as of 14:57, 2 September 2009

Contents

[edit] Introduction to DITA

This page contains information about how to use DITA for authoring Eclipse Help. If you are using DITA in Eclipse and have questions, comments, etc., about integration, send a note to the WTP Dev List or contact me, Arthur Ryman.

DITA is an XML format designed especially for authoring Help information. Several WTP components have DITA-based Help, but up until know, the DITA source has not been checked into CVS. Instead the generated HTML has been checked in and privately kept in synch with the DITA source. The main reason for this cumbersome process is that the tools to process DITA have been proprietary.

[edit] DITA-OT

But all that has changed with the availability of the DITA Open Toolkit (DITA-OT) project at SourceForge. Now there is a freely available toolkit so anyone can author using DITA. The DITA Open Toolkit Home Page contains extensive documentation about DITA-OT, including notes on how to run the Ant scripts to build Help documentation.

[edit] Getting Started

You'll need to install DITA-OT on your development machine. DITA-OT1.2 does not work with Eclipse. You need DITA-OT1.2.1 which was released on April 5, 2006. Download the code from DITA-OT1.2.1, or some other mirror.

Unzip DITA-OT1.2.1_bin-ASL.zip to the root of your C: drive. This creates the directory c:/DITA-OT1.2.1. If you unzip the code to a different directory, you'll have to pass that in to the Ant build script as the property dita.ot.dir (see build.xml).

FYI, DITA-OT1.2.1 corrects a critical bug that prevented the scripts being run in Eclipse due to an Ant error. The critical bug is: 1431229 hardcoded path in MessageUtils.java.

DITA-OT requires an XML parser and XSLT engine. You can use Apache Xerces. If this is not included in the JRE you use to run Ant, you'll get a Class Not Found error. Either use a JRE that includes the required classes, or add the required classes to the classpath used by Ant.

Once DITA-OT and the required XML classes are installed, you can run the Ant build script. Do this after you edit the DITA source to generate the HTML pages. Perhaps one day the HTML generation will be automatic and incremental, just like the Eclipse JDT.

[edit] Initial DITA Contribution

The initial contribution to WTP of DITA Help source has been attached to bug 131837. This source and build scripts tailored to Eclipse have been commited to WTP CVS. These plugins have been released as tag v200604111302 and will be in the WTP 1.5 M6 build.

Some folks on the DITA-OT project have been asking for examples to illustrate the problems. All the code is in CVS. Here are the links to the five Help plugins we are startings with:

Here's the common plugin that contains the css, etc:

[edit] Next Steps

  • Add DITA build to WTP batch build
  • Delete generated HTML from CVS
  • Add support for multiple ditamaps per plugin
  • Add support for infopops

[edit] Problems Integrating DITA-OT into Eclipse

Here are my notes on integrating DITA-OT into Eclipse:

I've resolved as many of the problems as possible for now and have commited the DITA source and build scripts for the 5 plugins that Kate attached. Kate reviewed the generated HTML and corrected a few DITA markup errors. The initial contributions have been released as v200604111302.

There are a few outstanding problems:

[edit] Integration with releng Not Done Yet

The first stage is to have both the DITA source and the generated HTML and XML in CVS. I need to iron out the remaining problems before integrating the DITA builds into the releng builder.

When you edit the DITA source, run the build.xml Ant script to regenerate the HTML and XML.

[edit] Generated plugin.xml is Bad

The scripts generate bad plugin.xml files. I have therefore preserved the good copies as myplugin.xml. Our build script copies myplugin.xml over the generated plugin.xml, so make any edits to myplug.xml.

[edit] maplist Builds Not Supported

The scripts generate code from a *.ditamap file as input. However, the IBM contribution uses *.maplist files which list one or more *.ditamap files. Two plugins have two *.ditamap. To workaround this, please ensure that there is a "master" *.ditamap that pulls in all the *.dita files. We'll try to upgrade the scripts to support *.maplist files as input.

[edit] CSS Doesn't Match Eclipse Style

The *.css files that come with DITA-OT use a different style than Eclipse. They have been copied into the org.eclipse.wst.doc.user plugin. These *.css files, e.g. commonltr.css must be edited to give the correct style for Eclipse Help.

To fix this problem, copy the contents of common.css to the bottom of commonltr.css.

[edit] Sporatic "Access denied" Build Failure

I am hitting sporatic build failures while building modified DITA source files. I have reported this problem to the DITA-OT dev list. The problems occurred while I was connected to my LAN with an Ethernet cable but dissappeared when I was wireless!!!!!

Here's a snippet from my console in case anyone else sees the same behavior:


BUILD FAILED D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\build.xml:45: The following error occurred while executing this line: C:\DITA-OT1.2.1\conductor.xml:83: The following error occurred while executing this line: C:\DITA-OT1.2.1\pretargets.xml:147: Failed to copy D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita.pull to D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita due to D:\workspaces\WTP-Dev\org.eclipse.jst.ws.doc.user\temp\org.eclipse.jst.ws.doc.user\concepts\csoap.dita (Access is denied)

I edited another file, i.e. not csoap.dita.

[edit] Other DITA solutions on Eclipse

While DITA is becoming more popular more and projects and solutions (both open source and commercial) are appearing on Eclipse platform supporting DITA. Herea re some examples:

  • DITA Open Platform - GPL project which goal is to provide an enterprise platform for the edition, management and processing of DITA documents.
  • DITAworks - eclipse based documentation infrastructure designed around DITA that enables modeling (DITA specialization), authoring, management and processing of DITA content. Easily integratable into any Eclipse project as documentation nature.