Tuesday, May 5, 2009

Working with Eclipse Help System (Version 3.4 - Ganymede)

Introduction:

Almost any application we work with needs a help system. The help system can be set up for normal workbench mode, remote infocenter mode (help via web) and standalone mode (for users who do not use eclipse). This article will guide you through how to add help menu, how to set up the help system using the workbench mode.

Adding help menu items:

Under your help menu, create a new command with commandId org.eclipse.ui.help.helpContents to add Help->HelpContents menu item. To add Search menu item, create a new command with commandId org.eclipse.ui.help.helpSearch. To add index menu item, create a new command with commandId org.eclipse.help.ui.indexcommand. You also need to make sure that the actions are registered. Add this block of code to makeActions(window) method in your ApplicationActionBarAdvisor to register them:

IWorkbenchAction action = ActionFactory.HELP_CONTENTS.create(window);
this.register(action);

action = ActionFactory.HELP_SEARCH.create(window);
this.register(action);

Generating sample help content:

The help content can either go with your source plugin or in a separate documentation plugin. I personally prefer to have it in a separate documentation plugin. Help is contributed by documentation plugins by using org.eclipse.help.toc extension point. The easiest way to add some help content is using the help content template which comes with Eclipse. Open plugin.xml and go to Extensions tab. Click on "Add" and type in org.eclipse.help.toc in extension point filter and in the available templates select Help Content and click Next. Make sure to select Primary checkbox, if you wish to contribute a main book to the help content. This will generate a bunch of toc xml files and sample html pages under html directory. Now, if you do Help->Help Contents you should be able to see the sample content.

Understanding help content:

If you look at plugin.xml, you will see that all of the toc* points to xml file. The primary toc.xml has several topics inside it and each topic can either specify link or anchor. In this case, you can see that all of the them are specifying anchors and not an actual link. These anchors can actually be used by any plugin to contribute help under that section. The primary toc would look like this:

<toc label="Sample Table of Contents" topic="html/toc.html">
<topic label="Getting Started">
<anchor id="gettingstarted"/>
</topic>
<topic label="Concepts">
<anchor id="concepts"/>
</topic>
<topic label="Tasks">
<anchor id="tasks"/>
</topic>
<topic label="Reference">
<anchor id="reference"/>
</topic>
<topic label="Samples">
<anchor id="samples"/>
</topic>
</toc>

If you see tocconcepts.xml, it uses anchor to contribute help i.e all topics inside this toc would go under the main topic which has this anchor. The link_to attribute takes care of this.

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

This is bottom-up composition. For top-down nesting, instead of defining anchors, the primary toc can instead create the links directly. Below is an example of top-down nesting, where links are directly used:

<toc label="Sample Table of Contents" topic="html/toc.html">
<topic label="Getting Started">
<link toc="toc_gettingStarted.xml"/>
</topic>
<topic label="Concepts">
<link toc="toc_concepts.xml"/>
</topic>
<topic label="Tasks">
<link toc="toc_tasks.xml"/>
</topic>
<topic label="Reference">
<link toc="toc_reference.xml"/>
</topic>
<topic label="Samples">
<link toc="toc_samples.xml"/>
</topic>
</toc>

Now, the secondary toc files (i.e tocconcepts.xml or toctasks.xml) do not need link_to attribute anymore.

Top down nesting is easier to understand but bottom up composition is preferred since it is very flexible and other plugins can contribute content to that section dynamically.

The actual help content is actually html pages. So, it does not matter how they are generated i.e using docbook or DITA or FrameMaker. As long as the html files are valid and they are structured properly, help will show up fine. You can also use XHTML to generate dynamic content.

Localization of help content:

By default, the toc files are in the base directory and the html pages reside under the html directory. For localizing the content, the content needs to be under nl/<languageCode> or nl/<languageCode>/<countryCode>. For example, for help content in german, the contents need to be in nl/de/DE directory. The content is first searched in nl/<languageCode>/<countryCode>. If it is not found, then it is searched in nl/<languageCode>. If it is not found there also, then it looks in the default base directory of the plugin.

The amount of documentation can quickly grow as your application gets bigger. Eclipse allows the documentation to be bundled in doc.zip file so that you can compress your documentation files. But, this works only when the plugin is deployed in unpacked form. Also, if you have localized help content, you cannot have one big doc.zip which has content for all languages. Instead, you need to have doc.zip for each of the languages under it's own nl directory.

Help Index:

To set up the help index, you need to use org.eclipse.help.index extension point. This extension point takes a index xml file and it looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<index version="1.0">
<entry keyword="Eclipse Concepts">
<entry keyword="Views">
<topic href="html/concepts/views.html" />
</entry>
<entry keyword="Editors">
<topic href="html/concepts/editors.html" />
</entry>
</entry>
</index>

This shows up in the help index page. Basically, this is similar to book keyword index. Here Eclipse concepts is shown as a folder under which you have two keywords - Views and Editors.

Don't confuse this with search index. Talking about search index, the index is built by eclipse, whenever user first does search on the help. If you have large number of help files and do not want your user to wait for a long time, then you also have the option of pre building index files and ship it along with your plugin. Basically, this is a tradeoff between time and space.

Customization:

The help contents window is very rich and offers lot of functionalities including searching, printing, bookmarking, moving between search results to table of contents etc., We can also customize some of the help contents window UI using the preferences defined in org.eclipse.help plugin. Some of the preferences are:

banner - To specify new banner at the top of the help
banner_height - To specify the height of the banner
help_home - To specify the custom html help home page, when help opens up
page_not_found - The page to show when the help topic html page is not found
windowTitlePrefix - To specify whether the help window show have "Help - " string prefixed
always_external_browser - Set this to true, if you want help to always open in external browser
bookmarksView - Set this to true or false to control the visibility of bookmarks view

Conclusion:

We saw how to add help to your menu, how to generate and understand help content, how to create index pages, how to localize and customize help functionality. Eclipse also supports context sensitive help, programmatic help and active help. I purposefully left them out for simplicity purpose. I will cover them in a separate article. Hope this article helps you in understanding and getting started with the Eclipse help system.

13 comments:

Stoobie said...

Thanks for the info, Raja.

For localizing the help plugin, could you give some more specifics for all the help plugin files? META-INF/MANIFEST.MF
preferences.ini
plugin.properties
contexts.xml
plugin.xml
toc.xml

Do they all go under nl/<languageCode>/<countryCode>?

tanushreemehra17 said...

Hi Raja,

Is there a tool that you know that can enable me to generate the Eclipse help project that I can directly import into the Help plug-in framework?

mnuttall said...

Instantiations has a tool

Raja said...

Sorry for the late reply. Somehow, I missed this comment.

Regarding the tool, we use DITA. DITA open toolkit has ways to generate Eclipse help.

Also, I believe FrameMaker has capability to generate Eclipse Help.

Hagen said...

Hi Raja!

Could you help me?...
I work with rcp help system. By pressing F1 help view appears. How can I get help view with only "related topics" and "about" block, but without "Dynamic Help",without "Go To" block("All Topics", "Search", "Indexes", "Bookmarks" links) and without popup menu in toolbar?
I've found some necessary preferences in preferences.ini file in org.eclipse.help.base for "Indexes" and "Bookmarks"(indexView, bookmarksView), but didnt find for other.

Raja said...

@Hagen - As far as I know, there is no way to customize the Help View. Generally in RCP, Activities API is used to filter out UI components during run-time. You could take a look at that, but I'm skeptical if that would be able to customize the help view.

Hagen said...

Hi Raja!Thank you for answer!!!

Could you help me again?...

Is it possible to open context sensetive help in external window by pressing F1?

Raja said...

@Hagen - As far as I know, you can open regular help contents in a browser, but not the context sensitive help. You can open context sensitive help either in dynamic help view or in infopopup. You can configure this using Help Preferences.

By external window, do you mean opening the help in Help Contents Window. If yes, then you can. For example, this link will open the help contents window and jump to the specified help topic.

"http://org.eclipse.ui.intro/showHelpTopic?id=//html/mytopicpage.html"

Raja said...

@Hagen - You can look at my other post to know more about context sensitive help and also programmatic help. I think invoking help programatically would be useful to you.

(http://rajakannappan.blogspot.com/2009/05/context-sensitive-help-in-eclipse.html)

Beth said...

Hi Raja. We'd like to add a "Feedback" button to the Help pages so that users/readers can email us feedback on what they read. HOw would you do that? Thanks in advance!

Raja said...

@Beth - We haven't tried making the help contents dynamic. How about adding a "mailto" link in your help pages, which user click on and send feedback via email. Just a thought...

Andrius Kurtinaitis said...

Is there a way to switch from one language to another?

Watson Zion said...

Eclipse has a build-in threw in one lot with system which allows to fly and retrieve the uphold system shortly from your Eclipse RCP application. The Eclipse uphold system is based on HTML, the "org.eclipse.help.toc" purview points and additional XML files which involve to the HTML files. Via the extension answer you Write my Research Paper for Me call a spade a spade the willingly level technique and answer to XML files. These XML files bring to screeching halt references to the pertinent HTML files.