This article (continually in progress) documents my experiences in creating documentation and help for an Eclipse plug-in. If you're delivering documentation or help for an Eclipse-based project, feel free to add to this article.


Eclipse is an opensource community. One of its primary projects is the creation of "an extensible development platform...for building software." This platform takes shape in the Eclipse workbench, a Java-based IDE (Integrated Development Environment).

The Basics

Since Eclipse is Java-based, it stands to reason that its help system is based on Sun's JavaHelp. There are many similarities between Eclipse's help system and Sun's JavaHelp — but there are also several important differences. I'll try to highlight these items in this article

If you're familiar with JavaHelp you'll be ahead of the curve. If you're not, don't worry... the curve isn't too sharp.

An Eclipse documentation project (called a "plug-in") is made up of:

• An XML file that defines the plug-in
• A separate HTML file for each documentation topic (or "page")
• Additional XML files for the table of contents, keyword index, and context-sensitive help.

Sample Documentation Demo

Creating the Plug-in

Your documentation plug-in is defined by a plugin.xml file. This file contains:

• The name of your documentation plug-in
• A unique ID to identify your plug-in. Other plug-ins can reference your content by this ID.
• "Extension Points" to create items such as a table of contents (TOC), keyword index (IX), and context-sensitive help.

The -+plugin.xml+- file is similar to JavaHelps's *.hs (helpset) file. This table defines some of the key differences:

JavaHelp Uses...	Eclipse Uses...
-+<title>+-	-+<plug-in name="...">+-
-+<view>+-	-+<extension point>+-

Here is a sample -+plugin.xml+- file for our sample documentation plug-in.
<?xml version="1.0" encoding="UTF-8"?>
<plug-in name="Demo Documentation Plug-in" id="org.eclipse.demo.doc" version="1.0.0">
 <extension point="org.eclipse.help.toc">
  <toc file="toc.xml" primary="true"/>
 </extension>
 <extension point="org.eclipse.help.index">
  <index file="index.xml"/>
 </extension>
</plug-in>

Creating the Table of Contents

The table of contents for the documentation is defined by the -+toc.xml+- file, just as it is in JavaHelp (and OHJ). The key differences are the names of the labels, as defined in this table:

JavaHelp Uses...	Eclipse Uses...
-+target+-	-+href+-
-+text+-	-+label+-
-+tocitem+-	-+topic+-

Turning your JavaHelp's table of contents into Eclipse is fairly straightforward and trivial. You'll also need to include a definition type of org.eclipse.help.toc at the beginning of the file.

Here's a sample Eclipse toc.xml:
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
 <toc label="My Guide">
  <topic label="Getting Started">
   <topic href="file002.htm" label="Some Topic" />
   <topic href="file004.htm" label="Yet Another Topic" />
  </topic>
 </toc>

This would produce the following table of contents in Eclipse:

Sample of the TOC.

To Open or Show?

By including (or omitting) the label attribute in the topic element of each item in the toc.xml, you can control its behavior: Will clicking the link open a specific page, expand the items to show its children, or both?

In the previous example, clicking the Getting Started node will simply expand the node to show the its child (Some Topic). Clicking the Some Topic node will show the page file002.htm and its child node (Yet Another Topic).

Multiple Tables of Contents

If you have an exceptionally long (or detailed) table of contents, you may consider creating a separate toc.xml file for each major category (e.g., concepts, tasks, references, etc.). You simply add each toc file to your -+plugin.xml+-.

For example, if your project contained three toc files:

• toc_concepts.xml
• toc_tasks.xml
• toc_referneces.xml

Your plugin.xml would define each file within the toc extension point:
 <extension point="org.eclipse.help.toc">
  <toc file="toc.xml" primary="true" />
  <toc file="toc_concepts.xml" />
  <toc file="toc_tasks.xml" />
  <toc file="toc_references.xml" />
 </extension>

The Eclipse documentation contains additional information.

Defining the Keyword Index

The keyword index (not to be confused with the search index) is a traditional "back of the book" index: an alphabetical list of keywords and terms. This functionality was introduced in Eclipse 3.2.

The index for the documentation set is defined by the -+index.xml+- file, just as it is in JavaHelp (and OHJ). The key differences are the names of the labels, as defined in

this table:

JavaHelp Uses...	Eclipse Uses...
-+target+-	-+href+-
-+text+-	-+keyword+-
-+indexitem+-	-+entry+-

As with the table of contents, turning your JavaHelp's index into Eclipse is fairly straightforward and trivial. Here's a sample Eclipse -+index.xml+-:
<?xml version="1.0" encoding="UTF-8"?>
 <index version="1.0">
  <entry keyword="alpha">
   <topic href="mypage.htm" />
  </entry>
  <entry keyword="beta">
   <entry keyword="foo">
    <topic href="myotherpage.htm" />
   </entry>
   <entry keyword="bar">
    <topic href="morepages.htm" />
   </entry>
  </entry>
 </index>

This would produce the following table of contents in Eclipse:

Sample of the TOC.

Adding Documentation Topics

In Eclipse, the documentation pages are delivered as HTML pages. For this sample documentation plug-in, you'll need three HTML files: mypage.htm, myotherpage.htm, and morepages.htm.

Note that the Eclipse help system is case sensitive — in order to link between pages you'll need the exact filename.

The Eclipse Doc Style Guide provides pointers and conventions used when creating Eclipse-style documentation.

Packaging and Testing the Sample

To test the sample plug-in:

1. Place the plugin.xml, index.xml, and toc.xml files in a new folder.
2. Name the folder identically to the id that you used in the plugin.xml file. In this sample, the folder is named org.eclipse.demo.doc.
3. Place the three documentation HTML pages in the org.eclipse.demo.doc folder.
4. Copy the org.eclipse.demo.doc folder to your eclipse/plugings folder.
5. Restart Eclipse with the -clean option.

After the Eclipse workbench appears, select Help > Help Contents. Your documentation should appear in the Contents pane of the Eclipse Help Center:

Sample documentation plug-in.

You can expand and collapse the items in My Guide and open the documentation pages.

Adding Online Help

You have seen how to add documentation to Eclipse and have it appear in the Eclipse Help Center. Now we will add online help to the plug-in. Let me first define some terms to makes sure we're all on the same page:

• Online Help: In this article, online help refers to context-sensitive assistance that the user receives for a specific UI element in Eclipse. In Eclipse, online help is displayed in an infopop or within the Help view.
  • Infopop: The help content appears in a "pop-up" near the currently selected UI element:

    Sample of an Eclipse infopop. Click for full image.

  • Help view: The help content appears in a separate window or view, embedded within the Eclipse interface:

    Sample of an Eclipse help view. Click for full image.

• Dynamic Help: In an Eclipse help system, dynamic help refers to a list of related topic links generated dynamically by the Eclipse help engine. These dynamically generated links appear only in the help view. Infopops do not display these links (although there is a link to change from infopop to help view.

Note: Eclipse help is also "dynamic" in the sense that the content displayed in the Help view can change automatically as the user selects a different UI widget. This happens without forcing the user to re-press F1.

Adding Context-Sensitive Online Help

For Eclipse, the online help content, (i.e., the text shown in either an infopop or the Help view as the result of pressing F1) is contained in a separate XML file: -+contexts.xml+-.

First, we need to "add" this contexts.xml file to the documentation plug-in. We need to add the following extension to the plugin.xml file:
<extension point="org.eclipse.help.contexts">
 <contexts file="contexts.xml" plug-in="org.eclipse.demo.doc"/>
</extension>

Now we can create the actual contexts.xml file. Remember, the online help shows only a few lines of text — not a complete page. This is much different than JavaHelp, which uses a mapping file to match help topic IDs with a specific HTML page.

The infopop and help view samples shown earlier were created with a -+contexts.xml+- file similar to:
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.contexts"?>
<contexts>
 <context id="select_a_wizard_dialog">
  <description>Choose the type of resource you would like to create.</description>
  <topic label="Resources" href="./org.eclipse.platform.doc.user/concepts/concepts-12.htm" />
 </context>
</contexts>

• The context element contains a single attribute: id. This is your help topic ID. This is the unique ID that the developer attaches to the UI widget.
• The description element is the actual help text.
• The topic element allows you to add a list of related topic links. These links are different than the Dynamic Help links, which Eclipse provides automatically. The label attribute is the text for the link; the href is the documentation file to open...relative to the location of the contexts.xml file. In this example, the Resources link will open the concepts-12.htm page in the org.eclipse.platform.doc.user plug-in. You can easily link to other documentation plug-ins.

Setting the ID in Code

To assign the help topic to the UI widget, your developer simply uses the setHelp method in org.eclipse.ui.help.WorkbenchHelp. You must supply both your plug-in's ID and the help topic ID.

For example, to add the ID "select_a_wizard_dialog" with a the dialog box in the application (as shown in the previous samples), you would use the following code:
WorkbenchHelp.setHelp(myDialogBoxn, org.eclipse.demo.doc.example.select_a_wizard_dialog);

The Eclipse documentation contains additional information on how to declare a help topic in code.

Searching the Documentation

The search functionality for your documentation plug-in is handled automatically by Eclipse. The first time you perform a search, you may notice a message indicating that the search index is being rebuilt.

If you make changes to the doc set, you'll need to have Eclipse rebuild the search index. This ensures that when users perform a search of the documentation, they will be getting results from the current doc set.

To force Eclipse to rebuild the search index, delete the following folder:
\eclipse\configuration\org.eclipse.help.base\index

Then restart Eclipse with the -clean option. After starting up, Eclipse will rebuild the index.

Using the Eclipse Plug-in Tool

You can create the beginnings of a documentation plug-in from within Eclipse, itself. Eclipse contains a documentation plug-in template that will help you get started defining most of the XML file.

1. In Eclipse, select File > New > Project.
2. In the New Project dialog, select Plug-in Project.
3. On the Plug-in Project of the New Plug-in Project wizard, enter your documentation project's ID and click Next.
   
4. On the Plug-in Content page, enter a name for your project and click Next.
   
5. On the Templates page, select the Sample Help Content template and click Next.
   
6. On the Sample Help page, enter a label for the TOC and click Finish. You can also specify if your plug-in contains multiple toc files.
   

Eclipse creates your project, including the plugin.xml, toc.xml and all additional toc files.


The Eclipse documentation contains additional information on creating plug-ins.

Using Other Help Authoring Tools (HATs)

There are several third-party tools that can be used to generate Eclipse documentation plug-ins from your source material (such as FrameMaker, MS-Word, etc.):

• Mif2Go produces Eclipse Help from FrameMaker files.
• list of more tools to come

Although some do not support Eclipse help directly, they do generate JavaHelp. As shown in this article, conversion from JavaHelp to Eclipse is straightforward.

Setting End-user Preferences

The end-user can control several interface and display options, while using your documentation plug-in.

Preferences - Help page. Click for full image.

Some of these options include:

• Using Eclipse's internal browser or another web browser to display the documentation content.
• Displaying help content in either an infopop or a help view
• Defining the scope of search results.

Getting Fancy

coming soon

Using Cheat Sheets

Cheat sheets are "views that help guide the user through a series of complex tasks to achieve an overall goal."

Users can select a cheat sheet from Help > Cheat Sheets.



To add cheat sheets to your plug-in, fist add the extension to the plugin.xml file:
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
 <category name="My Cheatsheets" id="com.eclipse.myplugin.category"/>
 <cheatsheet name="Title of my cheatsheet" category="com.eclipse.myplugin.category" contentFile="$nl$/cheatsheets/my_cheatsheet.xml" id="com.eclipse.myplugin.cheatsheet.my_cheatsheet">
  <description>This is my first Eclipse cheatsheet.</description>
 </cheatsheet>
</extension>

• The category element allows you to create a new category for your cheat sheet (or list your cheat sheet in an existing category) on the Cheat Sheet Selection dialog.
• The cheatsheet element defines each cheat sheet.
  • name: The title that will appear in the Cheat Sheet Selection dialog.
  • contentFile: The XML file that contains the actual cheat sheet.
• The description element displays a brief description of the cheat sheet.

Using Call Backs

coming soon

Finding More Help

• Yahoo mailing group eclipse_tw: http://groups.yahoo.com/group/eclipse_tw/
• Eclipse foundation: http://www.eclipse.org and http://help.eclipse.org
• Eclipse Documentation Guidelines

---