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

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

图 1. Eclipse 帮助示例

文档插件的“Hello World”

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

清单 1. 插件定义

<plugin　name="Sample　Documentation　Plug-in"　id="com.ibm.sample.doc"
　　 version="1.0.0"　provider-name="IBM">
　　 <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>