Table of Contents (TOC)

org.eclipse.help.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 performance of the first search attempt. Only one index per plug-in can be registered - multiple index elements will result in undefined behaviour.

<!ELEMENT extension (toc* , index?)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT toc EMPTY>

<!ATTLIST toc

file     CDATA #REQUIRED

primary  (true | false) "false"

extradir CDATA #IMPLIED>


<!ELEMENT index EMPTY>

<!ATTLIST index

path CDATA #REQUIRED>

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



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

(in file plugin.xml)

 

<extension point=

"org.eclipse.help.toc"

>

<toc file=

"maindocs.html"

primary=

"true"

/>

<toc file=

"task.xml"

/>

<toc file=

"sample.xml"

extradir=

"samples"

/>

<index path=

"index/"

/>

</extension>

(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"/>
  </topic>
  <link toc="task.xml" />
  <topic label="Testing a Project" href="tasks/taskn.html"/>
 </topic>
 <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"/>
  </topic>
  <anchor id="samples" />
 </topic>
</toc>


(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"/>
 </topic>
</toc>


(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"/>
 </topic>
</toc>

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

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.

The default implementation of the help system UI supplied with the Eclipse platform fully supports the toc extension point.