Curtis d'Entremont, 01/02/2007
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.
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.
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>
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.
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:
In any case, if no port is specified, a default of 80 will be assumed.
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:
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
ITocContribution
s:
/** * AnAbstractTocProvider
is a mechanism to provide arbitrary * content to the table of contents (TOC).AbstractTocProvider
s * must be registered via theorg.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 timegetTocContributions()
* 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 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
.
In the future it may be desirable to allow multiple remote servers instead of just one. This will be taken into consideration during implementation.