Add Help to HALE

1 Creating a basic framework

1.1 Create a Plug-In Project

Adding a Help function to HALE needs you first to create a new Plug-In Project. In Eclipse select "File -> New -> Project...". Now select "Plug-In Project" then enter your Project Name and make the following settings.

Remove the checks at "Use default location" if HALE is not in your default location otherwise don't remove the check. But in both cases remove the check at "Create a Java project". Then klick "Next" and "Finish".

1.2 Make first Configurations

Now open your "MANIFEST.MF" file and copy&paste the following settings:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: YOURBUNDLENAME
Bundle-SymbolicName: YOURPROJECTNAME;singleton:=true
Bundle-Version: 1.0.0.qualifier
Bundle-Vendor: Fraunhofer IGD
Require-Bundle: org.eclipse.ui,
org.eclipse.help.ui,
org.eclipse.help,
org.eclipse.help.webapp,
org.eclipse.equinox.http.jetty

We can now delete the "html"-folder and the "testTOC.xml"-file because we will get them from other projects that will get a help function. Open your "Extension" index tab and delete "testToc(toc)". Then select your "toc.xml(toc)" and set the combo box "primary: true". Your file name should now be "(toc)".

1.3 Create a keybinding

You can also configure a binding for your help to get called (e.g. F1). This requires you to add another Extension Point. Click on "Add..." and select "org.eclipse.ui.bindings". After this you can add a Key to your Extension Point:

Now configure your Key similarly to this example:

Eclipse has a predefined command to display the help function. So we can use that commandID.

1.4 Finish your basic framework

Actually there is one last step to create your basic framework for your help function. Open your toc.xml source Code and copy this into your file(below your code header):

<toc label="Sample Table of Contents">
</toc>

Now you have your basic framework for your help function to work on.

2 Integrate other ToCs to your basic framework

2.1 Configure the plugin.xml file

Open the plugin.xml of your project you want a help function for. Navigate to tab "Dependencies" and add "org.eclipse.help.ui" to the required plug-ins. Then go on to tab "Extensions" and add "org.eclipse.help.toc". It is recommended to create a "html" folder for the pages the help function shows in HALE. All help pages are written in html format, so you need some knowledge in html to create a (good) help page. After you have written your help page(s) you need to create a .xml-file to link the html content with your table of contents. Creating a .xml-file is as follows: File -> New -> Other -> "Help Table of Contents". Make sure the .xml-file is in the right project! Choose a file name and press "Finish". You can change the table of contents' name and add your html files to your table of contents here. Easiest way is to "Add Topic": Just choose a name of the page that will be shown by clicking on the name and select your html file (should be "html/FILENAME.html"). You can also "Add Topic" -> "Add Anchor" e.g. for bigger sub topics. This should look like this:!http://chrizzly.ch.funpic.de/HALE/help/subtopic.jpg! Difference between these 2 options is you don't have to set a location for your "SubTopic" in the second case. You just need to set an anchor ID ("sub" in this example). But option 2 needs some steps more to work. You need a connection between your anchor ID and a help page (.html file). This happens in another .xml-file. So create another new .xml-file as above. Important here is now to set the anchor for your "Book". To link it correctly you have to follow the convention: "TOC_WHERE_ANCHOR_ID_IS_SPECIFIED#ANCHOR_ID" (e.g. toc.views.xml#sub in this example). After linking your files you do the same as in option 1, "Add Topic", choose name, select file.

2.2 Add Help Tables to plugin.xml/Extensions

Now add all your help tables (.xml-files) you want your help function to show:

To choose your file klick on "Browse..." and select the desired table of contents. Repeat this step until all your help tables are integrated. "primary" setting should be "false" for all tables.

2.3 Link Help Tables to Help Project

Back to the initial Help Project. Open the toc.xml and you should see this window now:

You can change the name of your table of content (1) and add links (2) to the help file in your project you want a help file for. For example your table of contents can look similarly to this:

Congratulations you added a Help function to HALE! You can always add/remove other Help pages as above (to remove, follow the steps backwards).

3 Context sensitive Help

For context sensitive Help see http://www.vogella.de/articles/EclipseRCPHelpSystem/article.html -> 1.5 Context sensitive help

4 Creating a Table of Contents

4.1 Rough Table of Contents

To get a good overview of what your table of contents should contain you need to create a first rough table of contents. First you need a dummy.html file to get your topics shown in your help (if you don't include this file you will see an empty table of contents when you call your program's help). Open your help project and create a new HTML file into the "html" folder. Name it "dummy.html" or something like that. Now type some text into the body of that file (<body>ENTER TEXT HERE ! </body>).
Next you can start creating your rough table of contents by adding "Topic" to the book or to other topics (this is if you want subtopics). Name thge topics and then select the location of your dummy.html file (should be "html/dummy.html"). Do this for all of your topics. This can e.g. look like this:

4.2 Replace rough topics

Now you can particularize your table of content by replacing the rough topics with e.g. links to the help files (.xml + .html) in other projects. This can look similarly to this:

Repeat that replacement until your table of contents contains all detailed topics and no more dummies.

5 Internationalize your Help

5.1 Internationalize via Fragment-project

First create always a single fragment project for each language you want to translate to. The name should be almost the same as the host plug-in. e.g. like this:

When you create the fragment-project be sure to browse the host plug-in that your fragment belongs to. In this example the creation wizard would look like this:

At least you just have to keep the hierarchy which the system specifies. The help system will first search in the "nl/language/country" directory, afterwards in the "nl/language" directory and if it doesn't find anything there then it searches in the root folder of the plug-in directory. The "nl/language/country" directory is optional, so you can use for example for german content "nl/de". In this example we use the "nl/de" directory in the fragment project and the simple root directory in the "main" project.