Table of Contents (TOC)

Identifier:
org.eclipse.help.toc

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:

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

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED

>


<!ELEMENT toc EMPTY>

<!ATTLIST toc

file     CDATA #REQUIRED

primary  (true | false) "false"

extradir CDATA #IMPLIED

category CDATA #IMPLIED

>

a toc contribution made by supplying an XML file



<!ELEMENT tocProvider EMPTY>

<!ATTLIST tocProvider

class CDATA #REQUIRED

>

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



<!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.



<!ELEMENT tocIcon EMPTY>

<!ATTLIST tocIcon

id         CDATA #REQUIRED

openIcon   CDATA #REQUIRED

closedIcon CDATA #IMPLIED

leafIcon   CDATA #IMPLIED

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



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

(in file plugin.xml)


 <extension point="org.eclipse.help.toc">
  <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/"/>
 </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.
 

API Information:
An implementation of org.eclipse.help.AbstractTocProvider 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.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html