65.9K
CodeProject 正在变化。 阅读更多。
Home

使用 Eclipse 帮助系统记录您的项目

Eduardo Mozart de Oliveira
starIconstarIconstarIconstarIconstarIcon

5.00/5 (5投票s)

2018年8月24日

CPOL

7分钟阅读

viewsIcon

17781

任何项目都可以使用平台的精简版来提供专业、易用且可搜索的文档

引言

当您访问 Eclipse 帮助系统（通过 帮助 > 帮助内容）时，实际上是在启动一个嵌入式 Apache Tomcat 服务器。然后会打开一个基于 Web 浏览器的窗口，指向该服务器上的正确页面（参见图 1）。文档提供了一个可折叠的左侧索引和右侧的 HTML 文档，并且可以进行搜索（感谢 Apache Lucene 搜索引擎）。由于使用了 Tomcat，您不仅限于 HTML。例如，您可以使用 JSP 使您的文档动态更改（尽管我们稍后会讨论避免这样做的可能原因）。

图 1. Eclipse 帮助示例

安装 Eclipse 插件开发环境 (PDE)

您必须安装用于 Java 开发人员的 Eclipse IDE。您可以安装默认包含 PDE 的 Eclipse Committers 版本。

对于 Eclipse IDE for Java Developers Mars，请转到

  1. 在继续之前，从 Eclipse 菜单栏中选择 帮助 > 检查更新
  2. 从 Eclipse 菜单栏中选择 帮助 > 安装新软件
  3. 在 工作方式 字段中，选择 "Mars - http://download.eclipse.org/releases/mars"
  4. 展开 Eclipse Plugin Development Tools，然后选择 Eclipse Plug-in Development Environment （参见图 2），然后只需执行 下一步、下一步、接受许可协议、完成
  5. 出现提示时，重新启动 Eclipse

图 2. 安装 Eclipse PDE

如何创建 PDE 插件？

开发和维护插件的最简单方法是使用 PDE 提供的特殊向导和编辑器。使用向导，您只需几次鼠标点击即可生成基本插件。

  1. 从 Eclipse 菜单栏中选择 文件 > 新建 > 其他...
  2. 选择 插件开发 > 插件项目（参见图 3） > 下一步

    图 3. 创建新的插件项目
  3. 为您的插件选择一个合适的名称（参见图 4）。大多数 Eclipse 插件名称以org.eclipse开头，但您可以在此处选择任何合适的名称。点击 下一步。

    图 4. 项目名称
  4. 勾选 使用模板创建插件 （参见图 5）
  5. 选择 带示例帮助内容的插件 > 下一步

    图 5. PDE 模板
  6. 选择 带示例帮助内容的插件 > 下一步。通过点击 下一步 来接受接下来的向导页面中的所有默认设置。
  7. 在左侧面板中选择 plugin.xml 文件。
  8. 点击 扩展 选项卡，然后点击 添加...（参见图 6）

    图 6. 添加示例内容
  9. 点击 生成用于测试的主要目录 > 完成 （参见图 7）

    图 7. 示例帮助内容

文档插件的“Hello, World”

文档被分成“书籍”，您可以在一个帮助系统实例中拥有任意数量的书籍。每本书都写成一个 Eclipse 插件，但幸运的是，这里的工作量很小。要编写一个简单的插件，您需要一个 plugin.xml 文件来描述您的插件，它看起来应该像列表 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 帮助窗口左侧窗格中的分层信息提供数据。一个简单的文件包含如下所示的内容

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

如果您的项目有超过几个人参与，或者有大量的文档集，更新单个目录（toc.xml）文件可能会变得不切实际。您可以通过在主 toc.xml 文件的主题中添加 link 元素来更改此设置。

<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 元素之间没有区别。

打包插件

Eclipse 帮助系统由以下组成：

  • HTML、CSS 和支持的图像文件，通过 DITA Open Toolkit（或其他 DITA 处理器）生成
  • plugin.xml 文件，它定义了帮助系统的位置以及目录（TOC）的文件名
  • TOC 文件，这是一个简单的 XML 文件，指定了帮助系统中主题的层次结构和位置

最终文档中的每个主题元素都由导航列表中的一个条目表示。这些主题可以嵌套（它们可以包含更多主题），每个主题都指向一个 HTML 或 JSP 文件。完成此操作后，您只需将所有内容打包到图 8 所示的结构中（请注意，插件目录名称与 plugin.xml 中定义的插件的 id 和 version 属性匹配）。

图 8. 插件目录结构

为了方便起见，并减小文件大小，Eclipse 允许您将所有实际文档（HTML 文件）保留在一个名为 doc.zip 的 ZIP 文件中，因此您可以使用图 9 所示的目录结构。

图 9. 替代插件目录结构

为了支持本地化，您可以使用以下目录结构

com.my.plugin/
              plugin.xml
              nl/
                 de/
                    doc_index.zip
                 en/
                    doc_index.zip
                 zh/
                    CN/
                       doc_index.zip
              other files of this plugin

查看您的文档

  1. 在左侧面板中选择 plugin.xml 文件（参见图 6）
  2. 点击 构建 选项卡（参见图 10）
  3. 在 二进制构建 面板中勾选文档文件

    图 10. 选择要构建的文档文件
  4. 在 导出 中，点击 导出向导 链接（参见图 11）。
  5. 选择要保存生成的 *.jar 文件的目录，然后点击 完成

    图 11. 构建文档

测试插件的最简单方法是将 *.jar 文件放入已安装的 Eclipse Platform 的 plugins 目录中，然后启动 Eclipse 并选择 帮助 > 帮助内容。您将看到一个包含您插件的帮助窗口（类似于图 1）。

独立帮助

使用 IDE 进行测试很好，但要独立于 IDE 使用，文档需要更易于访问，因此我们真正想要的是运行一个后台进程，让我们可以通过浏览器连接到它。您可以允许用户通过安装信息中心和文档插件到服务器上来访问互联网或内网上的帮助系统。客户端通过导航到一个 URL 来查看帮助，帮助系统会显示在他们的 Web 浏览器中。

Eclipse 帮助系统通过 Java Server Pages (JSP) 通过 Web 服务器进行交付。Eclipse 帮助的交付系统通常称为 Eclipse InfoCenter。独立的 Eclipse Help InfoCenter 是一个自包含的帮助文件集合和一个捆绑了 JSP 支持的 Web 服务器，没有完整的 Eclipse IDE。交付组件（包括捆绑的 Web 服务器）的大小约为 80MB（压缩后 40MB）。该软件包还包括一个专用查看应用程序，这是一个精简版浏览器（参见图 4）。Eclipse 帮助系统在技术上称为 插件。一个 InfoCenter 通常由多个帮助系统（插件）组成。

图 12. InfoCenter 运行中

如果您正在创建一个非基于 Eclipse 框架的应用程序，您仍然可以使用 Eclipse 帮助系统。您的应用程序可以打包和安装独立的帮助系统，这是一个非常小的 Eclipse 版本，其中除了帮助系统之外的所有内容都已被剥离。当应用程序不是基于 Java 的，或者在应用程序未运行时需要帮助时，可以从系统 shell、shell 脚本或桌面快捷方式使用独立帮助，并提供命令行选项，而不是调用 Java API。

启动 InfoCenter 进程（基本上是 Apache Tomcat）的说明包含在 Eclipse 帮助系统的文档中（参见相关主题）。请注意，还有关于如何精简 Eclipse 系统以仅获取您所需部分的说明。

关注点

当然，如果您不介意分发所需的 40MB 以上代码，使用 Eclipse 帮助系统也是一件很方便的事。在中央服务器上托管 InfoCenter 允许人们远程连接。人们可以获得使用 Eclipse 帮助系统的所有好处（如搜索），但没有连接性的人却被排除在外。因此，除了使用托管的 InfoCenter 外，在可下载的软件包中包含纯 HTML 也是很有用的。只要您没有使用任何服务器端技术（如 JSP），您就可以轻松生成 HTML 目录来替换 Eclipse 使用的 XML 目录。

使用 Eclipse 帮助系统是一种相对轻松的方式来开发专业外观、可搜索的文档，这会让您的朋友和同事们惊叹不已。

参考文献

  1. 使用 Eclipse 帮助系统文档化您的项目。IBM Development。
  2. 独立帮助。Eclipse Documentation。
  3. Eclipse Standalone Help。Dita Wiki。
  4. FAQ 如何创建插件？ Eclipsepedia。

相关主题

  1. 将信息中心部署为 Web 存档。Eclipse Documentation。
  2. 独立帮助。Eclipse Documentation。
  3. 信息中心。Eclipse Documentation。

历史

  • 2018 年 8 月 24 日：初始版本
© . All rights reserved.