当我们通过Help > Help Contents方式打开 Eclipse 的帮助系统时，本质上是在Eclipse中启动了一个嵌入式的 Apache Tomcat 服务器。然后打开了一个基于 Web 阅读器的窗口，随后定位到服务器上的页。同时在页面左侧提供了一个索引，右侧是 HTML 文档，并且随时能够执行搜索（基于 Apach Lucene 搜索引擎）。
图1 Eclipse帮助示例
在此帮助系统中，文档被拆分为“书”，并且在此系统的一个实例中你可以添加任意多的书。每本书都编写为一个 Eclipse 插件，好在这一步要做的工作很少。接下来介绍编写一个示例插件的步骤，首先需要一个 plugin.xml 文件来描述插件，其内容类似于清单 1。
清单 1. 插件定义
<plugin name="help document" id="com.zuccess.help.doc"
version="1.0.0" provider-name="ZUCCESS">
<extension point="org.eclipse.help.toc">
<toc file="toc.xml" primary="true" />
</extension>
</plugin>
根据具体的项目，将插件的 name 、 id 、 version 和 provider-name 修改为适当的值。扩展点 org.eclipse.help.toc 将此标识为帮助系统的一个插件。toc.xml 文件作为这个插件的目录被引用进来；将为 Eclipse 帮助窗口左侧的分级信息提供数据。清单 2 是一个包含有类似内容的示例文件。
清单 2. 目录定义
<toc label="Sample Documentation">
<topic label="My Section" href="mySection.html">
<topic label="Foo" href="foo.html"/>
<topic label="Bar" href="bar.html"/>
</topic>
</toc>
包装插件
在最终的文档中，每一个主题元素都表现为导航列表中的一个条目。这些主题可以嵌套（它们可以包含更多的主题），每一个指向一个 HTML 或者 JSP 文件。当你完成了这一步，所有你需要做的就是包装如图 2 所示的结构中的所有内容（注意，插件目录名与在 plugin.xml 中定义的插件属性 id 和 version 相匹配）。
图 2. 插件目录结构
为了方便，也为了压缩文件的大小，Eclipse 允许你将实际的文件（HTML 文件）存放在一个名为 doc.zip 的 ZIP 文件中，所以你可以使用图 3 所示的目录结构。
图 3. 另一种插件目录结构
处理庞大的目录
如果你的项目有多人参与工作，或者有大量的文档，那么更新单个目录文件 (toc.xml) 会变得不切实际。为改变这一状况你可以向主 toc.xml 文件中的主题添加一个 link 元素（见清单 3 的示例）。
清单 3. 目录定义
<toc label="Sample Documentation">
<topic label="My Section" href="mySection.html">
<topic label="Foo" href="foo.html"/>
<topic label="Bar" href="bar.html">
<link toc="bar-toc.xml" />
</topic>
</topic>
</toc>
bar-toc.xml 文件正是另一个目录，格式应该和任何其他的 toc.xml 文件完全相同。当文档被浏览时，使用这种方法和简单地直接包含另外的topic 元素没什么不同。
查看文档
测试你的插件的最简单方法就是，将整个目录（像上面的一样）拖入到已经安装 Eclipse 平台的插件目录下，然后启动 Eclipse 并选择 Help > Help Contents。你将得到一个添加了你的插件的帮助窗口（类似于图一中那个）。
使用 IDE 来进行测试当然是好的，但是为了在没有 IDE 时也可以使用，文档需要更加易用，所以我们真正希望的是要后台运行一个进程，让我们可以在浏览器中连接它。这种方式的操作被称为 InfoCenter。启动 InfoCenter 进程（基本上是 Apache Tomcat）的指令包含在 Eclipse 帮助系统文档中。
生成独立的文档集
当然，如果你不介意需要发布 20 MB 额外的代码，使用 Eclipse 帮助系统当然好，但是这对小些的项目来说是不现实的。在中心服务器上安装一个 InfoCenter，让人们可以远程访问。人们可以充分利用 Eclipse 帮助系统的所有功能（比如搜索），但是那些不能连接的人还是束手无策。所以，除了使用在主机上的 InfoCenter 以外，有必要将普通的 HTML 包含在一个可下载的包中。只要你没有使用任何服务器端技术，比如 JSP，那么你可以方便地生成一个 HTML 目录来取代 Eclipse 所用的 XML 目录。这就是为什么我们要用 XSLT。
XSLT (eXtensible Stylesheet Language Transformations) 是一种将 XML 格式转化为其他格式的技术，例如 XHTML（一个更为严格的 XML 版本的 HTML）。XSLT 提供了丰富而强大的语言来完成转换，其本身就是很多书和文章的主题，所以我们在这里不再细述。清单 4 给出了一个 toc.xml 文件简单转换的例子，将条目呈现为嵌套的 HTML 列表。注意，这个特定的转换为全部文档集的内容创建了一个单独的 HTML 文件，文件量较大时这可能不实用。所以，如果你已经将你的目录拆分为多个文件，这个 XSLT 将失效。
清单 4. 生成 HTML 目录的示例 XSLT
<?xml version="1.0"?>
<xsl:stylesheet
version="1.1"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="no" encoding="ISO-8859-1" />
<xsl:template match="toc">
<html>
<head />
<body>
<h1><xsl:value-of select="@label" /></h1>
<ul>
<xsl:apply-templates />
</ul>
</body>
</html>
</xsl:template>
<xsl:template match="topic">
<li>
<xsl:choose>
<xsl:when test="@href">
<!-- Only add a hyperlink when there is something to link to ->
<xsl:element name="a">
<xsl:attribute name="href">
<xsl:value-of select="@href" />
</xsl:attribute>
<xsl:value-of select="@label" />
</xsl:element>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@label" />
</xsl:otherwise>
</xsl:choose>
<!-- If there are any nested topics, then start a new sub-list ->
<xsl:if test="descendant::topic">
<ul>
<xsl:apply-templates/>
</ul>
</xsl:if>
</li>
</xsl:template>
</xsl:stylesheet>
通过一个 XSLT 处理器，比如 Apache Xalan，使用前面的 XSLT 来处理 toc.xml 文件，生成一个在浏览器中查看时如图 5 所示的 HTML 文件：
结束语
使用 Eclipse 帮助系统可以轻松开发出令你的朋友和同事大为惊奇的、具有专业外观的并且可搜索的文档。如果你不需要独立的文档集，那么你甚至不需要理会 XSLT；你只需要编写两个简单的 XML 文件就可以愉快地享用文档了。
参考文档：使用 Eclipse 帮助系统为项目编制文档，Arthur Barr，2004年3月
