CSHelp Plug-in

This topic provides an overview of the DITA Open Toolkit (DITA-OT) plug-in named cshelp (for Context-Sensitive Help).

The cshelp plug-in generates contexts files in the format that Eclipse-based applications use for Context-Sensitive Help. The standard DITA-OT transforms can be used to produce XHTML® output. This chapter focuses on producing Eclipse contexts files.

Overview

If you develop code plug-ins that extend the Eclipse user interface or develop documentation for development teams that do, you either already are or should be incorporating Context-Sensitive Help into the user interface.

The Eclipse user interface allows you to display Context-Sensitive Help as an infopop or in the Dynamic Help view. The latter option includes information and functionality in addition to the contents of the Context-Sensitive Help topic.

Figure 1. Eclipse User Interface and Help
Example of Context-Sensitive Help in
an Eclipse wizard

For more information on contexts files and developing Context-Sensitive Help for Eclipse, refer to the documentation for the current Eclipse release, available on http://www.eclipse.org.

The cshelp plug-in was developed by a team of writers representing the various software brands in IBM®, led by the author. It is currently in use by products in several brands that develop applications for the Eclipse environment.

Setup and configuration

The cshelp plug-in is available from the DITA-OT site on sourceforge.net:

http://sourceforge.net/project/showfiles.php?group_id=132728

Figure 2. cshelp Plug-in Download
Partial list
of downloads for DITA-OT, including the cshelp plug-in

Download and unzip the plug-in into your DITA-OT installation (typically, the <DITA-OT>/demo directory).

Figure 3. cshelp Installation

To complete the installation, open a command prompt and run the Ant integrator build file from your DITA-OT directory (ant -f integrator.xml).

Authoring

The structure of a cshelp DITA file mirrors that of an Eclipse contexts file. A contexts file is an XML file that contains one or more context elements inside a containing <contexts> element. Each context element contains a unique ID, the text of the Context-Sensitive Help topic, and optionally, links to Help topics in the Help system.

<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.contexts"?>
<contexts>
    <context id="new_wizard_selection_wizard_page_context">
        <description>
	        Choose the type of resource you would like to create.
        </description>
        <topic label="Resources" href="concepts/concepts-12.htm"/>
    </context>
    …
</contexts>

Similarly, a cshelp DITA file contains one or more cshelp elements inside a containing <cshelp> element (which is otherwise unused). Each nested cshelp element contains a unique ID, text, and related links.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE cshelp PUBLIC "-//OASIS//DTD DITA CSHelp//EN"
 "..\demo\cshelp\dtd\cshelp.dtd">
<cshelp id="csh_outer_container" xml:lang="en-us">
  <title>sample1_context</title>
  <shortdesc></shortdesc>
  <csbody></csbody>
  <cshelp id="new_wizard_selection_wizard_page_context">
    <title></title>
    <shortdesc>Choose the type of resource you would like to create.</shortdesc>
    <csbody>
    </csbody>
    <related-links>
      <link format="htm" href="concepts/concepts-12.htm" scope="peer">
        <linktext>Resources</linktext>
      </link>
    </related-links>
  </cshelp>
  ...
</cshelp>

It is important to note that the only highlighting markup that can be used inside Eclipse Context-Sensitive Help is the bold (<b></b>) tag, and the only formatting options are the carriage return and the space key. All of these are permissible only inside the description element. When sourcing Context-Sensitive Help in DITA, all of the highlighting and formatting markup options that are available in the shortdesc and body elements of the topic type may be used. The transform that produces a contexts file from the DITA source produces output that conforms to the restrictions of the contexts file. In most cases, the output approximates what would be seen in HTML output, but some DITA elements are simply ignored:

Table and simpletable
Image (only the text in the <alt> attribute or tag will display)
Object
Figure (only the text in the <desc> tag will display)
Footnote
Indexterm, indextermref
Xref

Use as many DITA files per Eclipse plug-in that you want, and create a simple DITA map file inside the plug-in that points to each of them. Include any copyright information in the DITA map; this information will appear in comment tags in each generated contexts file. Note, however, that relationship tables (reltables) cannot be used to create related links when producing Eclipse contexts files.

Integration

Refer to the Eclipse documentation for instructions on incorporating context IDs in code plug-ins. This information is typically in Platform Plug-in Developer Guide > Programmer's Guide > User assistance support > Help > Context-Sensitive Help > Declaring a context ID.

http://www.eclipse.org/documentation/

Output

When processing the DITA map file, there are two parameters that need to be set:

Use the switch that identifies a separate XSL file, and point to the dit2context.xsl file in the cshelp/xsl directory. For example, if you are using Ant:
```
<property name="args.xsl" value="${dita.dir}${file.separator}demo${file.separator}
cshelp${file.separator}xsl${file.separator}dit2context.xsl"/>
```
Use the switch that indicates the output extension of the generated file will be XML. For example, if you are using Ant:
```
<property name="args.outext" value="xml"/>
```

The contents of the generated XML file should resemble the example contexts file in the Authoring section.

Summary

Context-Sensitive Help is an integral part of the user assistance for software applications. If you already use DITA to source your Eclipse documentation plug-ins, sourcing the Context-Sensitive Help in DITA allows you to maintain a consistent authoring and build environment and consistently formatted output.

Jeff Antley

IBM Corporation

OASIS DITA Help Subcommittee