Difference between revisions of "Authoring Eclipse Help Using DITA"

From Eclipsepedia

Jump to: navigation, search
(Initial DITA Contribution)
(Fixed CSS Problem by copying current common.css)
Line 61: Line 61:
 
files, e.g. commonltr.css must be edited to give the correct style for Eclipse
 
files, e.g. commonltr.css must be edited to give the correct style for Eclipse
 
Help.
 
Help.
 +
 +
To fix this problem, copy the contents of common.css to the bottom of commonltr.css.

Revision as of 15:07, 6 April 2006

Contents

Introduction to DITA

This page contains information about how to use DITA for authoring Eclipse Help.

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

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.

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 committed to HEAD and will be released to WTP 1.5 M6 pending successfully testing.

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. These are in HEAD now and have not been released. Please test them and confirm that the Help looks ok before I release them. There are a few outstanding problems:

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. You need to install the 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: 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:

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

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.

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.

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.