[引用] 使用 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>

包装插件
在最终的文档中，每一个主题元素都表现为导航列表中的一个条目。这些主题可以嵌套（它们可以包含更多的主题），每一个指向一个 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. 目录定义

<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 元素没什么不同。

生成独立的文档集
当然，如果您不介意需要发布 20 MB 额外的代码，使用 Eclipse 帮助系统当然好，但是这对小些的项目来说是不现实的。在中心服务器上安装一个 InfoCenter，让人们可以远程访问。人们可以充分利用 Eclipse 帮助系统的所有功能（比如搜索），但是那些不能连接的人还是束手无策。所以，除了使用在主机上的 InfoCenter 以外，有必要将普通的 HTML 包含在一个可下载的包中。只要您没有使用任何服务器端技术，比如 JSP，那么您可以方便地生成一个 HTML 目录来取代 Eclipse 所用的 XML 目录。这就是为什么我们要用 XSLT。

标签：

版权申明：本站文章部分自网络，如有侵权，请联系：west999com@outlook.com
特别注意：本站所有转载文章言论不代表本站观点，本站所提供的摄影照片，插画，设计作品，如需使用，请与原作者联系，版权归原作者所有