Table of Contents (TOC)

Identifier:

Description:

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

• create TOC files that describe the table of contents for the help and the necessary topic interleaving. See the syntax below.
• the plugin.xml file should extend the org.eclipse.help.toc extension point and specify TOC file(s).

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

• file - the name of the TOC file which contains the table of contents or section for this plug-in's online help.

  Configuration Markup for toc file:

      <!ELEMENT toc (topic | anchor | link)* >
      <!ATTLIST toc link_to CDATA #IMPLIED >
      <!ATTLIST toc label CDATA #REQUIRED >
      <!ATTLIST toc topic CDATA #IMPLIED >
      <!ATTLIST toc sort CDATA #IMPLIED >
      <!ATTLIST toc icon CDATA #IMPLIED >

      <!ELEMENT topic (topic | anchor | link )* >
      <!ATTLIST topic label CDATA #REQUIRED >
      <!ATTLIST topic href CDATA #IMPLIED >
      <!ATTLIST topic sort CDATA #IMPLIED >
      <!ATTLIST topic icon CDATA #IMPLIED >

      <!ELEMENT anchor EMPTY >
      <!ATTLIST anchor id ID  #REQUIRED >

      <!ELEMENT link EMPTY >
      <!ATTLIST link toc CDATA #REQUIRED >

  In general, a plug-in that needs to provide online help will define its own TOC files. In the end, the help system is configured to be launched as some actions, and the path of the TOC file can be used to do so.

  The topic element

  All help topic element are contributed as part of the toc container element. They can have a hierarchical structure, or can be listed as a flat list.

  The topic element is the workhorse of structure of Table of Contents. There are two 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 toc, 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 toc.  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>

  If the sort attribute is true child topics will be sorted alphabetically.

  The optional icon attribute allows the use of a different icon as defined by a < tocIcon > element in an org.eclipse.help.toc extension.

  The link element

  The link element allows to link Table of Contents defined in another toc file.  All the topics from the toc file specified in the toc attribute will appear in the table of contents as if they were defined directly in place of the link element.  To include toc from api.xml file you could write

  <topic label="References" >
    ...
    <link toc="api.xml" />
    ...
  </topic>

  The anchor element

  The anchor element defines a point that will allow linking other toc files to this navigation, and extending it, without using the link element and referencing other toc files from here.  To allow inserting Table of Contents with more topics after the "ZZZ" document you would define an anchor as follows:

  ...
  <topic label="zzz" href="zzz.html" />
  <anchor id="moreapi" />
  ...

  The toc element

  The toc element is a Table of Contents that groups topics and other elements defined in this file.  The label identifies the table of contents to the user, when it is displayed to the user. 

  The optional topic attribute is the path to a topic file describing the TOC. 

  If the sort attribute is true child topics will be sorted alphabetically.

  The optional icon attribute allows the use of a different icon as defined by a < tocIcon > element in an org.eclipse.help.toc extension.

  The optional link_to attribute allows for linking toc from this file into another toc file being higher in the navigation hierarchy.  The value of the link_to attribute must specify an anchor in another toc file. To link toc from myapi.xml to api.xml file, specified in another plugin you would use the syntax

  <toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool API"/>
  ...
  <toc />

  where # character separates toc file name from the anchor identifier.

  Filters

  Filters can be used to make parts of the TOC conditional. One possible use for filters is to show a set of topics only if a specific plugin is installed.

  
  
• primary - specifies whether the TOC file is a primary table of contents and is meant to be the master table of contents, or not primary and intended to be integrated into another table of contents.
• extradir - specifies a plug-in relative path to a directory containing additional documents that are associated with the table of contents. All help documents in this directory, and all subdirectories, will be indexed and accessible through the documentation search, even if the documents are not in the table of contents. Note: the directory must be within the declaring plug-in (e.g. "../my.other.plugin/path" is invalid)
• category - specifies the category of TOCs to which this one belongs. This applies only to primary TOCs. Categories are used to group together related books. The value must be a string that uniquely identifies the category.

<!ELEMENT tocProvider EMPTY>

<!ATTLIST tocProvider

class CDATA #REQUIRED>

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

• class - the implementation class for the toc provider. This class must implement the org.eclipse.help.AbstractTocProvider interface.

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

• path - a plug-in-relative path of the prebuilt search index. The index referenced by the path must exist. Missing index will be flagged in the log file. Note that each locale must have a different index. If a plug-in contributes index directories for multiple locales, it should append the locale using standard Eclipse NLS lookup. (e.g. index/, nl/ja/JP/index/, nl/en/US/index/ etc.).

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

• id - The unique id of this icon. Typically this id will include the name of the plugin in which it is declared.
• openIcon - The path of an icon to be used for a toc or topic whose chidren have been expanded.
• closedIcon - The path of an icon to be used for a toc or topic whose chidren have been expanded. If no provided openIcon will be used.
• leafIcon - The path of an icon to be used for a toc or topic without children. If not provided openIcon will be used.
• altText - Text that will be used in the "alt" attribute for the img tag in the web presentation.

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

• plugin - The name of a help plug-in for which this is a placeholder.
• placeholderPage - The page to show when the plug-in is not installed.

Examples:

(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:

Supplied Implementation:

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 https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0