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

关注

转载最新推荐文章于 2025-12-07 07:30:00 发布 1.7k 阅读 AI 写同款· GEO 优化 ›

荣耀X16 Plus 2026深度评测：AI PC真实生产力落地指南 AI PC正从参数宣传走向场景落地，其核心在于将大模型能力嵌入真实工作流——不是追求本地运行GPT-5.5等未商用模型，而是通过YOYO智能体框架实现文案生成、代码编写、会议纪要等高频任务的秒级响应。依托英特尔酷睿Ultra 5处理器的能效优化、LPDDR5高带宽内存与PCIe 4.0 SSD的协同调度，该类设备在办公续航、静音控制与跨设备协同上形成技术闭环。典型应用场景覆盖小红书内容创作、前端开发调试、多端文件续传及视频双语字幕实时翻译，真正解决都市白领、研究生与自由职业者‘想做即得’的效率痛点。阅读详情

构建易于使用且可搜索的帮助文档

级别：入门

Arthur Barr
软件工程师，IBM
2004 年 3 月

具有非常强大的 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. 插件定义


<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。

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 文件：

图 5. 生成的 index.html

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

参考资料

下载本文中用到的源代码。
在 Eclipse 帮助项目 Web 站点上查找更多关于 Eclipse 帮助项目的信息。
阅读将帮助系统作为一个信息中心安装。注意，这些说明适用于 Eclipse 2.1 平台。
在 Doug Tidwell 的优秀教程“转化XML文档”（developerWorks, 2000 年 5 月）中深入学习 XSLT。
下载 Apache Xalan XSLT 处理器（有 Java 和 C 版本，但是如果您正在使用 Java 2 v1.4 运行期环境，那么标准的已经附带了一个XSLT 处理器）。
查看 IBM WebSphere Application Server V5.1 InfoCenter 来理解帮助系统在大的项目上如何运行。
在 developerWorks 开放源代码项目专区查找更多为 Eclipse 用户准备的文章。同样在 alphaWorks 可以了解最新的 Eclipse 技术下载。

关于作者
Arthur Barr 是英国 IBM Hursley 开发实验室的一名软件工程师。他已经将本文的心得应用到 Business Integration for Games 项目中，这应该是他当前正在致力的项目。可以通过 arthur.barr at uk.ibm.com 与 Arthur 联系。