Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

---

Standalone help

If you are creating an application that is not based on the Eclipse framework, you can still use the Eclipse help system. Your application can package and install the stand-alone help system, a very small version of Eclipse that has everything except the help system stripped out of it. Then, your application can make API calls from its Help menu, or from UI objects, to launch the help browser. The stand-alone help system has all the features of the integrated help system, except workbench-integrated context help, the help view, and active help. When an application is not Java based, or help is required when the application is not running, it is possible to use stand-alone help from a system shell, a shell script or a desktop shortcut and provide command line options instead of calling Java APIs.

The stand-alone help system allows passing number of options that can be used to customize various aspects of the help system. The following options are supported:

• -eclipsehome eclipseInstallPath - specifies Eclipse installation directory. This directory is a parent to "plugins" directory and eclipse executable. The option must be provided, when current directory from which infocenter is launched, is not the same as Eclipse installation directory.
• -host helpServerHost - specifies host name of the interface that help server will use. It overrides host name specified the application server plugin preferences.
• -data instanceArea - specifies a path that Eclipse can use to write instance data. The value can be an absolute path of a directory, or a path relative to Eclipse installation directory. The option must be provided when Eclipse is installed in the read only location, or has been customized to override osgi.instance.area or osgi.instance.area.default properties.
• -port helpServerPort - specifies port number that help server will use. It overrides port number specified the application server plugin preferences.
• -dir ltr or -dir rtl - sets left-to right or right-to-left rendering direction of help UI in the browser.
• Additionally, most options accepted by Eclipse executable can be passed. They are especially useful during debugging and for applying customization to Eclipse. For example, passing an option

  
  -nl fr_FR
   

  will start help system in French language instead of a language specified by the machine's locale.

Installation/packaging

These steps are for the help system integrator and are not meant to address all the possible scenarios. It is assumed that all your documentation is delivered as eclipse plug-ins and, in general, you are familiar with the eclipse help system.

1. Download the eclipse Platform Runtime Binary driver from eclipse.org.
2. Install (unzip) the driver under your application directory, for example, d:\myApp. This will create an eclipse sub-directory, d:\myApp\eclipse that contains the code required for the eclipse platform (which includes the help system).

How to call the help classes from Java

1. Make sure d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar is on your classpath, where [version] is the version of the plugin you're using (e.g. org.eclipse.help.base_3.2.0.jar). The class you use to start, launch, and shut down the help system is org.eclipse.help.standalone.Help.
2. Create an array of String objects containing options that you want to pass to help system support. Typically, the eclipsehome option is needed.

   String[] options = new String[] { "-eclipsehome", "d:\\myApp\\eclipse" };

3. In your application, create an instance of the Help class by passing in the options. This object should be held onto until the end of your application.

   Help helpSystem = new Help(options);

4. To start the help system:

   
   helpSystem.start();
    

5. To invoke help when needed:

   
   helpSystem.displayHelp();
    

   You can also call help on specific primary TOC files or topics:

   helpSystem.displayHelp("/com.mycompany.mytool.doc/toc.xml");
   helpSystem.displayHelp("/com.mycompany.mytool.doc/tasks/task1.htm");

6. To launch context sensitive help, call helpSystem.displayContext(contextId, x, y) where contextId is a fully qualified context id. The screen coordinates, x and y, are not currently used.

7. At the end of your application, to shutdown the help system:

   
   helpSystem.shutdown();
    

How to call the help from the command line

The org.eclipse.help.standalone.Help class has a main method you can use to launch stand-alone help from the command line. The command line arguments syntax is:

-command start | shutdown | (displayHelp [href]) [-eclipsehome eclipseInstallPath] [-data instanceArea] [-host helpServerHost] [-port helpServerPort] [-dir rtl] [platform options] [-vmargs JavaVMarguments]

A simple way to display help is to invoke

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command displayHelp

from within d:\myApp\eclipse directory, where version is the plug-in's version. To display a specific TOC file or topic use

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command displayHelp /com.mycompany.mytool.doc/tasks/task1.htm

The calls above to display help will cause help system to start, display help, and keep running to allow a user to continue browsing help after the command is executed. To control the life cycle of the help system, use start and shutdown commands, in addition to the displayHelp command. For example, you may call

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar org.eclipse.help.standalone.Help -command start

[Optional] Installing a minimal stand-alone help system

The stand-alone help does not require the entire eclipse Platform package. It is possible to run the stand-alone help using only those plugins from the feature org.eclipse.help. To do this perform the following steps.

1. Download an eclipse SDK build and upzip it into two different locations, <location1> and <location1>
2. Remove the eclipse plugins directory from location1
3. Start Eclipse in location2 and import the org.eclipse.help feature into your workspace using File/Import/Plug-in Development/Features
4. Export the help feature and it's plugins to location1/eclipse using File/Export/Plug-in Development/Deployable Features. The plugins directory which was just deleted will be replaced by a directory containing a smaller number of plugins.
5. From location1 start standalone help from the command line as described in the previous section.

Some documentation plug-ins may have dependencies on other plug-ins, usually by specifying required plug-ins in their manifest. The dependent plug-ins need to be installed as well. Additionally, plug-ins that were designed for earlier than 3.0 version of eclipse implicitly require org.eclipse.core.runtime.compatibility plug-in being present to work.

See Product customization for more information on customizing the help system.