目录(TOC)

标识符:org.eclipse.help.toc

描述:用于为个别插件注册联机帮助添加项。

向帮助文件进行添加的每个插件一般应执行下列操作:

toc 扩展点的配置标记(这是 plugin.xml 文件的内容)

    <!ELEMENT toc EMPTY>
    <!ATTLIST toc file CDATA #REQUIRED>
    <!ATTLIST toc primary (true | false) "false">
    <!ATTLIST toc extradir CDATA #IMPLIED>

toc 的配置标记(这是 TOC 文件的内容)

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

国际化

可以翻译 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 平台一起提供的帮助系统 UI 的缺省实现完全支持 toc 扩展点。


Copyright IBM Corp. and others 2000, 2002. All Rights Reserved.