描述:用于为个别插件注册联机帮助添加项。
向帮助文件进行添加的每个插件一般应执行下列操作:
<!ELEMENT toc EMPTY>
<!ATTLIST toc file CDATA #REQUIRED>
<!ATTLIST toc primary (true | false) "false">
<!ATTLIST toc extradir CDATA #IMPLIED>
<!ELEMENT toc (topic | anchor | link)*
>
<!ATTLIST toc link_to CDATA #IMPLIED >
<!ATTLIST toc label CDATA #REQUIRED >
<!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 >
通常,需要提供联机帮助的插件将定义它自己的 TOC 文件。最后,将帮助系统配置为象某些操作那样启动,而 TOC 文件的路径可用来执行此操作。
主题元素
所有帮助主题元素都是作为 toc 容器元素的一部分来添加的。它们可具有分层结构,或可列示为平面列表。
主题元素是“目录”结构的骨干部分。主题元素有两种主要用途:
1. 提供与文档文件(通常是 HTML 文件)的链接。
2. 充当同一清单或另一清单中的其它 toc 的容器。
1. 作为链接的主题
主题最简单的用法就是用作文档文件的链接。
<topic label="Some concept file" href="concepts/some_file.html"/>
href 属性是与清单文件所属的插件相关的。如果您需要访问另一插件中的文件,可使用以下的语法:
<topic label="topic in another plug-in" href="../other.plugin.id/concepts/some_other_file.html" />
2. 作为容器的主题
主题的另一个最常用的用途是将它用作其它 toc 的容器。容器主题本身也可以总是指某个特定文件。
<topic label="Integrated Development Environment" href="concepts/ciover.htm"
>
<topic label="Starting the IDE" href="concepts/blah.htm"
/>
...
</topic>
链接元素
链接元素允许链接在另一个 toc 文件中定义的“目录”。在 toc 属性中指定的 toc 文件的所有主题将如同直接在链接元素中定义的那样出现在目录中。要使 api.xml 文件中包括 toc,您可以编写
<topic label="References" >
...
<link toc="api.xml" />
...
</topic>
锚点元素
锚点元素定义一个点,该点允许将其它 toc 文件与此导航链接并扩展它而不必使用链接元素,并从此处引用 其它 toc 文件。要允许在“ZZZ”文档后面插入具有多个主题的“目录”,应按如下所示定义锚点:
...
<topic label="zzz" href="zzz.html" />
<anchor id="moreapi" />
...
toc 元素
toc 元素是一个“目录”,它对主题和在此文件中定义的其它元素进行分组。向用户显示标号时,标号标识用户的目录。可选的 link_to 属性将 toc 从此文件链接到在导航层次结构上处于更高位置的另一个 toc 文件中。link_to 属性的值必须在另一 toc 文件中指定锚点。要将 toc 从 myapi.xml 链接至在另一个插件中定义的 api.xml 文件,将使用以下语法
<toc link_to="../anotherPlugin/api.xml#moreapi" label="My Tool
API"/>
...
<toc />
其中,# 字符将 toc 文件名与锚点标识符分开。
示例:
以下是使用 toc 扩展点的一个示例。假设以下示例是关于其标识名为 "org.eclipse.help.examples.ex1" 的插件的。(将示例作为一个通用样本,应注意,从下列所有 toc 文件中产生的同一文档层次结构还可用其它 toc 文件的不同组合来创建。)
(在 plugin.xml 文件中)
<extension point="org.eclipse.help.toc">
<toc file="maindocs.xml" primary="true" />
<toc file="task.xml" />
<toc file="sample.xml" extradir="samples" />
</extension>
(在 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>
(在 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>
(在 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>
以下是“Eclipse 工作台”中的结果文档层次结构
假定以“samples”开头的路径中存在多个文档,则这些文档不会显示在导航树中,但是可以使用搜索来访问。这是由于 plugin.xml 文件内的 <toc file="sample.xml" extradir="samples" /> 元素中存在“extradir”属性。例如,搜索“创建 Java 项目”可能会返回文档“创建 Java 项目的其它方法”,路径为 samples/sample2.html。
可通过创建具有已翻译版本的文档的 doc.zip 文件并将
doc.zip 文件放置在
nl/<language>/<country> 或 nl/<language> 目录中来使
doc.zip 中包含的文档本地化。在缺省设置为插件目录之前,帮助系统将查找这些目录下面的文件。
API 信息:使用此扩展点不需要任何代码。所需要的只是提供在 plugin.xml 文件中提到的适当清单文件。
所提供的实现:随 Eclipse 平台一起提供的帮助系统 UI 的缺省实现完全支持 toc 扩展点。