Mailing-List: contact dev-help@openejb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@openejb.apache.org
Received-SPF: pass (athena.apache.org: domain of daniel.haischt@googlemail.com
 designates 66.249.92.168 as permitted sender)
Message-ID: <47E9341B.8060409@gmail.com>
Date: Tue, 25 Mar 2008 18:19:23 +0100
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US;
 rv:1.8.1.12) Gecko/20080213 Thunderbird/2.0.0.12 Mnenhy/0.7.5.666
MIME-Version: 1.0
To: dev@openejb.apache.org
Subject: [INFO] How to add context help to the Eclipse plugin
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
From: "Daniel S. Haischt" <daniel.haischt@googlemail.com>

Hi all,

I've added basic help support to the Eclipse plugin for
OpenEJB. Basically the context help and the standalone help
is contained within the following plugins:

* org.apache.openejb.help
* org.apache.openejb.help.nl1
* org.apache.openejb.help.nl2
* org.apache.openejb.help.nl2a
* org.apache.openejb.help.nlBidi

org.apache.openejb.help is the default and should contain
English only. org.apache.openejb.help.nl1 for example contains
German beside of other language dependent files. You should
note that anything beside of org.apache.openejb.help is a
fragment and not a plugin!

How are fragments structured? Example:
**************************************

* Basically any localized properties file can be stored in
   the root folder.
* Language dependent files like HTML files or images etc.
   should go into the folder nl/<lang_code>, where lang_code
   could be for example 'de'.

I prepared this kind of directory structure already. Tho,
of course the actual documentation and translation work
still needs to be done if we want a functional help plugin.

Basically the main entry points to the help system are...

* TOCs (table of contents -> toc*.xml)
* Indexes (index.xml)
* Context help (context.xml)

These files are stored in the root of the help plugin.

Context help (context.xml):
***************************

Contains IDs and references to an actual HTML file.

Example:

   <context id="test_id" title="Test">
     <description>TEST</description>
     <topic href="html/gettingstarted/maintopic.html" label="FooBar"/>
   </context>

The ID is test_id and must be reflected by the Java code.

How to associate a help ID with an SWT element?

AFAIK help IDs can only be associated with Controls, IActions, Menus
and MenuItems if using the setHelp() method. Please have a look at
the following page for further reference:

http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/ua_help_context_id.htm

In our case I did use the displayHelp() method which simply requires
you to specify the help context ID. This ID is composed of the plugin
name plus the actual context ID (here: test_id).

code example (ProjectSelectionPage):

@Override
public void performHelp() {
	PlatformUI.getWorkbench().getHelpSystem().displayHelp(
			"org.apache.openejb.help.test_id");
}

So as you can see the actual work that needs to be done regarding
the help system is ...

a) write the help contents (HTML or XML that may be transformed to HTML)
b) define context help IDs (in theory each widget may get an ID if using
    setHelp())
c) associate wizard pages and widgets with the actual context help IDs
    right within the code.

If this has been accomplish you would get approprate context help if
pressing F1 or clicking on the blue question mark icon.

Regards
Daniel S. Haischt