Table of Contents (TOC)


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

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

Optionally, a search index can be prebuilt and registered using index element in order to improve the performance of the first search attempt. Only one index per plug-in can be registered - multiple index elements will result in undefined behaviour.

Configuration Markup:

<!ELEMENT extension (toc | tocProvider | index | tocIcon | placeholder)+>

<!ATTLIST extension







primary  (true | false) "false"


category CDATA #IMPLIED>

a toc contribution made by supplying an XML file

<!ELEMENT tocProvider EMPTY>

<!ATTLIST tocProvider


(since 3.3) a toc contribution made by plugging in code


<!ATTLIST index


(since 3.1) an optional element that allows declaration of prebuilt search index created from documents contributed by this plug-in.


<!ATTLIST tocIcon

id         CDATA #REQUIRED




altText    CDATA #IMPLIED>

(since 3.5) an optional element that allows the icon to be specified for elements in a toc. Once a tocIcon has been declared it can be specified in a topic or toc using the "icon" attribute, for example <toc label="Sample Table of Contents" topic="html/toc.html" icon="myicon">

<!ELEMENT placeholder EMPTY>

<!ATTLIST placeholder

plugin          CDATA #IMPLIED

placeholderPage CDATA #IMPLIED>

A placeholder is used for products where the documentation is installed as an additional step. The placeholder specifies a help page which will be presented to the user if help is opened and a documentation bundle is not installed. Typically this help page would contain information about how to install the documentation. Each placeholder specifies a bundle or list of bundles and a help page which will be displayed if one or more of the bundles in the list is not installed

The following is an example of using the toc extension point.

(in file plugin.xml)

 <extension point="">
  <toc file="toc1.xml" primary="true"/>
  <toc file="toc2.xml" primary="true" category="myCategory"/>
  <toc file="task.xml"/>
  <toc file="sample.xml" extradir="samples"/>
  <index path="index/"/>

(in file maindocs.xml)

<toc label="Help System Example">
 <topic label="Introduction" href="intro.html"/>
 <topic label="Tasks">
  <topic label="Creating a Project" href="tasks/task1.html">
   <topic label="Creating a Web Project" href="tasks/task11.html"/>
   <topic label="Creating a Java Project" href="tasks/task12.html"/>
  <link toc="task.xml" />
  <topic label="Testing a Project" href="tasks/taskn.html"/>
 <topic label="Samples">
  <topic label="Creating Java Project" href="samples/sample1.html">
   <topic label="Launch a Wizard" href="samples/sample11.html"/>
   <topic label="Set Options" href="samples/sample12.html"/>
   <topic label="Finish Creating Project" href="samples/sample13.html"/>
  <anchor id="samples" />

(in file tasks.xml)

<toc label="Building a Project">
 <topic label="Building a Project" href="build/building.html">
  <topic label="Building a Web Project" href="build/web.html"/>
  <topic label="Building a Java Project" href="build/java.html"/>

(in file samples.xml)

<toc link_to="maindocs.xml#samples" label="Using The Compile Tool">
 <topic label="The Compile Tool Sample" href="compilesample/example.html">
  <topic label="Step 1" href="compilesample/step1.html"/>
  <topic label="Step 2" href="compilesample/step2.html"/>
  <topic label="Step 3" href="compilesample/step3.html"/>
  <topic label="Step 4" href="compilesample/step4.html"/>

Assuming more documents exists with the path starting with "samples", they will not be displayed in the navigation tree, but be accessible using search.  It is due to the presence of "extradir" attribute in the element <toc file="sample.xml" extradir="samples" /> inside plugin.xml file. For example searching for "Creating Java Project" could return a document "Other Ways of Creating Java Project", which path is samples/sample2.html.

Internationalization The TOC XML files can be translated and the resulting copy (with translated labels) should be placed in nl/<language>/<country> or nl/<language> directory.  The <language> and <country> stand for two letter language and country codes as used in locale codes.  For example, Traditional Chinese translations should be placed in the nl/zh/TW directory.  The nl/<language>/<country> directory has a higher priority than nl/<language>.  Only if no file is found in the nl/<language>/<country>, the file residing in nl/<language> will be used.  The the root directory of a plugin will be searched last.

The documentation contained in can be localized by creating a file with translated version of documents, and placing in
nl/<language>/<country> or nl/<language> directory. The help system will look for the files under this directories before defaulting to plugin directory.

API Information:
An implementation of must be supplied if a tocProvider is used.

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

Copyright (c) 2000, 2006 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at SPDX-License-Identifier: EPL-2.0