当前页面: 开发资料首页 → Eclipse 专题 → 集中化 Eclipse 中的帮助功能

集中化 Eclipse 中的帮助功能

摘要: 本文将阐述如何利用 Eclipse 帮助和插件架构的动态特性，创建一个集中的帮助存储库。重点介绍如何使用内容帮助表来创建 Eclipse 插件，如何通过 Infocenter 来集中化管理帮助文件，以及如何创建使您能够直接从 Eclipse 主菜单访问集中的帮助存储库的新菜单项。

长期以来，开发人员一直认为构建模块系统可以很容易地更新系统中的某个部分，而不影响系统的其他部分。模块性还可以通过新的方法很方便地对原始系统进行扩展。这就是作为一组插件来构建 Eclipse 的动机，这允许其他开发人员替代或增强已有的模块。

Eclipse 中的“帮助”与其他环境一样，是使用插件架构构建的。本文讨论了如何利用这个有用的架构来外部化帮助内容。本文假定您已具备 Java?、Eclipse 和 Web 主题方面的应用知识。但并不要求您了解在 Eclipse 中“帮助”是如何组织的，以及插件的工作原理方面的所有知识。本文的目的是向您说明在集中的服务器（企业内部网或 Internet）上承载 Eclipse 环境的“帮助”方法和原因以及如何从该环境中对它进行访问。

为什么要集中化？

Eclipse 中的“帮助”不是单块集成实体，而是为提供整体概念合并在一起的一系列插件。但即使这样，也没有真正回答以下问题：“为什么要集中管理 Eclipse 中的‘帮助’？如果下载 Eclipse 的 Java 版本，则可以进行 Java 开发，并且可以得到本地所需的所有帮助”。这对于整个开发小组也是如此。其中每个人都可以有自己的本地“帮助”副本，您可以很好地使用这些副本，一直到有一天出现额外的插件。

插件的到来

在实际的项目中，那一天将会到来，到时您会认识到自己以及开发小组的其他成员都需要一两个插件服务（或者由于它们经济实惠，您会需要更多的插件）。对于任何不平凡的小组开发工作，从构建过程到正在使用的第三方 JAR 文件都要确保每个人的环境是相同的。这只是一个项目的最佳实践：确保小组中的每个人都在构建同一事物。事实上，大量的第三方工具的作用只是处理这个实践，这些工具有：Ant、Java Make 工具，用于支持连续集成的 CruiseControl，以及其他大量的工具。经验丰富的 Java 开发人员认识到确保开发环境和过程在整个小组中可重复利用是一件较好的事情。为什么“帮助”又各不相同呢？

当您在 Eclipse 中安装插件时，经验比较丰富的人员还可安装他们自己“帮助”，由于组织“帮助”的方式的不同，似乎可以将权利合并到现有的“帮助”基础架构中。这就是外部可访问的“帮助”存储库能够奏效的原因。正像您要保持开发过程的其他部分的一致性一样，您的“帮助”不需要相同的一致性吗？“帮助”包含现有的 Eclipse 帮助，还包含通过其他插件合并的帮助。

为了确保更好地使用帮助系统，您应当将自己的内容添加到此系统中，方法是将特定于项目和小组的通知添加到标准的帮助条目中。您可以下载使您工作更轻松的插件，但是必需确保小组中的每个人都能用相同的方法使用它，并且能够访问关于插件的相同通知。如果将所有信息放在同一位置，就会减少信息失去同步的可能性。这也是《注重实效的程序员》一书中写到的最佳实践，该书的作者是 Dave Thomas 和 Andy Hunt（请参阅参考资料)。他们阐述了“不要重复自己”(Don't Repeat Yourself, DRY) 的原则：如果您将同一信息存放在多个地方，它将失去同步，并且您不会再信任它的任何特定实例。如果遵循“不要重复自己”原则，您会了解单一副本是权威副本。这一点也适用于“帮助”。

Eclipse 中的“帮助”组织

在开始外部化 Eclipse 中的“帮助”之前，您必须了解一下是如何按环境组织“帮助”的。要做到这一点,您需要进一步弄清 Eclipse 中的“帮助”组织。

查看“帮助”内部结构的最简单方法是使用 help 扩展点构建一个插件。由于 Eclipse 附带插件开发环境（Plug-in Development Environment，PDE），所以构建一个新插件非常容易。首先，使用下列几个方法之一创建一个新插件项目：File>New Project，然后选择 File>New Plug-in Project...，或结合使用库方法和 Control-N。如果您选择这两个通用项目创建选项中的任何一个方法，屏幕上都会显示图 1 所示的 New Project 对话框。

向导的下一步允许您指定项目的详细信息，如名称和目录结构。此对话框如图 2 所示。

在这种情况下，您只能创建“帮助”插件扩展点。但是，PDE 自带了多种预置的扩展点，其中包括一个用于“帮助”扩展的扩展点。要查看扩展点列表，请在图 2 的 Project Settings 中选中“Create a Java Project”，否则在随后的向导对话框中不会出现示例扩展点。在这种情况下，您将最终创建 Java 代码，因此将选择该选项。如果您只需要创建一个“帮助”扩展，并且要使用预定义的扩展点，那么请保持选中此选项。

下一个向导页面允许您指定关于插件的元信息；如图 3 所示。

为了使构建插件变得更方便，PDE 自带了多种模板，其中包括预定义类型的插件。您可以利用这些模板围绕“帮助”插件创建基础结构。图 4 显示了一个向导页面，该页面允许选择模板。

自定义插件向导提供了多种扩展点，其中有一个是“帮助”扩展，如图 5 所示。

最后，您要选择“帮助”插件将要提供的内容类型，它显示在最后一个向导页面上，如图 6 所示。

通过 PDE 向导这一过程的最后结果是形成一个文件集，其中包括 XML、Java 源和构建基础结构。

TOC 的内部

PDE 向导（图 6 所示）的最后一个页面会创建一个 TOC.XML 文件，它是将包含在插件中的那些“帮助”文件的内容表（TOC）。这个 TOC 格式用于 Eclipse 的内部帮助和插件；它始终是一致的。默认情况下生成的 TOC 文件如清单 1 所示。

清单 1. 默认情况下生成的 TOC 文件
<table bgcolor="#eeeeee" width="100%" cellpadding="5" cellspacing="0" border="1"><tr><td>



<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

</td></tr></table>

注意：在图 6 中创建的标题显示在标记的顶部，它指向 html/toc.html 的主题。这个 TOC 条目位于帮助集的帮助目录结构中的最高一层。也就是说，实际的帮助 HTML 文件将出现在根目录下指定的目录结构中。通常情况下，为了节省空间，这些 HTML 文件以 zip 文件形式出现（传统上称为 doc.zip）。如果对 Eclipse 插件目录进行搜索，将会看到大量的 doc.zip 文件，其中的每一个文件都包含一个将其合并到 Eclipse 的主帮助中的帮助（无论何时调用该帮助）。

TOC 文件中的其他条目指向与第一个 TOC 同时生成的其他的 TOC。其中有“gettingstarted”、“concepts”和“tasks”。这些二级 TOC 条目中的每一个在项目中都有对应的 XML 文件目录。另外在该项目中，PDE 还为 HTML 文件内容创建了适当的目录结构。在图 7 中，从 Package explorer 截取的片断明显地表现出了这种情况。

由于有了这个结构，您可以用适当的结构创建满足您需要的多个帮助文件，并将他们放入 zip 文件中，这样就可以通过 Eclipse 中的帮助系统浏览器将他们完美地合并成一个文件。

构建外部存储库

知道了 Eclipse 中帮助文件的结构方式之后，您会检查如何将它外部化到独立的服务器中。Eclipse 通过提供一个称为 Infocenter（与 Eclipse 一起安装）的工具简化了这一过程。您可能已猜到，Eclipse 中的帮助系统实际上是由嵌入 Web 服务器/servlet 引擎驱动的。事实上，它将拆分式版的 Apache Tomcat 用作帮助应用服务器。Eclipse 附带的一个插件是 org.eclipse.help.appserver_3.0.0，它可以封装 Web 服务器。Infocenter 使应用服务器外部化，这样您可以在 Eclipse 环境之外对其进行操作。

Infocenter

要在外部服务器上设置 Infocenter，请安装 Eclipse 运行时二进制文件 (Eclipse Runtime Binary)，您可以从 Eclipse 下载 zip 文件形式的这个文件。将它解压缩到服务器上的目录结构中（注意：此过程与安装 Eclipse 相同，是在服务器上执行的操作）。除 infopops（对上下文敏感的工具将提供弹出式窗口）和 Active 帮助（它可从帮助视图执行命令，像创建一个新文件一样）外，Infocenter 支持所有的内部帮助功能。这些高级帮助功能从外部服务器是不可能实现的。Infocenter 作为一组 Java 类包含在二进制文件中，可以从命令行调用它。

要启动服务器上的 Infocenter，请发出如下命令，其中 [ehome] 是 Eclipse 的安装目录（为便于阅读分成了多行，它应该是单个命令行，如清单 2 中所示）。

清单 2. 启动服务器上的 Infocenter
<table bgcolor="#eeeeee" width="100%" cellpadding="5" cellspacing="0" border="1"><tr><td>



java
-classpath [ehome]\plugins\org.eclipse.help.base_3.0.1\helpbase.jar
org.eclipse.help.standalone.Infocenter
-eclipsehome [ehome]
-port 8081
-command start

</td></tr></table>

此命令将 classpath 设置为指向 Infocenter JAR 文件，通知该文件 Eclipse 安装的位置，设置端口号并发出 start 命令。要停止该服务器，您可发出相同的命令，但要用 shutdown 代替 start。启动 Infocenter 之后，立即就可以使用浏览器并发布一个 URL，如 http://localhost:8081/help/index.jsp。

您将在浏览器中看到标准的 Eclipse 帮助信息，如图 8 所示。

独立的 Infocenter

Infocenter 是一个独立服务器，所以它不需要其他 Web 服务器。但是，在实际环境中您要控制一些重要问题（例如，由常规 Web 服务器能够很好处理的访问控制、可视性和其他方面的问题）。您可以基于 URL 模式，轻松地将 Web 服务器设置为将命令转发到 Infocenter。

例如，您可以将 Apache 中的代理模块设置为以 http://bigsprawlingcompany.com/eclipsehelprepo 的形式将请求重新定向到 Infocenter URL，该 URL 看上去像是对 Apache 的 conf/httpd.conf 文件使用以下更改的 http://internalhelpserver:8081/help。


LoadModule proxy_module modules/ApacheModuleProxy.dll
ProxyPass /eclipsehelprepo http://internalhelpserver:8081/help
ProxyPassReverse /eclipsehelprepo http://internalhelpserver:8081/help

</td></tr></table>

<table border="0" cellspacing="0" cellpadding="0" width="100%"><tr><td>
</td></tr></table><table class="no-print" cellspacing="0" cellpadding="0" align="right"><tr align="right"><td>
<table border="0" cellpadding="0" cellspacing="0"><tr><td valign="middle">
</td><td valign="top" align="right"></td></tr></table></td></tr></table>

帮助访问中的堵漏

现在您已将帮助外部化，您需要一种从 Eclipse 内部访问它的方法。可以使用好几种方法可做到这一点。在本文中，您将会创建一个指向新的远程库新顶级菜单项。通过重写现有菜单项，您能够替代现有的帮助行为，但这是不可取的。破坏已经存在的东西通常不是一个好做法，尤其是在这种情况下。您或许不想让开发人员在帮助服务器出于某些原因而停机时失去获得本地帮助的能力。当开发插件时最好使用 Hippocratic Oath 的部分变体：首先不要损坏它。

创建新菜单项的最容易方法是让 PDE 向导为您构建基础结构。要创建此帮助库菜单项，请使用与前面更改一个向导页面相同的顺序。对于图 5 中显示的模板选择页面，添加了一个新的“示例操作”，如图 9 所示。

此操作为新菜单项创建一个基础结构。因为您正在创建新的操作，所以您还会得到新的向导页面，该向导页面允许您指定操作名称。此页面如图 10 所示。

此页面允许您命名并随后创建 Action 类。此 Action 类包含用于在 Eclipse 中添加新操作的示例代码，在本例中绑定到菜单项。只有您需要添加的代码才是调用帮助查看器的代码，该查看器可以是标准的 Eclipse 帮助查看器，也可以是浏览器。在这种情况下，您可以调用用户的默认浏览器。使用功能完备的浏览器可以提供与帮助查看器相同的各种好处，而且还允许用户在与开发相关的 Web 上的收藏夹旁为帮助库代码创建收藏夹。run() 方法中的代码是一行代码：


public void run(IAction action) {
     Program.launch("http://localhost:8081/help");

</td></tr></table>

当然，您可以将 URL 放到帮助库中。再进行一些努力，就可以在允许您指定地址的 Preferences 对话框中添加设置，这样就无需将它硬编码到插件中。但是，该主题最好留到构建修改 Preferences 对话框的插件的文章中进行讨论。

综合

创建了菜单插件之后，就可以将它附加到 Eclipse 主菜单栏中已外部化的 Infocenter 帮助中。图 11 显示了这个新菜单。

当单击这个菜单项时，它会启动 Infocenter 帮助，无论您在自己的计算机上配置了何种外部浏览器。图 12 显示了最后的结果。

好啦! 现在您已经有了一个外部帮助库，在这个库中，您可以开始整合整个应用程序开发小组的帮助系统。在逐渐习惯于使用这些现成的资源后，您会惊呀过去为什么没有使用它。

结束语

将本文讨论的所有知识点综合起来，会比学习各个的单独部分收获更大。您可以使用所有适当的插件帮助以及自己的内容为开发人员创建高度定制的帮助集。将公司的编码标准放在帮助中，并与其他参考资料放在一起不是很好码？

如果您在开发环境外创建了帮助，那么还可以将它用于在家中或远程客户端站点的开发人员。帮助环境成了一种无价的参考资料。事实上，帮助的外部化比供应商提供的静态信息分组要有用得多。您可以让帮助成为开发环境的一个动态的、有机的组成部分。

关于作者<table border="0" cellspacing="0" cellpadding="0" width="100%"><tr><td colspan="3"></td></tr><tr align="left" valign="top"><td>

</td><td></td><td width="100%">

Neal Ford 是 ThoughtWorks 的应用程序设计师，ThoughtWorks 是一个具有创新精神的 IT 专业服务公司，该公司利用世界各地极具天赋的人才为软件创造更高的价值。他还是应用程序、教学材料、杂志文章、课件、视频/DVD 演示文稿的设计者和开发者，还是 Developing with Delphi: Object-Oriented Techniques、JBuilder 3 Unleashed 和 Art of Java Web Development 的作者。他主要是构建大型企业应用程序方面的顾问。他还是国际知名演说家，在全球许多开发人员研讨会上做过演讲。他欢迎您提出反馈意见，他的联系方式是：nford@thoughtworks.com。

↑返回目录
前一篇: 使用 Eclipse 帮助系统为项目编制文档
后一篇: 将 Eclipse 导航文件转换为 DITA 导航文件