使用Eclipse帮助系统为项目编制文档 - 编程入门网

使用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>

使用Eclipse帮助系统为项目编制文档(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

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

处理庞大的目录

如

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!