Help Placeholders

A help placeholder is used when documentation is not installed at the same time as the corresponding software bundles. A placeholder contains a reference to a help page which describes how to install help bundles.

As an example suppose that for reasons of size the documentation bundle org.eclipse.myfeature.doc was a separate download from org.eclipse.myfeature. Users who installed only org.eclipse.myfeature without the documentation would not see the help content for myfeature and a help search would not search org.eclipse.myfeature.doc. If the developers of myfeature add a toc placeholder the user will be made aware that documentation is available and be able to get instructions for installing it.

A help placeholder is defined using the placeholder element of the extension point org.eclipse.help.toc. The easiest way to manage placeholders is to create bundles which contain one or more help placeholder extensions and no code. The code bundles will have a dependency to these help placeholder bundles.

As an example here is how to setup a placeholder for the ( nonexistent ) help bundle org.eclipse.myfeature.doc A bundle org.eclipse.myfeature.doc.placeholder is created which contains the extension point below and no code.

  <extension
         point="org.eclipse.help.toc"*gt;
      <placeholder
            placeholderPage="http://www.eclipse.org/installingmyfeaturedocs.html"
            plugin="org.eclipse.myfeature.doc"*gt;
      </placeholder*gt;
   </extension*gt;

A dependency is added from the Java bundle org.eclipse.myfeature to org.eclipse.myfeature.doc.placeholder. If the help system is launched with org.eclipse.myfeature installed and org.eclipse.myfeature.doc not installed the home page will be replaced with a page informing of the missing documentation bundle. In this example clicking on the link "org.eclipse.myfeature.doc" will open the page http://www.eclipse.org/installingmyfeaturedocs.html.

help showing placeholder page