Installing the stand-alone help system

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

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 www.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_2.1.0\help.jar is on your app classpath. 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 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 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 command line

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

-command start | shutdown | (displayHelp [href]) [-eclipsehome eclipseInstallPath] [-host helpServerHost] [-port helpServerPort] [-servertimeout timeout] [platform options] [-vmargs JavaVMarguments]

A simple way to display help is to invoke

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help_2.1.0\help.jar org.eclipse.help.standalone.Help -command displayHelp

from within d:\myApp\eclipse directory. To display specific TOC file or topic use

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help_2.1.0\help.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_2.1.0\help.jar org.eclipse.help.standalone.Help -command start

[Optional] Installing a minimal set of plug-ins

The stand-alone help does not require the entire  Eclipse Platform package. It is possible to run the stand-alone help with the following plug-ins (located in the  eclipse\plugins directory):

org.apache.lucene
org.apache.xerces
org.eclipse.core.boot
org.eclipse.core.resources
org.eclipse.core.runtime
org.eclipse.help
org.eclipse.help.appserver
org.eclipse.help.webapp
org.eclipse.tomcat
org.eclipse.update.core

In addition to these plugins, depending on the operating system or machine architecture, you may need to also need to install the corresponding fragments for the above plugins (when they exist). For example, on Windows, you need to add the following fragments (also located in the eclipse\plugins directory):

org.eclipse.core.resources.win32
org.eclipse.update.core.win32

On Windows, it is possible to provide a different help browser (an SWT-embedded Internet Explorer web browser) by adding the following plugins and fragments on top of the minimal configuration:

org.eclipse.help.ui.win32
org.eclipse.help.ui
org.eclipse.jface.text
org.eclipse.jface
org.eclipse.search
org.eclipse.swt.win32
org.eclipse.swt
org.eclipse.text
org.eclipse.ui.editors
org.eclipse.ui.views
org.eclipse.ui.win32_2.1.0 org.eclipse.ui.workbench.texteditor
org.eclipse.ui.workbench
org.eclipse.ui

Copyright IBM Corporation and others 2000, 2003.