ONLINE HELP CHANGES

(First draft: Nov 13, 2001)

Early adopters of the eclipse help system version 1.0 have provided considerable feedback on the contribution mechanism for online help and there seems to be a consensus on the following as direction for further work: As such, the proposed changes are meant to simplify the help contributions mechanism, to allow for simple migration from R1.0 and not to introduce radically new concepts.

CONCEPTS

This section describes in very general terms the basics of the eclipse online documentation.

Eclipse-based products are made up of a number of plugins, each plugin contributing some function, and/or documentation. Documentation consists of two parts: the actual html help files and the corresponding table of contents (TOC). Documentation is, thus, distributed across plugins and comes together as an integrated documentation library at runtime. Tables of contents across all plugins are usually integrated by linking them to one another to form larger, more product centric view of the documentation. Most often a plugin defines a primary table of contents to which other plugins integrate their own table of contents contributions.
Tables of contents are really the unit of work, the building blocks of the documentation navigation. Tables of contents can link any other table of contents, and can be linked to any other table of contents that allows linking. After all the table of contents linking has been performed some tables of contents are said to be integrated and some not. Those that are not integrated are discarded and the library only contains the integrated tables of contents.

A table of contents is considered to be integrated if:
A plugin indicates its desired integration of a table of contents by tagging it as "primary" or not:
 Clearly, a primary table of contents can link to other (primary or not) tables of contents and can link other tables of contents to it. So, tagging a TOC primary or not only declares an integration intention, not the final outcome.

Finally, the set of tables of contents forming the documentation library is the set of all primary tables of contents that are not linked to another integrated table of contents. In general it is the set of all the primary tables of contents, but sometimes, when some primary table of contents is linked (directly or indirectly) into another primary table of contents then it is no longer presented as a top level TOC.

CHANGES

At a glance, here are the main changes:

The above suggests that migrating from version 1.0 should be straightforward, as the html help content (doc.zip) does not change, the topics.xml files are also almost identical and the modularization of documentation across plugins can stay the same. There will be a separate document describing migration steps, tips, and examples.

 
 

SCENARIOS

It helps to look at a few scenarios to understand how help contributions work. 

Scenario 1: very basic

The simplest case is when there is exactly one documentation plugin that consists of a doc.zip and the associated table of contents. The table of contents should be declared primary, as it makes sense to be standalone.

Here are the files:

plugin.xml 
<plugin id="MyPlugin">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml"  primary="true" />
</extension>
</plugin>
toc.xml 

<toc label="My Plugin Documentation">
<topic label="Compiling"  href="docs/compile.html">
<topic label="Java files" href="docs/java.html"/.>
<topic label="C++ files" href="docs/cpp.html"/>
</topic>
</toc>
The doc.zip file contains docs/compile.html, docs/java.html and docs/cpp.html (and any images used).

The Help library consists of the following navigation structure
        Compiling

                Java files

                C++ files

Scenario 2: basic

There are a few documentation plugins, none being aware of the others existence (i.e. TOC's are standalone). In this case, each table of contents  is tagged as a "primary" and the library consists of the collection of  all the defined TOC's.

Scenario 3: top-down integration

A common scenario is to build an eclipse-based product and have the navigation distributed in a number of plugins, with a master plugin providing the navigation skeleton. The master table of contents file  would then include the other tables of contents at certain point and is marked as primary.

The basic markup is to add an <link toc="../another_pluginID/another_toc_section.xml"> at the desired point in a table of contents. This basically links (integrates) the "another_toc.xml" navigation. The effect of this is that the help system now has just one big table of contents that is made up of smaller ones.

Here are the files:

plugin.xml in PluginA and PluginB 
<plugin id="PluginA">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml"  type="toc"/>
</extension>
</plugin>
<plugin id="PluginB">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml"/>
</extension>
</plugin>
toc.xml in PluginA and PluginB 


<toc label="PluginA Documentation">
<topic label="Compiling"  href="docs/compile.html">
<topic label="Java files" href="docs/java.html"/>
<link   toc="../PluginB/toc.xml"/>

<topic label="C++ files" href="docs/cpp.html"/>

</topic>
</topic>
<toc label="PluginB  Documentation">
<topic label="JavaScript"  href="js.html">
<topic label="Netscape" href="ns.html"/>
<topic label="IE" href="ie.html"/>
</topic>
</topic>
The doc.zip file in PluginA contains docs/compile.html, docs/java.html and docs/cpp.html (and any images used). The doc.zip file in PluginB contais js.html, ns.html and ie.html (and any images used).

Help should display the following table of contents
        Compiling

              Java files

JavaScript
Netscape

IE

              C++ files

Scenario 4: basic bottom-up integration

A typical scenario for a third party ISV is to provide tools (plugins) and attempt to integrate their documentation with that of the target product (like IBM's Websphere Studio). For that to happen, the ISV toc file must link itself to the target toc, and the target doc must expose an anchor for linking.

The markup for this kind of linking is simply specifying the link_to attribute on the <toc> element inside the table of contents file:

<toc label="PluginA docs"  link_to="../PluginB/toc.xml#anchor_id" >

The net effect should be the same as if the target navigation file <link>-ed the ISV navigation component at the specified anchor.

Here are the files:

plugin.xml in PluginA and PluginB 
<plugin id="PluginA">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml"/>
</extension>
</plugin>
<plugin id="PluginB">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml"/>
</extension>
</plugin>
toc.xml in PluginA and PluginB 


<toc label=" PluginA Documentation">
<topic label="Compiling"  href="docs/compile.html">
<topic label="Java files" href="docs/java.html"/>
<anchor id="other"/>

<topic label="C++ files" href="docs/cpp.html"/>

</topic>
</topic>
<toc label=" PluginB  Documentation" link_to="../PluginA/toc.xml#other" >
<topic label="JavaScript"  href="js.html">
<topic label="Netscape" href="ns.html"/>
<topic label="IE" href="ie.html"/>
</topic>
</topic>
The following table of contents is built: 

        Compiling

              Java files

JavaScript
Netscape

IE

C++ files


REFERENCE

Plugin.xml

A plugin can contribute one or more tables of contents. Tables of contents files contain navigation info for the help content, i.e.a hierarchical structure of  topic nodes that point to the actual html help documents. By default tables of contents are meant to be integrated to other tables of contents. Some are considered standalone or master tables of contents, and marked as primary.  Each TOC contributed by a plugin must be defined in the plugin.xml file under the org.eclipse.help.toc extension point. A plugin can configure one or more toc extension points, and each toc extension point can define one or more tables of contents. Multiple TOCs are contributed when needed to support different navigation views, or to provide reusable table of contents components. The same TOC should not be defined multiple times. 
The DTD for the org.eclipse.help.toc extension point content is as follows:

<!ELEMENT extension  (toc)* >
<!ATTLIST  extension point  CDATA "org.eclipse.help.toc"  #FIXED>
<!--
Each toc extension point can define any number of toc files.
-->

<!ELEMENT   toc EMPTY>
<!ATTLIST    toc file CDATA   #REQUIRED>
<!ATTLIST    toc primary (true | false) "false" >

<!--
Each toc file definition specifies the toc file by its relative path (href)  to the plugin and whether the plugin contributes it as a section or a table of contents or as a standalone or master table of contents.
-->
 
 

Example:

 

<extension point="org.eclipse.help.toc">
<!-- this defines a standalone table of contents -->
<toc file="toc.xml"  primary="true"/>
</extension>

<extension point=" org.eclipse.help.toc">
<!-- this defines two sections -->
<toc file="tocWSAD.xml"/

<toc  href="referencesWSAD.xml" />
</extension>

Toc.xml

The new table of contents files combine the 1.0 topics files with the 1.0 action files in a cleaner document/web centric structure.
In its most basic form, tables of contents  are just hierarchical structures of topics. A topic is really a "pointer" to the actual help file. Stepping up in complexity,  a table of contents can link other tables of contents when desired, creating larger tables of contents. Conversely, a table of contents can link to another table of contents, forming larger navigation tables of contents in a bottom up approach. Linking to another table of contents file is done by specifying an anchor in the target table of contents file.
Since topics behave like pointers to a help file, the same html help file can be reused in many places, by defining the appropriate topic. Reuse can also be done in groups of topics, with the table of contents file acting as a reusable component.The same table of contents file can be linked  many times. Two branches of the navigation tree will look identical from the reused table of contents and down.

The DTD for the table of contents file follows:

<!ELEMENT  toc  (topic | anchor |  link)* >
<!ATTLIST  toc  link_to  CDATA  #IMPLIED>
<!ATTLIST  toc  label    CDATA  #REQUIRED>
<!--
A toc element is the root of the tree of topics defined in the table of contents file. It can optionally attach to another topics file by providing its "link_to" attribute. The value of this attribute should be an href to an anchor defined in this plugin or in another plugin.
 Href's to anchors in  a table of contents  in other plugins are specified as  ../other_plugin_id/path_to_toc_file.xml#anchor_id
Each toc element must define a label to be used in its presentation. The label is only shown when the table of contents  is primary and not integrated into another table of contents (i.e. it is part of the library of the tables of contents for the product). When linked, the toc element gets bypassed, and its topics are directly connected to topics at the link point .
A TOC  file consist of any number of  (nested) topics, anchor points or links of other TOC files.
-->

<!ELEMENT topic  (topic | anchor | link )* >
<!ATTLIST  topic  label  CDATA  #REQUIRED>
<!ATTLIST  topic  href    CDATA  #IMPLIED>
<!--
Each topic is a node in a table of contents tree and can contain topics, anchor points or can include the topics form other tables of contents.
For presentaton purposes, each topic must have a label.
Most topics have a corresponding help content, identified by the href value. In general the href is a relative path to a file in the same plugin (in doc.zip or a regular file) or can point to content in another plugin using the ../another_plugin_id/path_to_content_file.html form.
Topics with no href are there for grouping  other topics, for cleaner tree presentation.
-->

<!ELEMENT  anchor  EMPTY>
<!ATTLIST  anchor  id  ID    #REQUIRED>
<!--
An anchor  is really an insertion point for other tables of contents to link into the structure defined in the current file. If  multiple topics files  linked to the same topic, they will be linked in the processing order. In other words, the order is not guaranteed. Multiple, adjacent anchors may be used to differentiate among topics that should be linked before or after the others.
-->

<!ELEMENT  link  EMPTY>
<!ATTLIST  link  toc CDATA    #REQUIRED>
<!--
A link is used to link the topics from another table of content s.
-->