Eclipse_CSH Plug-in for Dynamic Context-Sensitive Help

This topic describes the eclipse_csh plug-in for the DITA Open Toolkit (DITA-OT), which generates complete, deployable Eclipse plug-ins that support dynamic context-sensitive Help for Eclipse-based applications.

Eclipse plug-ins generated by the DITA-OT, with the eclipse_csh plug-in, provide dynamic context-sensitive Help for Eclipse-based applications that define abstract Help contexts and use the ContextProviderDelegate (supplied by org.eclipse.datatools.help).

Abstract Help contexts allow UI developers to isolate the Eclipse Help system's concrete Help context ID strings and Help search expressions from the UI implementation (Java code). That gives user assistance (UA) content developers more control over Help contexts and context-specific content, so they can provide more useful, and more precisely targeted, dynamic context-sensitive help.

Overview

The Eclipse Help system uses two key pieces of data to find context-specific UA content for dynamic context-sensitive Help:

A Help context ID string, which associates a UI context with a particular chunk of context-specific content
A context-specific Help search expression, which the Help system uses to find additional, related content in its online documentation "library"

For many developers, one of the main problems with Eclipse dynamic context-sensitive Help is the necessity to embed Help context ID strings and context-specific Help search expressions in the UI code. That can reduce code portability, and it forces recompiling whenever a Help context ID string or a Help search expression needs to be changed. It makes UI implementation more cumbersome, particularly in an agile development (or RAD) environment. Unless all UI contexts are explicitly specified, and frozen in advance, developers are tempted to delay implementing context-sensitive Help to avoid otherwise unnecessary recompiling and rebuilding.

By using the org.eclipse.datatools.help.ContextProviderDelegate (the DTP help-helper, provided by the Eclipse Data Tools Platform project), and defining abstract Help contexts in their code, UI developers are free to implement dynamic context-sensitive Help at any point in the UI development cycle.

By using the DITA-OT, with the eclipse_csh plug-in, UA content developers (writers) and information architects can define the associations of Help context IDs with UA content, using special context-sensitive Help markup in a standard DITA map that produces an Eclipse online documentation plug-in. Content developers are free to revise the UI-UA context associations and context-specific Help search expressions at any time, without impacting UI code.

Setup and configuration

The eclipse_csh plug-in is available from the DITA-OT project on sourceforge.net: [URL pending final release to open source]

Download the eclipse_csh zip file (eclipse_csh_1.0.0.zip), and extract all files and folders into the plugins/ directory, in a previously installed DITA-OT.

Run the DITA-OT integrator.xml Ant buildfile to complete the plug-in installation.

Authoring

Any DITA map document that defines an Eclipse online documentation (doc) plug-in can be modified to also define a corresponding context-sensitive Help plug-in, by inserting the appropriate context-related markup.

Note: The DITA map markup described in this section does not require any DITA specializations; it relies entirely on standard DITA map elements and attributes.

DITA maps for context-sensitive Help plug-ins must contain a <topicmeta> element as the first child of the <map> element, and for each UI plug-in whose Help context IDs are identified in the map, that <topicmeta> element must contain one <othermeta> element that identifies the UI plug-in.

The <othermeta> element's name and content attribute values will be used to identify UI plug-ins in the org.eclipse.help.contexts extension, which is declared in the plug-in manifest (plugin.xml file) of the context-sensitive Help plug-in. For example:

<map id="org.eclipse.datatools.ui.doc">
   <topicmeta>
      ...
      <othermeta name="ui-plugin"
         content="org.eclipse.datatools.connectivity.ui"/>
      <othermeta name="ui-plugin"
         content="org.eclipse.datatools.connectivity.ui.dse"/>
   </topicmeta>
   ...
</map>

The name attribute value "ui-plugin" is a fixed, literal string. The content attribute value is the Eclipse plug-in ID of a UI plug-in.

DITA maps for context-sensitive Help plug-ins contain <resourceid> elements, each of which identifies a concrete Help context ID associated with a DITA topic.

The <resourceid> element is a child of a <topicmeta> element. For example:

    <topicmeta>
        <resourceid id="help_context_ID_string"/>
    </topicmeta>

For each DITA topic associated with a Help context ID, the <topicref> element that points to that topic contains a <topicmeta> element (with a <resourceid> child element). This defines the association of a Help context ID with that topic. For example:

    <topicref navtitle="label attribute in contexts.xml topic element"
        href="path/to/topic.xml">
        <topicmeta>
            <resourceid id="help_context_ID_string"/>
        </topicmeta>
    </topicref>

Any DITA topic can be mapped to multiple Help context IDs by inserting as many <resourceid> child elements as necessary in the <topicmeta> element. For example:

    <topicref navtitle="label attribute in contexts.xml topic element"
        href="path/to/topic.xml">
        <topicmeta>
            <resourceid id="help_context_ID_1"/>
            <resourceid id="help_context_ID_2"/>
            <resourceid id="help_context_ID_3"/>
        </topicmeta>
    </topicref>

Other considerations for DITA maps that define context-sensitive Help plug-ins:

Markup for context-to-topic mapping is needed only for the DITA topics that will be context-sensitive Help targets (i.e., Related Topics shown in the Help view).
When a single DITA topic appears more than once in a map, only the first instance of a <topicref> that points to that topic needs the context-sensitive Help markup.
Nested maps that contribute DITA topics related to Help contexts must include the same context-sensitive Help markup.

Each <topicmeta> element that wraps a <resourceid> element may optionally contain one <searchtitle> element or one <shortdesc> element, or both (one of each), to provide context-specific Help content.

The <searchtitle> element is used to supply the value of the title attribute on the <context> element in the Eclipse context XML file.
The <shortdesc> element is used to supply the content of the <description> element in the Eclipse context XML file.

For example:

    <topicref navtitle="label attribute in contexts.xml topic element"
        href="path/to/topic.xml">
        <topicmeta>
            <searchtitle>Optional text to override the help About \
            title.</searchtitle>
            <shortdesc>Text for context description.</shortdesc>
            <resourceid id="help_context_ID_string"/>
        </topicmeta>
    </topicref>

Note: The <searchtitle>, <shortdesc>, and <resourceid> elements must appear in the <topicmeta> element in the order shown above.

A DITA map that contains the example shown above produces the following content in an Eclipse context XML file:

    <contexts>
        ...
        <context id="help_context_ID_string"
            title="Optional text to override the help About title.">
            <description>Text for context description.</description>
            <topic label="label attribute in contexts.xml topic element"
                href="PLUGINS_ROOT/doc_plugin_ID/path/to/topic.xml"/>
        </context>
        ...
    </contexts>

where doc_plugin_ID is the value of the id attribute on the <map> element.

Integration

To provide dynamic context-sensitive Help, an Eclipse-based application must define 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 defined in an Eclipse context XML file. Another method (getSearchExpression) must return a context-specific 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 (org.eclipse.datatools.help.ContextProviderDelegate).

The helpKeyProperties extension point allows any plug-in to contribute ResourceBundle properties files that define 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 first generate an Eclipse online documentation plug-in.

Eclipse plug-ins produced by eclipse_csh handle the mapping of Help contexts to context-specific Help content, and provide support for the DTP help-helper infrastructure by contributing:

Eclipse context XML files, which supply the context-specific Help content for each Help context, and point to other Help topic contributions directly related to the Help context
Java properties files, which define key-value pairs that map abstract Help contexts (helpKey constants) to concrete Help context IDs and context-specific Help search expressions

Eclipse plug-ins produced by eclipse_csh do not contribute (or contain) any topic-based UA content. Their context XML files 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 collaboration.

Development teams are primarily responsible to:

Implement the Eclipse classes and methods necessary to enable dynamic context-sensitive Help for all appropriate UI controls.
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 files for the helpKey constants interface classes. Java source files 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-specific Help content and context-specific Help search expressions for appropriate UI Help contexts.
Define the concrete Help context ID strings that associate abstract Help contexts with context-specific Help content.
Create the Java properties files that define the mapping of abstract Help contexts to concrete Help context IDs.
Create the context-sensitive Help UA plug-ins that contribute Eclipse context XML files and the Java properties files.
Test the context-sensitive Help UA plug-ins and online documentation plug-ins, with UI components provided by Development teams.

Documentation teams should rely on the Java source files (for the helpKey constants interface classes) as the original and definitive sources of all helpKey constant strings.

Note: Creating the Java properties files can be somewhat automated (e.g., by processing the Java source files with a simple PERL™ script).

The following summarizes the Documentation team workflow to create Eclipse context-sensitive Help plug-ins:

Get the helpKey list (provided as a Java source file) from the UI Development team for each UI plug-in.
Analyze the helpKey list and associated UI controls to define the Help contexts.
The Documentation team must determine whether:
- The helpKey constants alone are sufficient 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 defined to combine groups of helpKey constants into common Help contexts.
Tip: It may be preferable to combine Help contexts in the helpKey properties file, instead of defining 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.
Analyze the Help contexts and existing (or planned) Help topics to define context-specific Help search expressions.
Create helpKey properties files, based on the content of each Java source file.
- Define the mapping of helpKey constants to concrete Help context IDs and context-specific Help search expressions, based on results of the Help context analysis and Help topic (content) analysis.
- Save the helpKey properties files in source control, as appropriate.
Tip: The helpKey properties files are flat ASCII text files, so authors (or IAs) responsible for defining the Help context IDs and context-specific Help search expressions should use a suitable ASCII text editor to create and edit those files.
Modify existing DITA maps (if used to produce Eclipse online documentation plug-ins) to add the markup for context-sensitive help.
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.

Summary

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 benefits:

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 define 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 define and modify context-specific 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.

For more information about the DTP help-helper, see: http://www.eclipse.org/datatools/doc/20080310_DTP_Help-Helper.pdf.

Dave Resch

Sybase Inc.

OASIS DITA Help Subcommittee