Eclipse Help

This topic provides an overview of how to use the DITA Open Toolkit to develop content for the Eclipse Help system.

According to the Eclipse Web site, the Eclipse integrated development environment (IDE) is an "open source platform comprised of extensible frameworks, tools and runtimes for building, deploying and managing software across the lifecycle." Eclipse can be installed on Windows, Macintosh® OS X, or Linux (32–bit or 64–bit).

The Eclipse Help system is itself extensible, allowing additional documentation to be delivered using Eclipse's plug-in framework. It can be used in three different modes: workbench, standalone, and infocenter.

Workbench mode is for documentation for tools integrated into the Eclipse IDE.
Standalone mode serves a similar purpose, but is used for software that is not Eclipse-based.
Infocenter mode allows the Eclipse Help system to deliver topics through the World Wide Web. Local instances of the Eclipse Help system can also retrieve and integrate content from a remote server running Help in infocenter mode.

The Eclipse Help system contains search and indexing features, allows the triggering of workbench actions or Eclipse code from within Help topics, supports dynamic content and link filtering (when using XHTML), and supports globalization. You can even use Eclipse to manage the development, building, and testing of your DITA-sourced documentation plug-ins.

Overview

The Eclipse Help displays HTML- or XHTML-formatted topics, and organizes the topics according to the XML-formatted Table of Contents (TOC) files that are provided in each plug-in that contains documentation.

For more information on developing Help for Eclipse, refer to the documentation for the current Eclipse release, available on http://www.eclipse.org.

Setup and configuration

DITA Open Toolkit

The DITA Open Toolkit contains the transformations necessary to produce all of the files required for Eclipse Help plug-ins. No special setup or configuration is necessary. Refer to installation and configuration instructions within the DITA Open Toolkit to set it up.

Eclipse

Download Eclipse from http://www.eclipse.org. Installation involves unpackaging an archive file to any location on your machine. A Java Runtime Environment (JRE™) is required. Eclipse manages your development resources in workspaces, that also can be any location on your machine. You are prompted to select or create a workspace location to use each time you start Eclipse.

Eclipse documentation plug-ins

Documentation for the Eclipse Help system can be included in any plug-in, as long as the plug-in extends Eclipse's org.eclipse.help.toc extension point. It is up to the individual organization whether to include documentation inside code plug-ins or in their own plug-ins. There are several advantages to the latter, such as unambiguous plug-in ownership, or if the contents of the documentation plug-in will be globalized.

Plug-ins are named according to the Sun™ Java package naming guideline (for example, org.eclipse.help). Plug-ins that contain only documentation typically have .doc at (or near) the end of the plug-in name.

Within a plug-in, two XML files are required in the root (a manifest and a table-of-contents (TOC) file). Any number of content files may be included, in any location within the plug-in. The TOC file can be generated from a DITAMAP file, and HTML files will be generated from DITA files.

Plug-ins can be delivered to the Eclipse run-time environment as folders or as Java archive (JAR) files. Documentation within folders may exist in archives (for example, doc.zip). Archives cannot be nested (that is, a doc.zip cannot be included in a plug-in delivered as a JAR file).

Authoring

Author DITA topics as you would normally. You can include any number of topic files, folders, DITA maps, or other file-based resources that can be delivered within browser environment (for example, images or multimedia).

When creating links to other topics (XREFs or LINKs), note links to topics in other plug-ins should be coded as follows:

PLUGINS_ROOT/PLUGIN_ID/path/to/target.html

Where PLUGINS_ROOT/ indicates that the target file is in another plug-in and PLUGIN_ID is the ID of the plug-in as declared in the manifest file. Refer to the Eclipse documentation regarding Help server and file locations in Help content: http://www.eclipse.org/documentation/.

Integration

To integrate your content into Eclipse, manually create a plugin.xml file that points to one or more TOC files in the plug-in, and a manifest.mf file (in a META-INF folder).

Plugin.xml file

This example plugin.xml file is similar to the one provided with the Garage sample in the DITA-OT. This example shows the minimum amount of information required to declare a TOC file to the org.eclipse.help.toc extension point.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin>
	<extension point="org.eclipse.help.toc">
		<toc file="hierarchy.xml"/>
	</extension>
</plugin>

Manifest.mf

In current versions of Eclipse, some of the manifest information, such as the plug-in ID, is separated into the manifest.mf file. Manifest.mf is stored in the plug-in in a folder named META-INF For the Garage sample, here is a possible manifest:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Garage Plug-in
Bundle-SymbolicName: org.dita.garage.doc
Bundle-Version: 1.0.0

Note that what was the plug-in ID in the plugin.xml file is referred to as the Bundle-SymbolicName in the manifest.mf file.

TOC file

TOC files are generated from DITA map files. You may include any number of TOC files in a plug-in, as long as they are declared in the plugin.xml file.

From the Garage sample, here is hierarchy.xml:

<?xml version="1.0" encoding="UTF-8"?>

<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Garage (hierarchy)" topic="concepts/garagetasks.html">
<topic label="Garage Tasks" href="concepts/garagetasks.html">
<topic label="Organizing the workbench and tools" href="tasks/organizing.html"/>
<topic label="Taking out the garbage" href="tasks/takinggarbage.html"/>
<topic label="Spray painting" href="tasks/spraypainting.html"/>
<topic label="Washing the car" href="tasks/washingthecar.html"/>
</topic>
<topic label="Garage Concepts" href="concepts/garageconcepts.html">
<topic label="Lawnmower" href="concepts/lawnmower.html"/>
<topic label="Paint" href="concepts/paint.html"/>
<topic label="Shelving" href="concepts/shelving.html"/>
<topic label="Tool box" href="concepts/toolbox.html"/>
<topic label="Tools" href="concepts/tools.html"/>
<topic label="Water hose" href="concepts/waterhose.html"/>
<topic label="Wheelbarrow" href="concepts/wheelbarrow.html"/>
<topic label="Workbench" href="concepts/workbench.html"/>
<topic label="Windshield washer fluid" href="concepts/wwfluid.html"/>
</topic>
</toc>

Building DITA content in Eclipse

It is possible to use Eclipse as your IDE for developing, building, and testing your Eclipse plug-in projects. Refer to the DITA Open Toolkit User Guide topic entitled "Running DITA builds in Eclipse."

Output

Detailed instructions exist in the DITA-OT Help for producing Eclipse Help. Refer to DITA Open Toolkit User Guide topic entitled "Processing to Eclipse Help targets."

The image shows the content after it has been transformed and the plug-in has been added to a basic Eclipse run-time environment.

Figure 1. Eclipse Run-time Environment

If you intend to take advantage of active Help or the dynamic content capabilities within the Eclipse Help system, such as link filtering, be prepared to create your own post-processing transforms to incorporate the required markup.

Summary

Whether creating documentation for an Eclipse-based application or for a standalone Eclipse Help implementation, consider DITA for your source content. Since Eclipse Help is one of the key output targets for the DITA Open Toolkit, setup, configuration, and processing are all straightforward and well-documented. For additional instructions on such advanced Eclipse Help capabilities as active Help, dynamic content, or remote Help, refer to the current Eclipse documentation, located at http://www.eclipse.org/documentation/.

Jeff Antley

IBM Corporation

OASIS DITA Help Subcommittee