where doc_plugin_ID is the value of the id attribute on the <map> element.
To provide dynamic context-sensitive help, an Eclipse-based application must deﬁne the associations between its UI
controls and help contexts dynamically, by implementing methods of org.eclipse.help.IContextProvider. One of those
methods (getContext) must return a concrete help context ID string, which matches an IContext object contributed by
an extension of org.eclipse.help.contexts, and deﬁned in an Eclipse context XML ﬁle. Another method
(getSearchExpression) must return a context-speciﬁc help search expression, if the application requires more targeted
search results than the default help search expression provides.
The DTP help-helper plug-in (org.eclipse.datatools.help) provides a "help key" extension point
(org.eclipse.datatools.help.helpKeyProperties), and supplies a context provider delegate implementation
• The helpKeyProperties extension point allows any plug-in to contribute ResourceBundle properties ﬁles that deﬁne
the mapping of abstract help keys to concrete help context IDs and help search expressions.
• The ContextProviderDelegate, along with abstract help keys, enables help context abstraction for any UI control that
implements methods of IContextProvider.
The eclipse_csh plug-in for DITA-OT provides the processing to generate context-sensitive help plug-ins, which serve
as companions to Eclipse online documentation plug-ins generated by DITA-OT (using its standard dita2eclipsehelp
transtype). Indeed, the dita2eclipse_csh transtype target depends on the dita2eclipsehelp target to ﬁrst generate an Eclipse
online documentation plug-in.
Eclipse plug-ins produced by eclipse_csh handle the mapping of help contexts to context-speciﬁc help content, and
provide support for the DTP help-helper infrastructure by contributing:
• Eclipse context XML ﬁles, which supply the context-speciﬁc help content for each help context, and point to other
help topic contributions directly related to the help context
• Java properties ﬁles, which deﬁne key-value pairs that map abstract help contexts (helpKey constants) to concrete
help context IDs and context-speciﬁc help search expressions
Eclipse plug-ins produced by eclipse_csh do not contribute (or contain) any topic-based UA content. Their context XML
ﬁles refer to topics contributed by their companion documentation plug-ins.
Successful delivery of Eclipse dynamic context-sensitive help requires close coordination of UI components and UA
components. It imposes responsibilities on both Development teams and Documentation teams, and it requires ongoing
Development teams are primarily responsible to:
• Implement the Eclipse classes and methods necessary to enable dynamic context-sensitive help for all appropriate
• Implement interface classes that declare helpKey constants for each UI plug-in.
• Provide lists of the helpKey constants to Documentation teams in a timely manner.
• Test the context-sensitive help UI implementation, with context-sensitive help UA plug-ins and online documentation
plug-ins provided by Documentation teams.
Development teams should provide lists of helpKey constants in the form of Java source ﬁles for the helpKey constants
interface classes. Java source ﬁles provided as helpKey lists must include appropriate help context comments to provide
information about each associated UI control.
Documentation teams are primarily responsible to:
• Develop context-speciﬁc help content and context-speciﬁc help search expressions for appropriate UI help contexts.
• Deﬁne the concrete help context ID strings that associate abstract help contexts with context-speciﬁc help content.
• Create the Java properties ﬁles that deﬁne the mapping of abstract help contexts to concrete help context IDs.
Draft | Developing DITA-based Help for Existing Help Environments | 17
• Create the context-sensitive help UA plug-ins that contribute Eclipse context XML ﬁles and the Java properties ﬁles.
• Test the context-sensitive help UA plug-ins and online documentation plug-ins, with UI components provided by
Documentation teams should rely on the Java source ﬁles (for the helpKey constants interface classes) as the original
and deﬁnitive sources of all helpKey constant strings.
Note: Creating the Java properties ﬁles can be somewhat automated (e.g., by processing the Java source ﬁles with
a simple perl script).
The following summarizes the Documentation team workﬂow to create Eclipse context-sensitive help plug-ins:
1. Get the helpKey list (provided as a Java source ﬁle) from the UI Development team for each UI plug-in.
2. Analyze the helpKey list and associated UI controls to deﬁne the help contexts.
The Documentation team must determine whether:
• The helpKey constants alone are sufﬁcient to identify actual help contexts, and thus, a helpKey constant could
be mapped directly to a concrete help context ID, with the same string value as the helpKey constant.
• Distinct help context ID strings must be deﬁned to combine groups of helpKey constants into common help
Tip: It may be preferable to combine help contexts in the helpKey properties ﬁle, instead of deﬁning the
mapping for multiple help contexts to a single topic in a DITA map. This is a judgment call for the Documentation
team responsible for maintaining DITA maps.
3. Analyze the help contexts and existing (or planned) help topics to deﬁne context-speciﬁc help search expressions.
4. Create helpKey properties ﬁles, based on the content of each Java source ﬁle.
• Deﬁne the mapping of helpKey constants to concrete help context IDs and context-speciﬁc help search expressions,
based on results of the help context analysis and help topic (content) analysis.
• Save the helpKey properties ﬁles in source control, as appropriate.
Tip: The helpKey properties ﬁles are ﬂat ASCII text ﬁles, so authors (or IAs) responsible for deﬁning the help
context IDs and context-speciﬁc help search expressions should use a suitable ASCII text editor to create and
edit those ﬁles.
5. Modify existing DITA maps (if used to produce Eclipse online documentation plug-ins) to add the markup for
6. Build Eclipse plug-ins, using the DITA-OT with the eclipse_csh plug-in, and test the Eclipse plug-ins with UI
components provided by Development teams.
Help context abstraction is a technique to simplify the handling of help context IDs and help search expressions in the
UI code, by abstracting them to "help keys."
Help context abstraction provides the following beneﬁts:
• Development teams are free to associate new help contexts with UI controls, without necessitating that corresponding
help context IDs or help search expressions exist.
• Documentation teams are free to deﬁne UA help contexts, modify help context IDs, and control the mapping from
abstract help contexts to concrete help context IDs, without necessitating any change in the UI code.
• Documentation teams are free to deﬁne and modify context-speciﬁc help search expressions, and the mapping from
abstract help contexts to help search expressions, without necessitating any change in the UI code.
This separation of responsibilities enables the project team to provide higher quality, and more precisely targeted,
dynamic context-sensitive help.
18 | Draft | Developing DITA-based Help for Existing Help Environments
For more information about the DTP help-helper, see:
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, Mac 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
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 ﬁltering (when using XHTML), and supports
globalization. You can even use Eclipse to manage the development, building, and testing of your DITA-sourced
The Eclipse Help displays HTML- or XHTML-formatted topics, and organizes the topics according to the XML-formatted
Table of Contents (TOC) ﬁles 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
Setup and configuration
DITA Open Toolkit
The DITA Open Toolkit contains the transformations necessary to produce all of the ﬁles required for Eclipse Help
plug-ins. No special setup or conﬁguration is necessary. Refer to installation and conﬁguration instructions within the
DITA Open Toolkit to set it up.
Download Eclipse from http://www.eclipse.org. Installation involves unpackaging an archive ﬁle 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 ownership
or if content will be globalized.
Plug-ins are named according to Sun's 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.
Draft | Developing DITA-based Help for Existing Help Environments | 19
Within a plug-in, two XML ﬁles are required in the root (a manifest and a table-of-contents (TOC) ﬁle). Any number
of content ﬁles may be included, in any location within the plug-in. The TOC ﬁle can be generated from a DITAMAP
ﬁle, and HTML ﬁles will be generated from DITA ﬁles.
Plug-ins can be delivered to the Eclipse run-time environment as folders or as Java archive (JAR) ﬁles. 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 ﬁle).
Author DITA topics as you would normally. You can include any number of topic ﬁles, folders, DITA maps, or other
ﬁle-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:
Where PLUGINS_ROOT/ indicates that the target ﬁle is in another plug-in and PLUGIN_ID is the ID of the plug-in
as declared in the manifest ﬁle. Refer to the Eclipse documentation regarding Help server and ﬁle locations in Help
To integrate your content into Eclipse, manually create a plugin.xml ﬁle that points to one or more TOC ﬁles in the
plug-in, and a manifest.mf ﬁle (in a META-INF folder).
This example plugin.xml ﬁle 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 ﬁle to the org.eclipse.help.toc extension
<?xml version="1.0" encoding="UTF-8"?>
In current versions of Eclipse, some of the manifest information, such as the plug-in ID, is separated into the
manifest.mf ﬁle. Manifest.mf is stored in the plug-in in a folder named META-INF For the Garage sample,
here is a possible manifest:
Bundle-Name: Garage Plug-in
Note that what was the plug-in ID in the plugin.xml ﬁle is referred to as the Bundle-SymbolicName in the
TOC ﬁles are generated from DITA map ﬁles. You may include any number of TOC ﬁles in a plug-in, as long as they
are declared in the plugin.xml ﬁle.
From the Garage sample, here is hierarchy.xml:
<?xml version="1.0" encoding="UTF-8"?>
20 | Draft | Developing DITA-based Help for Existing Help Environments
Documents you may be interested
Documents you may be interested