The Eclipse help system is a component of the Eclipse Platform. It is used for displaying, browsing, searching, and printing online documentation. It also interacts with the Eclipse-based UIs through context-sensitive help (launching the help system from the user interface) and active help (launching a UI action from the help system content).
The help system not only presents online documentation about the Eclipse SDK and tooling, but also lets developers add their own documentation to it. Also, it can be used apart from the rest of Eclipse as a help system for non-Eclipse based applications or other projects. It can be installed either locally or on a web server.
The V2 help system supports the following product scenarios:
Integrated - If you are creating an Eclipse-based product,
the help system is automatically provided. You can launch the help browser from the Help menu in the
workbench, or through infopop links.
Stand-alone (local) - 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 had 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, as
described in the following sections. However, it interacts with the
application UI for features such as context-sensitive help or active help will
vary. All features except infopops and active help are supported.
Infocenter (served) - You can also allow your users to access the help system over the Internet or their intranet, by installing the stand-alone help system and the documentation plug-ins on a web server. The application accesses the documentation by calling a URL, and the help system is shown in their web browser. The infocenter help system can be used both for client applications and for web applications, either of which can have their help accessed remotely. All features except infopops and active help are supported.
Plug-ins that contribute documentation content ("doc plug-ins") created for one of these scenarios will work in any of the scenarios, without any revision (although infopops and active help may not be supported by your UI).
The help browser displays the navigation for the documentation in a frame on the left-hand side of the window.
The navigation trees are created with XML, following the help system's TOC DTD which is available in drivers. The XML trees are essentially nested lists of topic elements, each with an associated label and an optional href (a relative link to a content file). To form the whole navigation tree, merge together trees from individual plug-ins or XML files. You can build the tree in either a bottom-up or a top-down fashion:
The Eclipse help system provides search functionality via the Lucene search engine and a front end that is specific to the Eclipse help system. Information about the engine is available at http://www.lucene.com/. Eclipse makes no modifications to the Lucene code, but provides a front end and other functionality.
Some aspects of search can be controlled by language analyzers that can be provided through extension for every language. English and German analyzers are provided. They offer very high quality searches by performing the following:
If no analyzer is provided for a particular language, a simple default analyzer will be used. Words composed of English characters or digits can still be found.
From an exploiting product's standpoint, there is no effort involved in getting search to work. The search engine and UI are packaged as plug-ins. Indexes are generated the first time the user runs a search. You also have the option of pre-generating indexes so that they are available the first time search is used (this is particularly useful in the infocenter scenario). Indexes are re-generated each time a documentation plug-in is added or removed. First-use generation performance is satisfactory for several hundred topics. You may want to test if you will be using many more topics.
The search engine currently searches only HTML. Also, only those topics which appear in the navigation tree will be indexed.
An infopop is a small, light-weight box that contains a description of a UI widget, and links to related topics. To launch an infopop, put focus on the widget (either by clicking on it, putting the cursor in it, or pressing Tab until the focus indicator is on it), and press F1. If you want more information than what is provided in the description, click one of the links. This will open the help browser to the Links view and the topic you clicked; the other links from the infopop will be listed.
The UI developer must assign a context ID to each widget that needs an infopop. This context ID associates the widget with its infopop content. You can register the following kinds of objects for infopops:
Infopop content is written in XML, following the Contexts DTD, which is available in drivers. For each context ID there is a description and optionally one or more links. The XML files containing infopop content can be packaged in the code plug-in that also contains the UI objects it describes, or it can be packaged in another plug-in.
You can define infopop content for a particular context ID in more than one
XML file, in more than one plug-in. When an infopop is displayed, content
defined in the code plug-in itself is listed first; additional descriptions
and links, if any, are appended to the first set.
Any user interface can launch the help browser by calling a help system API. This API can take a topic href as an attribute and thus open the browser to that topic.
Also, it may be launched by running an executable, which can also take a URL as a parameter; this lets you set up launch points from the desktop or the Windows Start menu, and so on.
In the integrated scenario, a documentation topic can contain a special link that calls a class from the workbench. Using this, the user can launch workbench actions from the documentation. For example, consider a topic called "Importing external plug-ins". Instead of telling the user to go to the workbench and select File > Import, and then select External Plug-ins and Fragments and click Next, the topic could simply say "Click here to open the Import External Fragments wizard." The link would call a class you have defined, which in turn would open that wizard to that page.
The help system will be available on:
*secondary testing status
The help system displays online documentation inside an HTML viewer provided by a Web browser. The standard browsers, such as Internet Explorer, Mozilla, Netscape, are pluggable into the help system, but require an adapter. The Eclipse help system provides one adapter for each platform, as shown below. These adapters are for the system browsers shipped with the OS, except for Windows NT where IE must be upgraded to at least v5.
| Platform | Browser adapter supplied |
|---|---|
| Windows XP | Internet Explorer 6 |
| Windows 2000 | Internet Explorer 5 |
| Windows 98SE | Internet Explorer 5 |
| Windows NT | Internet Explorer 5+ |
| Windows ME | Internet Explorer 5.5 |
| Redhat Linux 7.2 | Mozilla 0.9 or greater |
| SuSE Linux 7.3 | Mozilla 0.9 or greater |
| Sun Solaris 8 | Netscape 4.7 |
| HP-UX 11i | Netscape 4.x |
| AIX 5.1 | Netscape 4.x |
For additional information about plans and restrictions, see Supported Browsers in Eclipse V2.
The help system displays better in Mozilla, and best in Internet Explorer.
We recommend you work with and require the browsers listed above. If you want your users to use a browser other than the ones listed above, you must ensure that it is available on their platform (i.e., you may have to get them to install a browser that didn't come with their OS), and you must supply your own adapter.
Integrated scenario
There is a Help preferences page that lets the user choose from the available browser adapters to select which browser they prefer to view help in.
Stand-alone scenario
If you want to allow users to select among browsers (if more than one adapter is available), you must provide your own UI for doing this.
Infocenter scenario
In this scenario, the Web browser is the help browser. It's recommended that you use one of the supported browsers (listed above).
The help system fully supports Latin-1 locales and, on Windows platforms, DBCS locales. The help system will also display BiDi navigation and content.
The design for help content (doc.zip) and infopop content has not changed since V1. However, the name of the extension point for help contributions has changed, and the XML for creating and merging navigation TOC trees has been simplified. This means that plugin.xml and all navigation XML files will need a moderate amount of re-writing. V1-level navigation is not supported.
Also, support for nested contexts and context computers for infopops has been removed, meaning that code that registers UI objects via arrays or context computers will have to be changed.
Also, support has been removed for putting translatable strings from the XML into doc.properties and context.properties. Translatable strings must remain in the XML.