Help Enhancements in Eclipse 3.1

This document describes new features added to provide for help and user assistance in Eclipse 3.1 release. The enhancements are still in progress and feedback is welcome. This document will be updated as changes are made towards the general availability of the release.

Help View

Most of the new help features revolve around the newly added Help view. The view is designed to be the universal location of most of the help needs inside the Eclipse workbench. The standard standalone help window from previous version is retained and is available via File>Help Contents. The role of the view is to bring help contents closer to the user inside the perspective where most of the work is done.

The new Help view can show various classes of content in pages that are shown one at a time. The following classes are currently available: Related Topics, All Topics and Search.

Related Topics

This page shows help topics related to the current workbench context. It replaces the yellow info pop window when F1 is pressed in the workbench. It is also shown when context help is asked for programmatically. The topics include context help contributed via help context help extension point, as well as the result of a local help search on the query formed from the current context. For example, if the currently active workbench part is 'Package Explorer' inside the Java perspective, local help will be searched for ("Package Explorer view" OR "Java perspective"). The first few results will be shown in place, with the possibility to follow the link to more elaborate search.

Related Topics page tracks changes in the workbench and updates accordingly. Workbench parts can affect the way Related Topics page works by supporting IContextProvider interface. This interface defines how the page should react to the active part:

public interface IContextProvider {
	/**
	 * State change trigger indicating a static context provider.
	 */
	int NONE = 0x0;

	/**
	 * State change trigger indicating that the provider should be asked for
	 * context help on each selection change.
	 */
	int SELECTION = 0x1;

	/**
	 * Returns the mask created by combining supported change triggers using the
	 * bitwise OR operation.
	 * 
	 * @return a bitwise-OR combination of state change triggers or
	 *         <code>NONE</code> for a static provider.
	 */
	int getContextChangeMask();

	/**
	 * Returns a help context for the given target. The number of times this
	 * method will be called depends on the context change mask. Static context
	 * providers will be called each time the owner of the target is activated.
	 * If change triggers are used, the method will be called each time the
	 * trigger occurs.
	 * 
	 * @param target
	 *            the focus of the context help
	 * @return context help for the provided target or <code>null</code> if
	 *         none is defined.
	 */
	IContext getContext(Object target);

	/**
	 * Returns a search expression that should be used to find more information
	 * about the current target. If provided, it can be used for background
	 * search.
	 * 
	 * @param target
	 *            the focus of the context help
	 * @return search expression as defined by the help system search, or
	 *         <code>null</code> if background search is not desired.
	 */
	String getSearchExpression(Object target);
}

Using the interface above can yield some interesting behavior. For example, if the context change mask is SELECTION, and getContext dynamically computes the context help for each selection, Related Topics will be highly dynamic. An example of this is support for Java editor where selections in the editor are reflected in the help view by showing the first sentence of Javadoc for the selected type.

All Topics

This page shows the Table of Contents tree you can also see in the classic Help window. The native Tree widget is tweaked somewhat to continue the 'web' user experience of the rest of the view. As a consequence, topics are opened on a single mouse click and cursor turns into a hand pointer when over the topics. However, tree item selections by the keyboard will not initiate the 'open' action - one needs to press 'Enter' to view the topic. This behavior provides for the expected keyboard navigation and makes the tree close in behavior to the counterpart in the Help window.

[

Search

One of the key new features in the new view is the Search page. The new mechanism supports federated search of multiple search engines running as background jobs. All engines run on the common search expression, but each engine's scope can be individually configured. Search expression follows certain rules that can be found when the label links above the text field is expanded:

If the provided text is not sufficient, the help link should be followed to find more information.

Search Types

The new search support starts by providing the new extension point for contributing engine types (extension point id 'org.eclipse.help.ui.searchEngine'). An engine type is a proto-engine that can be instantiated and configured to perform a particular search. At the moment, Eclipse Help view provides three engine types out of the box:

Local Help - searches the local help documentation. Instances of this type do not require any configuration.
Info Center - searches Eclipse help remote installation as Info Center. Instances of this type require the remote server URL.
Web Search - searches a general-purpose Web search engine. Instances of this type require the web search URL template with substitution variable for the query.

Most search needs can be satisfied by configuring one of the above search types. If that is not enough, new search types can be contributed using the above mentioned extension point. A good reason to contribute a new engine type is the existence of a separate domain where Eclipse users can find information for which there is a mechanism to issue complex queries and get results in a format suitable for parsing and presenting individually. For example, Info Center engine talks to the remote Web application to fetch the help books for scope configuration, as well as running the search and getting results in the XML format. If the remote search application does not provide results in a format that can be parsed, Web Search can be used to show the results in HTML format.

Instances of search engine types can be created in two ways:

Products can create engine instances as extension point contributions so that they show up out of the box
Users can create new engines by choosing from the list of available types and configuring the selected engine type on the fly

Configuring engines

Users can influence the search outcome in several ways. The fastest way to tweak the search is to control which engine should run when 'Go' is pressed. This is done by expanding the 'Scope Settings' section and checking the engines that need to run. More detailed scope manipulation can be done when 'Advanced Settings' link is selected.

The scope settings dialog is similar to preference pages and has nodes for each configured search engine. Each engine has a page that contains the master switch (linked to the one exposed in the scope section) and other scope settings below it. The actual widgets for configuring scope settings depend on the engine type. Local Help and Info Center types provide for narrowing the scope by selecting particular books. Web search type provides the URL template that is executed when search is performed.

Users can add to the list of preconfigured engines by pressing the 'New...' button at the lower left edge of the dialog. This button brings up a dialog allowing users to choose the search engine type:

All the settings made to the search engines are stored under one named preference set or Scope Set. Out of the box, the scope set that keeps the engine preferences is called 'Default'. By clicking on the scope name link in the Search page, it is possible to manipulate scope sets by creating new, editing and deleting them. Scope sets provide for quick switching between different search engine settings for all the configured engines at once.

Search results

When engines are selected for search, search expression is entered and Go is pressed, Search page will start each engine as a separate background job. As results arrive, they will be shown below the scope section grouped by engine (subject to selection of the tool bar button ). Search results consist of entries that can be navigated to, and optional short description if the search engine supports it. When there are many results, the page is kept manageable by breaking results in to groups of 10 (this number will be configurable in the future). Search results can be shown flat, or additionally grouped by category (tool bar button ), where category definition is provided by the results. For local help and Info Center, categories are books the results are coming from (e.g. Workbench User Guide, JDT ISV Guide etc.). Custom search engines can define their own categories.

Document Link Navigation

All the pages in the new Help view can be opened in two ways:

Internal- the page content will replace the content area of the view (except the quick links at the bottom)
External - the page will be shown in a separate window

The actual choice between the two options is controlled by several factors:

If the creation of the embedded browser page fails or the embedded browser in not supported on the particular OS, all links will be opened as external.
If the link represents a help topic, it will be shown as internal. However, external window can be forced either from the link's pop-up menu or (in case of search results) from the image link next to the topic. Topics shown in the external window will be shown in the context of the help system (with TOC).
If the link represents a random URL, it will be shown as internal. If external window is forced, it will be shown in a standalone web browser.
Search result objects that implement ISearchEngineResult interface can demand that their link is opened as external (see ISearchEngineResult.getForceExternalWindow()).
Help document shown inside the Help view can be opened in the external mode by following the tool bar button .

An orthogonal effort is currently under way to provide Platform UI support for showing URLs. URLs can be shown in a read-only web browser editor or an external browser suitable for the current OS/WS combination. When/if this support becomes available, the definition of 'External' in the context of Help view will be 'the page will be shown in a separate browser'. Whether this browser opens in the editor area or as a separate browser window will be user preference.