Note: The help system is still under development and can be expected to change somewhat before reaching stability. It is being made available at this stage to solicit feedback from early adopters, on the understanding that the details of the contribution mechanisms might change in breaking ways.

Contributions

Identifier: org.eclipse.help.contributions

Description: For registering an online help contribution for an individual plug-in.

Each plug-in that contributes help files should in general do the following:

Configuration Markup for the contributions extension point:

    <!ELEMENT topics EMPTY>
    <!ATTLIST topics name CDATA #REQUIRED>

    <!ELEMENT actions EMPTY>
    <!ATTLIST actions name CDATA #REQUIRED>     <!ELEMENT infoset EMPTY>
    <!ATTLIST infoset name CDATA #REQUIRED> Configuration Markup for Topics (this is what goes into the topics manifest file):

    <!ELEMENT topics (topic)* ) >
    <!ATTLIST topics id  ID #REQUIRED >

    <!ELEMENT topic (topic)* >
    <!ATTLIST topic id ID #IMPLIED >
    <!ATTLIST topic label CDATA #REQUIRED >
    <!ATTLIST topic href  CDATA #IMPLIED >

Configuration Markup for Infosets (this is what goes into the infoset manifest file):

    <!ELEMENT infoset (infoview)*  >
    <!ATTLIST infoset  id  ID  #REQUIRED >
    <!ATTLIST infoset  label  CDATA  #REQUIRED >
    <!ATTLIST infoset  href  CDATA #IMPLIED >
    <!ATTLIST infoset  standalone  (false|true) false  #IMPLIED >

    <!ELEMENT infoview EMPTY>
    <!ATTLIST infoview id ID #REQUIRED >
    <!ATTLIST infoview label CDATA #IMPLIED >

Configuration Markup for Insert Actions (this is what goes into the actions manifest file):

    <!ELEMENT actions (insert)* >
    <!ATTLIST actions infoview CDATA #REQUIRED >
    <!ATTLIST actions standalone (true | false) false #IMPLIED >

    <!ELEMENT insert (insert) >
    <!ATTLIST insert from CDATA #REQUIRED >
    <!ATTLIST insert to CDATA #REQUIRED >
    <!ATTLIST insert as (child | first-child | last-child | prev-sib | next-sib) "child" >
    <!ATTLIST insert label CDATA #IMPLIED >

In general, a plug-in that needs to provide online help will define its own topics manifests and the necessary actions manifests to wire the topics to the correct place. In the end, the help system is configured to be launched as some actions, and the id of the information set can be used to do so.

There are four types of XML elements a plug-in can use: the topic, the infoset, the actions, and the insert elements.

The topic element

With respect to topics elements, all the topics are contributed as part of the topics container element. They can have a hierarchical structure, or can be listed as a flat list. A topics manifest is viewed as a data source for further topics interleaving and organization into an integrated web, with different view perspectives.  In addition, topics can be acted upon by specifying their id's, but one can also act on a group of topics by specifying the id of the containing topics or topic element.  Later when wiring topics to views or other topics, the structure defined in the topics manifest is maintained (subject to alterations done by insert actions).

The topic element is the workhorse of the navigation structure. There are three typical uses for the topic element:

1.  To provide a link to a documentation file - usually an HTML file.
2.  To act as a container for other topics, either in the same manifest or another.
3.  To provide an insertion point for other topics, either in the same manifest or another.

1.  Topics as links
The simplest use of a topic is as a link to a documentation file.

<topic label="Some concept file" href="concepts/some_file.html" />

The href attribute is relative to the plug-in that the manifest file belongs to.  If you need to access a file in another plug-in, you can use the syntax

<topic label="topic in another plug-in" href="/other.plugin.id/concepts/some_other_file.html" />

2.  Topics as containers
The next most common use of a topic is to use it as a container for other topics.  The container topic itself can always refer to a particular file as well.

<topic label="Integrated Development Environment" href="concepts/ciover.htm" >
  <topic label="Starting the IDE" href="concepts/blah.htm" />
  ...
</topic>

3.  Topics as insertion points
Topics can be used as insertion points.  They provide a logical place for other topics to try and merge around.  To act as an insertion point, the topic must have an id attribute.
 
 

The infoset element

An information set is an entry point into a documentation web.  It can be thought of as a collection of views.

Views are intended to provide high level semantic groupings within a documentation web. They are defined using the infoview element defined within an infoset. A documentation team could use a view to produce getting started, tasks, and references sections (or other views the product team defines). The platform does not specify the actual sections, only the mechanism for defining them.

For example, there can be a "task view" defined which is a merge of all the topics from a "how to do something" perspective. Another view, a "component view", can also be defined which is a topics tree displaying all components and their documentation.

The infoview element represents a container for topics that can be "shared" across plug-ins.  It is a perspective on the entire documentation. There may be times when a number of different plug-ins contribute to the same logical documentation component.  This element ensures that during a "component view," they are correctly merged together into a coherent view.

The actions element

The actions manifest contains scripting actions to be performed on topics and views. Currently there is only one kind of action, the insert action, which is used to write topics and views together into one integrated information web, with multiple views.

The actions are structural actions (insert) and, thus, apply to a certain infoview. So, all the insert actions in a manifest build the topic hierarchy in one infoview.

The insert element

One of the most complicated parts of a componentized navigation is how to create an integrated information structure with a continuous flow of navigation.  To do this, we need a mechanism to publish insertion points, choose which insertion point we want to use, and to indicate where we want to insert topics (parent, child, before, after).

The insertion points can be topics or views.  A topic indicates its willingness to be an insertion point by providing an id. Views are required to have id's.  Only fully qualified ids are use as references. For example, the fully qualified topic id of the topic <topic id="concepts" label="concepts">  in the org.eclipse.help.examples.ex1 plug-in is org.eclipse.help.examples.ex1.concepts.

Since the insertion points are typically located in other plug-ins, and these plug-in may not be installed, one can specify an alternate insertion point. By default, if none of the choices succeed, the topic stays under its component hierarchy. The "to" attribute specifies the target insertion point. The topic specified by the "from" attribute is the topic being inserted.  Followings are some possible ways to insert a topic and they are specified using the as attribute:

Currently, a topic can only be inserted once in an infoview; it can, however, be inserted in multiple infoviews. This means, that if a parent topic, and thus, its subtree, is inserted into an infoset, none of its children can be reinserted in the same infoview. Basically, insertion creates indivisible partitions for a specific infoview.

Alternative insertion options are provided, and would be executed when previous ones could not be performed. The nested insert subelements of the insert element provide these alternatives. This can be thought of as a "fall-back" mechanism where if an insert action fails, the nested insert action will be executed. Once the first choice insertion point has been satisfied, the other alternative insertion points are ignored.
 

Examples:

The following is an example of using the contributions extension point. Assume the following is for a plug-in with id  named "org.eclipse.help.examples.ex1". (The example is intended as a general sample, and it should be noted that the same documentation hierarchy, resulting from all the following contribution files, could also be created with various combination of topics and actions files.)

(in file plugin.xml)
 

   <!-- Use the Help System contribution extension point to define Infosets, topics, -->
   <!-- and actions contribution files. For clarity, the extension point is used     -->
   <!-- twice, once to define the Infoset and it's view, and another to define the   -->
   <!-- Topics and their associated actions.                                         -->
   <extension point="org.eclipse.help.contributions">
    <infoset  name="infoset.xml"/>
   </extension>

   <extension point="org.eclipse.help.contributions">
     <topics  name="infosetTopics.xml"/>
     <actions name="infosetActions.xml"/>
   </extension>

   <!-- Configure the help contribution for this plugin -->
   <!-- This part should be in a documentation plugin -->
   <extension point="org.eclipse.help.contributions">
        <topics name="topics.xml"/>
        <actions name="topicsActions.xml" />
   </extension>
 
 

(in file infoset.xml)

<!-- Define the Infoset, and any views it has. -->
<infoset id="ex1InfosetId" label="%help_system_example">
      <infoview id="topicsView" label="%topics"/>
</infoset>


(in file infosetTopics.xml)

<!-- Now define a "container" topic that holds your general topics. This makes it -->
<!-- easier to quickly insert all these general topics under the view in the      -->
<!-- Infoset.                                                                     -->
<topics id="topLevelTopics">
  <topic id="concepts" label="%concepts"/>
  <topic id="tasks" label="%tasks"/>
  <topic id="references" label="%references"/>
  <topic id="samples" label="%samples"/>
</topics>


Define topics contained in the above general topics:

(in file topics.xml)

<topics id="topics">
 <topic id="aConceptId" label="%introduction" href="concepts/concept.html"/>
 <topic id="aTaskId" label="%creating_a_project" href="tasks/task1.html">
  <topic id="aSubTaskId1" label="%creating_a_web_project" href="tasks/task2.html"/>
  <topic id="aSubTaskId2" label="%creating_a_java_project" href="tasks/task3.html"/>
 </topic>
 <topic id="aReferenceId" label="%interfaces" href="ref/ref1.html"/>
 <topic id="aSampleId" label="%help_system_sample" href="MissingFile.html"/>
</topics>


Now define the insert actions necessary to create the documentation hierarchy :

(in file infosetActions.xml)

<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <insert from="org.eclipse.help.examples.ex1.topLevelTopics"
   to="org.eclipse.help.examples.ex1.topicsView" as="child"/>
</actions>
(in file topicsActions.xml)
<actions infoview="org.eclipse.help.examples.ex1.topicsView">
 <insert from="org.eclipse.help.examples.ex1.aConceptId"
   to="org.eclipse.help.examples.ex1.concepts" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aTaskId"
   to="org.eclipse.help.examples.ex1.tasks" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aReferenceId"
   to="org.eclipse.help.examples.ex1.references" as="child"/>

 <insert from="org.eclipse.help.examples.ex1.aSampleId"
   to="org.eclipse.help.examples.ex1.samples" as="child"/>
</actions>
 
 

Here is the resulting documentation hierarchy in the Eclipse Workbench :


 

Non-integrated components

One can expect a plug-in to sometimes be installed by itself, and in other cases it will be installed as part of a larger component or product. When is is a free floating plug-in it should be ensured that the infoset is visible. When the topics are integrated into a larger web it probably doesn't make sense for a standalone book to show up anymore. To support this non-integrated or loosely integrated documentation, a plug-in can define an infoset and associated actions and set their standalone attribute to true. This has an effect of executing the insert actions only when those topics have never been contributed anywhere else, and only display the infoset if it is not empty.  Setting standalone attributes on actions and infosets is useful when providing a "Catch all" scenario, when documentation cannot be contributed to a well-known infoset but the plug-in documentation should still appear somewhere.

Externalizing Strings

Plugin.xml files externalize their strings by replacing the string with a key (e.g. %pluginName) and creating an entry in the plugin.properties file of the form:
    pluginName = "Online Help Sample Plugin"
The contribution XML files are externalized using a similar approach. To externalize <topic id="plainTasks" label="Plain Stuff">, replace its label with a key %plainStuff . The topic will look like:
    <topic id="plainTasks" label="%plainStuff">
Create an entry in the doc.properties file containing the entry:
    plainStuff = Plain Stuff
The help system will use doc.properties when looking up strings externalized by our online help contributions.
 

API Information: No code is required to use this extension point. All that is needed is to supply the appropriate manifest files mentioned in the plugin.xml file.
 

Supplied Implementation: The optional default implementation of the help system UI supplied with the Eclipse platform fully supports the contributions extension point.

Copyright IBM Corp. 2000, 2001.  All Rights Reserved.