Remote Help proposal for Eclipse 3.3

Curtis d'Entremont, 01/02/2007

The problem

Packaging a comprehensive set of help contents with a product can significantly increase its size. Consider the eclipse SDK as an example. The download size for 3.2 on Windows is 120MB, of which 30MB is documentation (compressed). This results in longer downloads, larger media, and more required disk storage.

The solution

Overview

Host the content on a dedicated server (a plain infocenter) and have each client workbench access the content remotely. Local content is also allowed and will be merged with the remote content. The goal is that the help system will behave as though it were all local, as far as the user is concerned.

Scope

Remote help applies to all forms of help: online help (the documents themselves, be it html or anything else), table of contents, context help, help search, and keyword index. Dynamic content (e.g. filters) will still work on remote content, and will use information from the local machine, not the remote server. For example, if you have a paragraph to be displayed only on linux, and you're running the workbench on windows pointing to a remote help server running on linux, the paragraph will not be shown on the client machine. Since bookmarks are user-defined and per-user, remote help does not apply and they will continue to be stored locally.

Help should only show remote content pertaining to what the user has installed on the client side. That is, if the remote help server is used to serve help for several products, help should filter out all content except for the product(s) the user has installed.

To achieve this, all tocs should specify their enablement based on the presence of the specific bundle or bundles they are documenting. The same applies to index content. For example:

<toc label="User Guide">
   <topic label="Getting started">
      <link toc="topics_GettingStarted.xml" />
   </topic>
   ...
   <enablement>
      <test property="org.eclipse.core.runtime.isBundleInstalled" args="my.bundle.name"/>
   </enablement>
</toc>

Precedence

If local content for a particular item is available, it will be used and remote help will not be consulted. For example, if you attempt to open a specific document, or open context help on a particular UI, and that document or context help definition is available locally, it will be used and any remote content for that item will be ignored. This is for performance.

Configuration

Help needs to know the address (host name/IP) and port of the remote server. There will be two ways to configure which remote server to retrieve help from:

• Global default: Products can be preconfigured to point to a default server and port. This way the workbench will automatically retrieve remote content upon startup for the first time.
• User preference: A preference page will be available for the user allowing them to explicitly set or override the host address and port for the remote help server.

In any case, if no port is specified, a default of 80 will be assumed.

Related enhancements

This is a feature of the reference help implementation provided by eclipse. There will be no API specifically for this in the help platform (org.eclipse.help) for help system implementations in general. The API (for specifying which server to use) will be at the org.eclipse.help.base level instead. If another implementation of help wishes to do the same, it will be up to them to implement this support. However the platform API needs to be made more general in order to support this in the reference implementation. Here are the known required enhancements:

TOC provider support

Previously the only way to contribute to the TOC (table of contents) was to supply an XML file in a locally installed plug-in. Since this feature involves having books contributed from a remote source, this is not enough. To facilitate this, a general-purpose mechanism was be introduced to make contributions to the TOC. The API will allow any plug-in to contribute an AbstractTocProvider via an extension point, which will be queried at runtime to supply TOC information. One such provider will be contributed by the reference implementation, so authoring and packaging remote help with this implementation will not require the addition of any extensions.

An AbstractTocProvider is responsible for providing zero or more ITocContributions:

/**
 * An AbstractTocProvider is a mechanism to provide arbitrary
 * content to the table of contents (TOC). AbstractTocProviders
 * must be registered via the org.eclipse.help.toc extension point.
 * 
 * @since 3.3
 */
public abstract class AbstractTocProvider {

	/**
	 * Returns all toc contributions for this provider. Providers
	 * are free to provide any number of contributions (zero or more).
	 * 
	 * @param locale the locale for which to get contributions
	 * @return all the contributions for this provider
	 */
	public abstract ITocContribution[] getTocContributions(String locale);
	
	/**
	 * Notifies the platform that the content managed by this provider may
	 * have changed since the last time getTocContributions()
	 * was called, and needs to be updated.
	 */
	protected void contentChanged() {
	   ...
	}
}

/**
 * Represents either a complete or partial table of contents, as well as
 * its metadata.
 * 
 * @since 3.3
 */
public interface ITocContribution {

	/**
	 * Returns the contribution's category id. Contributions with the same
	 * category id will be grouped together.
	 * 
	 * @return the contribution's category id.
	 */
	public String getCategoryId();
	
	/**
	 * Returns the symbolic name of the bundle that made this contribution,
	 * e.g. "org.eclipse.help"
	 * 
	 * @return the contributor id, e.g. "org.eclipse.help"
	 */
	public String getContributorId();
	
	/**
	 * Returns the hrefs for any additional documents that are not in this TOC
	 * but are associated with it, and should be indexed for searching.
	 * 
	 * @return any extra documents associated with the TOC
	 */
	public String[] getExtraDocuments();
	
	/**
	 * Returns a unique identifier for this contribution.
	 * 
	 * @return the contribution's unique identifier
	 */
	public String getId();
	
	/**
	 * Returns the locale for this contribution.
	 * 
	 * @return the contribution's locale
	 */
	public String getLocale();
	
	/**
	 * Returns the table of contents data for this contribution.
	 * 
	 * @return the toc data for this contribution
	 */
	public IToc getToc();
	
	/**
	 * Returns whether or not this is a top-level contribution (a book).
	 * 
	 * @return whether the contribution is top-level book
	 */
	public boolean isPrimary();
}

The getId() method is needed here for ordering books in the TOC. In order to have a way to specify an order of books, whether it be relative or a complete list, there must be a way to refer to a specific book.

The provider must be registered as an extension using the org.eclipse.help.toc extension point, using the tocProvider element, as shown below:

<extension
      point="org.eclipse.help.toc">
   <tocProvider
         class="org.example.MyTocProvider"/>
</extension>

Keyword index provider support

Keyword index had the same limitation as TOC - the only way to contribute to it was to provide an XML file in a local plug-in. The solution is be the same as with TOC, except for keyword content. For example, it will be an AbstractIndexProvider which supplies IIndexContributions, and will be registered via the org.eclipse.help.index extension point using the indexProvider.

Limitations

• A network connection is required.
• The performance/responsiveness of help will be limited by the network connection.
• Progress monitoring during indexing may not be as accurate due to the distributed nature.
• Infocenter must be 3.3 or later.

Future considerations

In the future it may be desirable to allow multiple remote servers instead of just one. This will be taken into consideration during implementation.