描述:用于为个别插件注册联机帮助添加项。
向帮助文件进行添加的每个插件一般应执行下列操作:
配置标记:
<!ELEMENT extension (toc*)>
<!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
>
toc 文件的配置标记:
<!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 >
通常,需要提供联机帮助的插件将定义它自己的 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 元素是对在此文件中定义的主题和其它元素进行分组的目录。当向用户显示标号时,该标号就标识用户目录。可选的主题属性是描述 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 文件名与锚点标识分开。
(在 plugin.xml 文件中)
<extension point="org.eclipse.help.toc"> <toc file="maindocs.html" 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>
假定以“samples”开头的路径中存在多个文档,则这些文档不会显示在导航树中,但是可以使用搜索来访问。这是由于 plugin.xml 文件内的 <toc file="sample.xml" extradir="samples" /> 元素中存在“extradir”属性。例如,搜索“创建 Java 项目”可能会返回文档“创建 Java 项目的其它方法”,路径为 samples/sample2.html。
国际化可以翻译 TOC XML 文件并且生成的副本(具有已翻译的标号)应放置在 nl/<language>/<country> 或 nl/<language> 目录中。<language> 和 <country> 表示两字母语言和国家或地区代码,如在语言环境代码中使用的那样。例如,“繁体中文”翻译应放置在 nl/zh/TW 目录中。nl/<language>/<country> 目录具有比 nl/<language> 高的优先级。仅当在 nl/<language>/<country> 目录中找不到文件时,才将会使用 nl/<language> 中的文件。将最后搜索插件的根目录。
可通过创建具有已翻译版本的文档的 doc.zip 文件并将
doc.zip 文件放置在
nl/<language>/<country> 或 nl/<language> 目录中来使
doc.zip 中包含的文档本地化。在缺省查找插件目录之前,帮助系统将查找这些目录下面的文件。
API 信息:使用此扩展点不需要任何代码。所需要的只是提供在 plugin.xml 文件中提到的适当清单文件。
所提供的实现:随 Eclipse 平台一起提供的帮助系统用户界面的缺省实现完全支持 toc 扩展点。
Copyright (c) 2000, 2003 IBM Corporation and others.
该程序及附带提供的资料是基于“一般公共许可证”(Common
Public License) v1.0 的条款提供的,本发行版中提供了该许可证条款,并且也可
在以下位置处找到该条款:http://www.eclipse.org/legal/cpl-v10.html