The Eclipse RCP Platform provides the following:

  • Online Help
  • Context-Sensitive Help
  • Dynamicly Generated Help

The litrature sugests the creation of separate documentation plug-ins. That is a plug-in that only consists of XML configuration files and HTML content for the help system.

In practice many plug-ins are package with there help files.

File Use
toc.xml table of contents for the top level "book"
toc*.xml table of contents associated with a heading
contexts*.xml maps context Ids to context-sensitive help

The above filenames are only a suggestion -
The help system actually makes use of extentions points allowing any file to be used.

plugin.xml is used to extend three kinds of extention points:

  • toc - table of contents
  • contexts
  • contentProducer - allows for dynamic generation of help

Online Help Files

The first configuration file used by Online help is one that is familiar to you - plugin.xml.

plugin.xml extention points:

<extension
         point="org.eclipse.help.toc">
      <toc file="toc.xml" primary="true"/>
      <toc file="tocconcepts.xml"/>
   </extension>

The next xml file is the above mentioned toc.xml file:

<toc label="XYZ User's Guide" topic="html/overview.html">
   <topic label="Concepts">
      <anchor id="concepts"/>
   </topic>
</toc>

And the tocconcepts.xml file follows a similar format:

<toc label="Concepts" link_to="toc.xml#concepts"> 
	<topic label="Main Topic"  href="html/concepts/maintopic.html"> 
		<topic label="Sub Topic" href="html/concepts/subtopic.html" /> 
	</topic>
	<topic label="Main Topic 2">
		<topic label="Sub Topic 2" href="html/concepts/subtopic2.html" /> 
	</topic> 
</toc>

The configuration files refer to the following directory structure:

toc.xml
tocconcepts.xml
html/overview.html
html/concepts/maintopic.html
html/concepts/subtopic.html
html/concepts/subtopic2.html

Help Category

Unable to render {include} Couldn't find a page to include called: Help Category

Context Sensitive Help

Context sensitive help (or InfoPops) is available when the user presses the F1 key.

Context sensitive help can be associated with:

  • Control
  • IAction - when used to generate a MenuItem (not toolbar)
  • Menu
  • MenuItem

plugin.xml file extention point:

<extension point="org.eclipse.help.contexts"> 
       <contexts file="contexts.xml" plugin="an.example.plugin"/>
   </extension>

Sample context.xml file:

<contexts>
  <context id="add_action_context">
    <description>This command adds.</description>
    <topic label="Add" href="tasks/tasks-1.htm"/>
    <topic label="Concepts" href="html/concepts/maintopic.html"/> 
  </context>
</contexts>

To contect everything up on the UI side of things we need to know the help contexts ids.

public interface IHelpContextIds {
	public static final String PREFIX = XYZPlugin.ID + "."; //$NON-NLS-1$
        // Dialogs
        public static final String CONNECTION = PREFIX + "connection_context"; //$NON-NLS-1$

        // View
        public static final String SEARCH_VIEW = PREFIX + "search_view_context";
        // Viewers
        public static final String SEARCH_VIEWER = PREFIX + "search_viewer_context"; //$NON-NLS-1$
	// Actions
	public static final String SEARCH_ACTION = PREFIX + "search_action_context"; //$NON-NLS-1$        
}

And finally the connection needs to be made to the control:

WorkbenchHelp.setHelp( newAction , HelpContextIds.NEW_REGISTRY_LOCATION_ACTION);

TODO: Dynamic Help

Figure out the contentProducer extention point in the hopes of generating context-sensitive help for DataStore parameter screens.

Sample Table of Contents Wizard

Eclipse provides a code generation template assocaiated with the toc extention point.

  1. Start the Extention Point Selection Wizard
    1. Open the plugin.xml file, and switch to the extentions point tab
    2. Press the "Add" button
  2. Start the "Help Content" template
    1. Select "org.exlipse.help.toc"
    2. Select "Help Content" from the available templates
    3. Next
  3. Chose the categories required for you plug-in
    1. Note the Primary check box will result in a separate top level "book" in the help system

This is enough to get us going.


[view] [edit]
(c) Copyright (c) 2004,2005 Refractions Research Inc. and others.