[转载]使用 Eclipse 帮助系统为项目编制文档

使用 Eclipse 帮助系统为项目编制文档

具有非常强大的 IDE 的 Eclipse 平台中有其自己的帮助系统，这个系统基于一个引用 HTML 文件的 XML 目录表。鲜为人知的是，您不必去编写 Eclipse 插件就可以使用它。任何项目都可以使用一个简化版的平台来提供专业的、易用的和可搜索的文档。这个文档系统已经成功地应用于许多 IBM 项目，包括像 WebSphere Application Server 那样大的项目。

当您访问 Eclipse 帮助系统时（通过 Help > Help Contents）， 您实际上启动了一个嵌入式的 Apache Tomcat 服务器。然后打开了一个基于 Web 浏览器的窗口，定位到服务器上适当的页（见图 1）。文档同时在左侧提供了一个可折叠的索引，右侧是 HTML 文档，随时可以进行搜索（幸好有 Apach Lucene 搜索引擎）。由于使用了 Tomcate，您不只可以用 HTML；例如，您可以用 JSP 来使您的文档能动态改变 （可是我们稍后将会讨论避免这样做的可能原因之一）。

图 1. Eclipse 帮助示例

文档插件的“Hello World”

文档被拆分为“书”，只要您愿意，在帮助系统的一个实例中可以有任意多的书。每本书都编写为一个 Eclipse 插件，不过好在这一步要做的工作很少。为编写一个示例插件，您将需要一个 plugin.xml 文件来描述您的插件，其内容类似于清单 1。

清单 1. 插件定义

version="1.0.0" provider-name="IBM">

根据您的项目，将插件的 name 、 id 、 version 和 provider-name 修改为适当的值。扩展点 org.eclipse.help.toc 将此标识为帮助系统的一个插件。toc.xml 文件被引用进来，作为这个插件的目录；这个文件将为 Eclipse 帮助窗口左侧窗格中的分级信息提供数据。清单 2 是一个包含有类似内容的示例文件。

清单 2. 目录定义

包装插件

在最终的文档中，每一个主题元素都表现为导航列表中的一个条目。这些主题可以嵌套（它们可以包含更多的主题），每一个指向一个 HTML 或者 JSP 文件。当您完成了这一步，所有您需要做的就是包装如图 2 所示的结构中的所有内容（注意，插件目录名与在 plugin.xml 中定义的插件属性 id 和 version 相匹配）。

图 2. 插件目录结构

为了方便，也为了压缩文件的大小，Eclipse 允许您将实际的文件（HTML 文件）存放在一个名为 doc.zip 的 ZIP 文件中，所以您可以使用图 3 所示的目录结构。

图 3. 另一种插件目录结构

查看文档

测试您的插件的最简单方法就是，将整个目录（像上面的一样）拖入到已经安装 Eclipse 平台的插件目录下，然后启动 Eclipse 并选择 Help > Help Contents。您将得到一个添加了您的插件的帮助窗口（类似于 图 1中那个）。

使用 IDE 来进行测试当然是好的，但是为了在没有 IDE 时也可以使用，文档需要更加易用，所以我们真正希望的是要后台运行一个进程，让我们可以在浏览器中连接它。这种方式的操作被称为 InfoCenter（见图 4）。启动 InfoCenter 进程（基本上是 Apache Tomcat）的指令包含在 Eclipse 帮助系统文档中（请参阅本文后面 参考资料 部分中的链接）。注意，还有一些指令用来简化 Eclipse 系统，以便刚好满足您的需要。

图 4. 运行的 InfoCenter

处理庞大的目录

如果您的项目有多人参与工作，或者有大量的文档，那么更新单个目录文件 (toc.xml) 会变得不切实际。为改变这一状况您可以向主 toc.xml 文件中的主题添加一个 link 元素（见清单 3 的示例）。

清单 3. 目录定义

bar-toc.xml 文件正是另一个目录，格式应该和任何其他的 toc.xml 文件完全相同。当文档被浏览时，使用这种方法和简单地直接包含另外的 topic 元素没什么不同。

回页首

生成独立的文档集

当然，如果您不介意需要发布 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"?> version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <!-- Only add a hyperlink when there is something to link to -> <!-- If there are any nested topics, then start a new sub-list ->

通过一个 XSLT 处理器，比如 Apache Xalan，使用前面的 XSLT 来处理 toc.xml 文件，生成一个在浏览器中查看时如图 5 所示的 HTML 文件：

图 5. 生成的 index.html

回页首

结束语

使用 Eclipse 帮助系统可以轻松开发出令您的朋友和同事大为惊奇的、具有专业外观的并且可搜索的文档。如果您不需要独立的文档集，那么您甚至不需要理会 XSLT；您只需要编写两个简单的 XML 文件就可以愉快地享用文档了。开始吧。

来自 “ ITPUB博客 ” ，链接：http://blog.itpub.net/374079/viewspace-130678/，如需转载，请注明出处，否则将追究法律责任。

转载于:http://blog.itpub.net/374079/viewspace-130678/