向帮助文件进行添加的每个插件一般应执行下列操作:
可以通过使用 index
元素有选择地预构建和注册搜索索引,以尝试执行首次搜索。每个插件只能注册一个索引 - 多个 index
元素将导致未定义的行为。
<!ELEMENT extension (toc* , index?)>
<!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 文件名与锚标识分开。
<!ELEMENT index EMPTY>
<!ATTLIST index
path CDATA #REQUIRED>
(从 3.1 开始)一个可选元素,它允许声明从此插件提供的文档创建的预构建搜索索引。
index/
、nl/ja/JP/index/
和 nl/en/US/index/
等)。(在 plugin.xml 文件中)
<extension point=
"org.eclipse.help.toc"
>
<toc file=
"maindocs.html"
primary=
"true"
/>
<toc file=
"task.xml"
/>
<toc file=
"sample.xml"
extradir=
"samples"
/>
<index path=
"index/"
/>
</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 中包含的文档本地化。在缺省查找插件目录之前,帮助系统将查找这些目录下面的文件。
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html