Creating help plug-ins and adding to the Rational help content

Content

Creating help plug-ins and adding to the Rational help information set

With the Eclipse Platform help system, you can contribute the online help that your plug-in contains by using the org.eclipse.help.toc extension point. In the Eclipse Platform, you can also use a help plug-in template to assist you in getting started. The following topics provide information about using the Eclipse help template, contributing to Eclipse-based online help, and adding to the Rational Help content.

These instructions are meant for users who are familiar with Eclipse plug-ins, creating plug-ins and features, and working with XML and other files associated with help plug-ins.

The following topics are discussed:

• Creating a help plug-in, using the Eclipse help template
• Adding your content to the help plug-in that you create with the help template
• Adding to the Rational help navigation (table of contents)
• Adding your help plug-in to the product

Creating a help plug-in using the Eclipse help template

To create a help plug-in:

1. In Eclipse, click File > New > New Project.
2. In the Select a wizard dialog box, select Plug-in Project.
3. Click Next.
4. Type a project name, and clear the Create a Java project check box; help plug-ins do not need Java. In the example workspace that follows, the plug-in is named my_help_plugin.
5. Click Next.
6. On the Plug-in Content wizard page, click Next.
7. On the Templates page, select Plug-in with sample help content:



8. Click Next.
9. On the Sample Help Table of Contents (TOC) page, complete these steps:
a. Type a label for the table of contents. This title will be displayed in the top level of the navigation or table of contents if you have Primary selected.
b. Select Primary in the Sample Help Table of Contents.
c. Click Finish.

Your workspace includes the following plug-in:




The file testToc.xml provides the navigation for a primary book; the elements in testToc.xml will be displayed at the top level of the navigation:



TOCs that are primary will appear at the top level. To appear in the tree, TOCs that are not primary must be pulled into (using a link element) or pushed into (using a link_to attribute and an anchor element) another TOC XML file. The template demonstrates the "pulling in" method, pulling toc.xml into testToc.xml at the <link> element. The testToc.xml tree is otherwise empty and would show nothing on the navigation tree were it not for toc.xml. A larger discussion of tree-building is available in the Eclipse Plug-in Developer's Guide (http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_nested.htm).




The plugin.xml file tells Eclipse which table of contents files to use. Table of contents files with the primary attribute set to true are displayed at the top-level of the navigation.




When you run an Eclipse application with this plug-in, you see your contribution to the help as in the following illustration. “Test TOC” is included in the top-level of the navigation because the primary attribute is set to true:

Adding your help content to the help plug-in that you created with the help template

After you create the plug-in, you can add your own content and update the testToc.xml file or the toc.xml file with your files. Typically you put the HTML files in the html folder, but the plug-in structure can be anything that meets your development needs, with content topics completely flat, or nested in any helpful folder structure (TOC XML files must reside at the plug-in root).. For example, if you create a mytopic.html file in the html folder, you can update the testTOC.xml as this screen capture illustrates:



When you run the application with the plug-in, “My Topic” is added to the navigation:

Adding to the Rational help navigation

The Rational help system uses a series of “container topics” that are the top-level books and anchors that enable the addition of subbooks to the containers.

To add your help topics to the Rational navigation, create a doc plug-in as described earlier with a toc.xml that links to one of the Rational anchor points in the com.ibm.help.common.nav.doc plug-in.

For example, to add to the API reference section, link to the api_ref anchor in the ref_toc.xml file:

1. Open the ref_toc.xml in the com.ibm.help.common.nav.doc plug-in to locate the api_ref anchor:

<toc label="Reference">
<anchor id="reference_general" />
<anchor id="api_ref" />
<anchor id="api_ref_extra" />
<anchor id="cmd_ref" />
<anchor id="cmd_ref_extra" />
<anchor id="examples_ref" />
<anchor id="examples_ref_extra" />
<anchor id="extpt_ref" />
<anchor id="extpt_ref_extra" />
<anchor id="files_ref" />
<anchor id="files_ref_extra" />
<anchor id="lang_ref" />
<anchor id="lang_ref_extra" />
<anchor id="msg_ref" />
<anchor id="msg_ref_extra" />
<anchor id="script_ref" />
<anchor id="script_ref_extra" />
<anchor id="settings_ref" />
<anchor id="settings_ref_extra" />
<anchor id="ui_ref" />
<anchor id="ui_ref_extra" />
<anchor id="gen_ref" />
<anchor id="gen_ref_extra" />
</toc>


2. Link your TOC file to the api_ref_extra anchor by using the link_to property as shown in this illustration:



3. Update the plugin.xml to include your XML table of contents file: my_api_ref.xml.

<plugin>

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

</plugin>

4. Run the application with your plug-in included. The updated help includes your API topic in the Reference book:



Note that the com.ibm.help.rational.nav.anchors.doc plug-in is provided as an example of adding topics to each of the Rational help anchor points. This plug-in can be found attached to the white paper. Every available top-level book has an anchor so users can extend the product help with their content.

Adding your help plug-in to the product

More information on these steps can be found in the Eclipse Platform Plug-in Developers Guide.

Create a feature for your help plug-ins:
1. In Eclipse, click File > New > Project.
2. Expand Plug-in Development.
3. Select Feature Project.
4. Name your feature and click Next.
5. In Reference Plug-ins and Fragments, click your help plug-ins.
6. Click Finish.

To add the feature and plug-ins to the product, create an update site project:

1. In Eclipse, click File > New > Project.
2. Expand Plug-in Development.
3. Select Update Site Project.
4. Name your project and click Next.
5. In the Update Site Map, add the feature you created in the previous section, and click Build.
6. Save the project.

To add the new feature to the your product, bring up the project that you want to customize, and follow these steps:
1. Click Help > Software Update.
2. Click Add Site.
3. Navigate to your Update Site project and click OK.
4. Expand your new entry in the available software and click your feature.
5. Click Install and then Close.
6. Restart the product.

You help will now be displayed as part of the product help.

Note: If your product uses web-based delivery of help content, you can add your help to your Eclipse product as described above and your local plug-in will merge seamlessly with the Web-supplied help. If you download help content to your local help or access help on an Enterprise server, you can add to the help using the Local Help Updater and the site.xml in the Update Site project you created for your new feature.