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 >
<!ELEMENT topic (topic | anchor | link )*
>
<!ATTLIST topic label CDATA #REQUIRED >
<!ATTLIST topic href 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>
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. 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.
