| <?xml version='1.0' encoding='UTF-8'?> |
| <!-- Schema file written by PDE --> |
| <schema targetNamespace="org.eclipse.help"> |
| <annotation> |
| <appInfo> |
| <meta.schema plugin="org.eclipse.help" id="toc" name="Table of Contents (TOC)"/> |
| </appInfo> |
| <documentation> |
| For registering an online help contribution for an individual plug-in. |
| |
| <p>Each plug-in that contributes help files should in general do the following: |
| <ul> |
| <ul> |
| <li> |
| author the html files, zip html files into doc.zip, and store the zip file |
| in the plug-in directory.</li> |
| |
| <li> |
| create TOC files that describe Table of Contents for the help and the necessary |
| topic interleaving. See the syntax below.</li> |
| |
| <li> |
| the plugin.xml file should extend the <tt>org.eclipse.help.toc</tt> extension |
| point and specify TOC file(s).</li> |
| </ul> |
| </ul> |
| </documentation> |
| </annotation> |
| |
| <element name="extension"> |
| <complexType> |
| <sequence> |
| <element ref="toc" minOccurs="0" maxOccurs="unbounded"/> |
| </sequence> |
| <attribute name="point" type="string" use="required"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="id" type="string"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="name" type="string"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| </complexType> |
| </element> |
| |
| <element name="toc"> |
| <complexType> |
| <attribute name="file" type="string" use="required"> |
| <annotation> |
| <documentation> |
| the name of the TOC file which contains the table of contents or section for this plug-in's online help. |
| <p> |
| <i><b>Configuration Markup for toc file:</b></i> |
| <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT toc (topic | anchor | link)* ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc link_to CDATA #IMPLIED ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc label CDATA #REQUIRED ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST toc topic CDATA #IMPLIED ></tt> |
| <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT topic (topic | anchor | link )* |
| ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic label CDATA #REQUIRED ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST topic href CDATA #IMPLIED ></tt> |
| <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT anchor EMPTY ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST anchor id ID&nbsp; #REQUIRED ></tt> |
| <p><tt>&nbsp;&nbsp;&nbsp; &lt;!ELEMENT link EMPTY ></tt> |
| <br><tt>&nbsp;&nbsp;&nbsp; &lt;!ATTLIST link toc CDATA #REQUIRED ></tt> |
| <p>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. |
| <p><b>The topic element</b> |
| <p>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. |
| <p>The topic element is the workhorse of structure of Table of Contents. |
| There are two typical uses for the topic element: |
| <p>1.&nbsp; To provide a link to a documentation file - usually an HTML |
| file. |
| <br>2.&nbsp; To act as a container for other toc, either in the same manifest |
| or another. |
| <p><b><i>1.&nbsp; Topics as links</i></b> |
| <br>The simplest use of a topic is as a link to a documentation file. |
| <p><tt>&lt;topic label="Some concept file" href="concepts/some_file.html" |
| /></tt> |
| <p>The href attribute is relative to the plug-in that the manifest file |
| belongs to.&nbsp; If you need to access a file in another plug-in, you |
| can use the syntax |
| <p><tt>&lt;topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" |
| /></tt> |
| <p><b><i>2.&nbsp; Topics as containers</i></b> |
| <br>The next most common use of a topic is to use it as a container for |
| other toc.&nbsp; The container topic itself can always refer to a particular |
| file as well. |
| <p><tt>&lt;topic label="Integrated Development Environment" href="concepts/ciover.htm" |
| ></tt> |
| <br><tt>&nbsp; &lt;topic label="Starting the IDE" href="concepts/blah.htm" |
| /></tt> |
| <br><tt>&nbsp; ...</tt> |
| <br><tt>&lt;/topic></tt> |
| <p><b>The link element</b> |
| <p>The link element allows to link Table of Contents defined in another |
| toc file.&nbsp; 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.&nbsp; To include toc from api.xml file you could |
| write |
| <p><tt>&lt;topic label="References" ></tt> |
| <br><tt>&nbsp; ...</tt> |
| <br><tt>&nbsp; &lt;link toc="api.xml" /></tt> |
| <br><tt>&nbsp; ...</tt> |
| <br><tt>&lt;/topic></tt> |
| <p><b>The anchor element</b> |
| <p>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.&nbsp; To allow inserting Table |
| of Contents with more topics after the "ZZZ" document you would define |
| an anchor as follows: |
| <p><tt>...</tt> |
| <br><tt>&lt;topic label="zzz" href="zzz.html" /></tt> |
| <br><tt>&lt;anchor id="moreapi" /></tt> |
| <br><tt>...</tt> |
| <p><b>The toc element</b> |
| <p>The toc element is a Table of Contents that groups topics and other |
| elements defined in this file.&nbsp; The label identifies the table of |
| contents to the user, when it is displayed to the user.&nbsp; The optional topic |
| attribute is the path to a topic file describing the TOC.&nbsp; The optional |
| link_to attribute allows for linking toc from this file into another toc |
| file being higher in the navigation hierarchy.&nbsp; 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 |
| <p><tt>&lt;toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool |
| API"/></tt> |
| <br><tt>...</tt> |
| <br><tt>&lt;toc /></tt> |
| <p>where # character separates toc file name from the anchor identifier. |
| </p> |
| <br> |
| </documentation> |
| <appInfo> |
| <meta.attribute kind="resource"/> |
| </appInfo> |
| </annotation> |
| </attribute> |
| <attribute name="primary" type="boolean" use="default" value="false"> |
| <annotation> |
| <documentation> |
| 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. |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="extradir" type="string"> |
| <annotation> |
| <documentation> |
| specifies relative directory name of 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 <samp>topic</samp> elements in the TOC file do not refer to these documents. |
| </documentation> |
| </annotation> |
| </attribute> |
| </complexType> |
| </element> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="examples"/> |
| </appInfo> |
| <documentation> |
| The following is an example of using the <samp>toc</samp> extension point. |
| |
| <p>(in file <tt>plugin.xml</tt>) |
| <pre> |
| <extension point="org.eclipse.help.toc"> |
| <toc file="maindocs.html" primary="true"/> |
| <toc file="task.xml"/> |
| <toc file="sample.xml" extradir="samples"/> |
| </extension> |
| </pre> |
| </p> |
| |
| <p>(in file <tt>maindocs.xml</tt>) |
| <blockquote><tt>&lt;toc label="Help System Example"></tt> |
| <br><tt>&nbsp;&lt;topic label="Introduction" href="intro.html"/></tt> |
| <br><tt>&nbsp;&lt;topic label="Tasks"></tt> |
| <br><tt>&nbsp; &lt;topic label="Creating a Project" href="tasks/task1.html"></tt> |
| <br><tt>&nbsp;&nbsp; &lt;topic label="Creating a Web Project" href="tasks/task11.html"/></tt> |
| <br><tt>&nbsp;&nbsp; &lt;topic label="Creating a Java Project" href="tasks/task12.html"/></tt> |
| <br><tt>&nbsp; &lt;/topic></tt> |
| <br><tt>&nbsp; &lt;link toc="task.xml" /></tt> |
| <br><tt>&nbsp; &lt;topic label="Testing a Project" href="tasks/taskn.html"/></tt> |
| <br><tt>&nbsp;&lt;/topic></tt> |
| <br><tt>&nbsp;&lt;topic label="Samples"></tt> |
| <br><tt>&nbsp; &lt;topic label="Creating Java Project" href="samples/sample1.html"></tt> |
| <br><tt>&nbsp;&nbsp; &lt;topic label="Launch a Wizard" href="samples/sample11.html"/></tt> |
| <br><tt>&nbsp;&nbsp; &lt;topic label="Set Options" href="samples/sample12.html"/></tt> |
| <br><tt>&nbsp;&nbsp; &lt;topic label="Finish Creating Project" href="samples/sample13.html"/></tt> |
| <br><tt>&nbsp; &lt;/topic></tt> |
| <br><tt>&nbsp; &lt;anchor id="samples" /></tt> |
| <br><tt>&nbsp;&lt;/topic></tt> |
| <br><tt>&lt;/toc></tt></blockquote> |
| |
| <p><br>(in file <tt>tasks.xml</tt>) |
| <blockquote><tt>&lt;toc label="Building a Project"></tt> |
| <br><tt>&nbsp;&lt;topic label="Building a Project" href="build/building.html"></tt> |
| <br><tt>&nbsp; &lt;topic label="Building a Web Project" href="build/web.html"/></tt> |
| <br><tt>&nbsp; &lt;topic label="Building a Java Project" href="build/java.html"/></tt> |
| <br><tt>&nbsp;&lt;/topic></tt> |
| <br><tt>&lt;/toc></tt></blockquote> |
| |
| <p><br>(in file <tt>samples.xml</tt>) |
| <blockquote><tt>&lt;toc link_to="maindocs.xml#samples" label="Using The |
| Compile Tool"></tt> |
| <br><tt>&nbsp;&lt;topic label="The Compile Tool Sample" href="compilesample/example.html"></tt> |
| <br><tt>&nbsp; &lt;topic label="Step 1" href="compilesample/step1.html"/></tt> |
| <br><tt>&nbsp; &lt;topic label="Step 2" href="compilesample/step2.html"/></tt> |
| <br><tt>&nbsp; &lt;topic label="Step 3" href="compilesample/step3.html"/></tt> |
| <br><tt>&nbsp; &lt;topic label="Step 4" href="compilesample/step4.html"/></tt> |
| <br><tt>&nbsp;&lt;/topic></tt> |
| <br><tt>&lt;/toc></tt></blockquote> |
| |
| |
| <p>Assuming more documents exists with the path starting with "samples", |
| they will not be displayed in the navigation tree, but be accessible using |
| search.&nbsp; It is due to the presence of "extradir" attribute in the |
| element <tt>&lt;toc file="sample.xml" extradir="samples" /> </tt>inside<tt> |
| plugin.xml </tt>file. For example searching for "Creating Java Project" |
| could return a document "Other Ways of Creating Java Project", which path |
| is <tt>samples/sample2.html.</tt> |
| |
| <p> |
| <b><em>Internationalization</em></b> |
| The TOC XML files can be translated and the resulting copy (with translated |
| labels) should be placed in nl/&lt;language>/&lt;country> or nl/&lt;language> |
| directory.&nbsp; The &lt;language> and &lt;country> stand for two letter |
| language and country codes as used in locale codes.&nbsp; For example, |
| Traditional Chinese translations should be placed in the nl/zh/TW directory.&nbsp; |
| The nl/&lt;language>/&lt;country> directory has a higher priority than |
| nl/&lt;language>.&nbsp; Only if no file is found in the nl/&lt;language>/&lt;country>, |
| the file residing in nl/&lt;language> will be used.&nbsp; The the root |
| directory of a plugin will be searched last. |
| <p>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 |
| <br>nl/&lt;language>/&lt;country> or nl/&lt;language> directory. The help |
| system will look for the files under this directories before defaulting |
| to plugin directory. |
| <br>&nbsp; |
| </p> |
| </documentation> |
| </annotation> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="apiInfo"/> |
| </appInfo> |
| <documentation> |
| 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. |
| </documentation> |
| </annotation> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="implementation"/> |
| </appInfo> |
| <documentation> |
| The default implementation of the help system UI supplied with the Eclipse platform fully supports the <samp>toc</samp> extension point. |
| </documentation> |
| </annotation> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="copyright"/> |
| </appInfo> |
| <documentation> |
| Copyright (c) 2000, 2003 IBM Corporation and others.<br> |
| All rights reserved. This program and the accompanying materials are made |
| available under the terms of the Common Public License v1.0 which accompanies |
| this distribution, and is available at <a href="http://www.eclipse.org/legal/cpl-v10.html">http://www.eclipse.org/legal/cpl-v10.html</a> |
| </documentation> |
| </annotation> |
| |
| </schema> |