用 JavaHelp 系统开发和交付更好的文档

  在线帮助系统是任何软件系统整体不可或缺的一部分。帮助系统可提供直观的帮助信息，使用户可以轻松的浏览、查找和显示帮助信息，同时有助于用户学习系统的使用，如此一来，许多应用程序的学习周期就大大缩短。然而，从传统上讲，由于 Java 语言中没有集成帮助系统，那么 Java 开发人员不得不从零开始创建自己定制的帮助系统。这样不仅成本高，而且费时。

  现在有了 JavaHelp 技术，Java 开发人员就不再需要为应用程序所运行的每个平台构建自己的帮助系统。JavaHelp 技术的目的是满足当今的工业强度的应用程序。

  本文将详细介绍如何使用 JavaHelp 系统来为您的软件系统提供更好的帮助信息。内容包括：

  帮助信息实现方法概述。

  JavaHelp 技术介绍。

  JavaHelp 技术的功能特点和优势的讨论。

  开发帮助信息所应用的风格。

  可用于您自己应用程序中的示例代码。

  帮助系统的可选方案

  Java 开发人员可用以下几种方案来实现其应用程序的帮助系统：

  无帮助系统：让用户自行判断和领会系统是如何工作的。然而，一个软系统如果没有文档、帮助信息系统、或者手册，那么该软件系统就是不完全的。而且还会影响到使用它的用户。设想一下没有使用手册的 Adobe Photoshop 会是什么一种情况！

  使用 HTML：这是一个低成本的选项，但是其功能和导航受到限制。

  自定义系统：这是一个高成本的选项，耗费资源和时间。

  第三方私有方案：这是一个可替代自定义系统的可行的方案；然而，它也有自己的后果，包括：成本和长期支持。如果软件供应商破产，你能做些什么呢？

  这就是为什么要设计 JavaHelp 技术的原因。

  JavaHelp 技术

  JavaHelp 是一个可扩展的、平台独立的帮助系统，可使作者和开发人员将在线帮助融合到applet、应用程序、操作系统和设备之中。它也可用来 Web 上和公司内部 Intranet 上传递在线文档。它的设计理念之一就是以网络为中心，帮助数据和搜索功能既可以在客户端，也可以在服务器端，同时帮助数据可以通过 Web 进行更新。

  JavaHelp 系统是用 Java 语言所写，因此可以运行在任何支持 Java Runtime Environment (JRE)的平台或者浏览器上。这说明，它可用于异构环境中，如 Web 或 公司内部 Intranet。此外，它还可以用来为任何软件应用程序开发和提供在线帮助，而不只是针对那些用 Java 语言开发而成的应用程序。而且，它也可以自我应用，而不需与任何软件相关联－－正如以 Web 为中心的分类文档（如人力资源、技术支持、等）的传输机制。

  JavaHelp 1.0 在 1999 年首次发布，经历了数年的发展和完善，该技术现在已经成熟。 JavaHelp 2.0 技术由 Java Community Process (JCP) 设计成 JSR-97。这说明和 WinHelp 不同，JavaHelp 具有 HTML 内容的跨平台优势，因为它并不将公司局限于单一的平台。请务必注意：JavaHelp 系统可以用来为部署在任何平台上的任何软件应用程序（而不仅仅是基于 Java 语言的应用程序）传递和提供在线帮助。

  JavaHelp 系统得到了来自行业和 JavaHelp/industry.html" />主要帮助写作工具供应商 的广泛支持。

  JavaHelp 的功能和优势

  JavaHelp 提供了几个对文档写作十分有用的功能。此外，它所提供的几个可重用的组件可为 Java 开发人员节省大量的时间。JavaHelp 的一些功能如下：

  帮助导航器：内容目录 (TOC) 支持以可折叠和可扩展的方式显示主题、无限分级、多目录合并；一个索引支持多索引合并；和具有灵活和可配置特性的全文检索。

  压缩：基于 JavaHelp 的帮助系统可以压缩并封装到一个单一的 Java Archive （JAR）文件中。

  可扩展和可定制： JavaHelp API 可用来定制或者扩展用户界面及其功能。 Extensions 可以自定义导航，甚至是语音和声音。这就使得作者在设计帮助系统时有更大的灵活性和控制力。

  上下文帮助：这是由 Swing 提供的。

  合并功能：在提供给用户之前可以对多个帮助组件进行合并。

  动态更新：许在线帮助系统在发布之后进行动态更新。

  适应性强：可使帮助系统适用于提供和显示信息。在最终部署环境事先未知的情况下，这将十分有用。

  可本地化：Java 支持国际化(I18N)，因此 JavaHelp 系统可以轻松进入国际市场。

  部署和操作情况

  JavaHelp 技术为作者和开发人员提供了几种在应用程序中部署或调用它的方法。由于它是以网络为中心的，所以它可以独立于它所支持的应用程序而运行。它甚至可以嵌入应用程序之中。并且由于它是用 Java 语言所写，因此它具有平台独立和浏览器独立的特点，可运行在任何支持Java Runtime Environment (JRE)的平台和浏览器上。这使得它成为当今异构计算环境中的理想的选择。

  这里是 JavaHelp 提供帮助信息的几种情况：

  独立应用程序：这是一个运行在桌面上的无需浏览器的本地应用程序。JavaHelp 帮助查看器可以作为一个单独的应用程序或者一个嵌入到该本地应用程序本身的应用程序而运行。

  网络应用程序：这些是网络应用程序，它们从远程服务器提取数据。JavaHelp 系统从远程服务器装载帮助信息是可能的。这对软件开发商来说十分有用，它们就可以为其客户提供轻量级的客户端应用程序，这些轻量级的应用程序从远程服务器提取帮助信息。软件供应商可以随意更改帮助信息，而不需要发布新的软件版本。

  Applets：运行于 web 浏览器中的小应用程序。JavaHelp 系统本身可以是浏览器的一部分，同时帮助数据可以是，也可以不是应用程序的一部分。

  基于服务器的应用程序：这是一个运行于 Java 服务器上的，但使用浏览器作为其 GUI 的应用程序。

  参考实现

  Sun Microsystems 提供一个参考实现 (JavaHelp System)，它将实现 JavaHelp 规范。它具有成熟、健壮和可靠的特点，并可供开发人员所使用。JavaHelp System 下载的地址是： JavaHelp/download_binary.html#download" />http://java.sun.com/products/JavaHelp/download_binary.html#download。其最新的版本是2.0_01.

  参考实现是以压缩文件的形式出现的，在选择的目录下对它进行解压缩就可以轻松的进行安装。 如果您选择 Windows 的 c:/ 作为其目的，它将被安装到 c:/jh2.0 下。

  参考实现附带有文档、工具和几个演示程序。二进制演示程序位于 c:/jh2.0/demos/bin， 用 java -jar demoName.jar 命令可以方便的运行这些演示程序。除了这些演示程序外，目录 c:/jh2.0/JavaHelp/bin 含有 jhindexer 和 jhsearch 工具，它们分别用来创建索引数据库和搜索的。最后，目录 c:/jh2.0/JavaHelp/lib 含有 JavaHelp API 的 JAR 文件，它们是：

  jh.jar: 使用标准导航器（目录、索引、全文检索）所需的标准库。

  jhbasic.jar:它是 jh.jar 的子集，不包含对全文搜索引擎的支持。对于那些大小很关键的帮助信息系统，或者不需要全文检索数据库的系统来说，这可能会十分有用。

  jhall.jar: 含有所有 JavaHelp 系统类，以及创建检索数据库所需的工具。

  jsearch.jar: 含有用于 JavaHelp 系统中的全文搜索引擎。

  JavaHelp 帮助查看器

  参考实现所附带的一个有趣的演示程序是帮助查看器（c:/jh2.0/demos/bin/hsviewer.jar），它是一个 helpset 查看器，可用来查看本文将要部署的帮助信息。值得注意的是它和 508 兼容。

  如图 1 所示的标准查看器是由一个工具栏（可用来显示多种按钮如 Back、Forward、Print，等等）和两个窗格所组成：

  内容窗格: 使用 HTML 和 frame 、表格和轻量级组件显示帮助主题

  导航窗格: 一个标签界面，用户可以在目录、索引和全文搜索显示模式之间进行切换。需要指出的是，导航器和内容查看器是同步的，所以用户总是知晓相对位置和选项。

  图 1：JavaHelp 标准查看器

  帮助信息写作

  为了用 JavaHelp 系统开发帮助信息，作者需要创建 JavaHelp 系统用来显示信息的元数据文件。此外，作者也需要创建供用户使用的主题。元数据和主题文件被称为 helpset。有一些帮助制作工具对这些 helpset 的创建进行了简化，但在本文中，我们将自己创建这些 helpset。

  创建 helpset 包含以下步骤：

  使用您所喜欢的编辑器创建 HTML 主题。

  创建一个 helpset 文件。

  创建一个 map 文件。

  创建一个目录。

  创建一个索引文件。

  创建一个全文检索数据库。

  将帮助文件压缩并封装到一个 JAR 文件中，以便提供给客户。

  注意：第 5 和第 6 步只有当您的帮助信息系统中集成有索引和全文检索数据库时才是必要的。

  要查看您的 helpset，helpset 查看器提供有参考实现（RI）。 helpset 查看器位于 c:/jh2.0/demos/bin/hsviewer.jar

  当查看器处于打开状态时，单击 "Browse" 来定位到一个 helpset (扩展名为 .hs)。 您也可以用以下方法进行查看：

  java -jar c:/jh2.0/demos/bin/hsviewer.jar -helpset c:/PathToMyHelpSet.hs

  帮助主题包含在文件中，这些文件在帮助查看器中一次显示一个，从这个意义上讲，Java Help 系统是基于文件的系统。相互关联的主题应该进行分组。最好用文件夹的分级结构来组织帮助主题。从一个主题到另一个主题的链接应该在含有该链接的文件中进行指定，且不能使用绝对路径。而且，您应该使用正斜杠 "/" 作为文件分隔符。举例如下：

  New Topic

  1. 创建 HTML 主题 实际的帮助信息是用 HTML 创建的； helpset 查看器能够解析并运行 HTML。您的 HTML 文件可以含有与其他文件以及图像的链接。示例代码 1 显示了 welcome.html 示例：

  注意：HTML 呈现引擎是一个 JRE 组件，且不是 JavaHelp 的一部分，因此呈现根据所用的 Java 的版本会有所变化。呈现引擎只显示 HTML 3.2 (带一些 4.0 版本的功能特点)。然而，它确实包含对 CSS1 样式表的支持。

  示例代码 1: welcome.html

  Help Overview

  This help system is organized into the following main

  topics. You can access these topics directly from the

  Help menu.

  Managing Projects

  How to create and use projects and

  portfolios

  Debugging Projects

  How to debug Java programs

  Profiling Projects

  How to analyze the performance of

  Java programs

  Some Copyright Information Goes Here!

  2. 创建 Helpset 文件

  helpset 文件是应用程序惟一显式引用的文件。JavaHelp 系统从该文件中抽取所有有关帮助系统的必要信息。 一旦 JavaHelp 系统被某个应用程序所激活，它会首先读取该 helpset 文件，该文件是组成帮助系统的一组数据，包含的信息如下：

  Map 文件: 用来联系主题 ID 和 URL 或 HTML 主题文件的路径名。

  查看信息: 描述用于 helpset 中的导航器。标准的导航器是： 目录、索引和全文检索。其他导航器包括词汇表和收藏导航器。

  Helpset 标题:

  Home ID: 当调用帮助查看器而不指定 ID 时所显示出的默认 ID 的名称。

  Presentation: 显示帮助主题的窗口。 标签用来定义用于 helpset 中的窗口。

  Sub-helpsets: 这是一个可选节，它包括 sub-helpset，该 sub-helpset 可以自动合并到包含它的 helpset 中。

  Implementation: 这是一个可选节，用来创建一个注册，它提供关键数据映射以定义 HelpBroker 类。

  示例代码 2 显示的是一个 helpset 文件 Sample.hs：

  示例代码 2: Sample.hs

  /p>

  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"

  "../dtd/helpset_2_0.dtd">

  top

  TOC

  javax.help.TOCView

  SampleTOC.xml

  Index

  javax.help.IndexView

  SampleIndex.xml

  Search

  javax.help.SearchView

  JavaHelpSearch

  main window

  toplevelfolder

  javax.help.BackAction

  javax.help.ForwardAction

  javax.help.SeparatorAction

  javax.help.HomeAction

  javax.help.ReloadAction

  javax.help.SeparatorAction

  javax.help.PrintAction

  javax.help.PrintSetupAction

  main

  正如您在示例代码 2 中所看到的，每个窗口都是由其自己的 标签所定义。 presentation 标签包括：

  : 命名窗口，使得 Java 程序可以通过名称对它进行调用。

  : 指定窗口尺寸（宽和高）的像素值。

  : 用横坐标(x)和纵坐标(y)指定窗口的位置。

  : 说明该窗口含有一个工具栏。 工具栏上的按钮的定义是这样的：每个动作都使用一个 标签，每个动作也都有一个 Java 类名。例如，代码: javax.help.PrintSetupAction定义了一个打印设置动作，因此用户就可以设置/选择打印机。

  3. 创建 Map 文件

  在读取 helpset 文件之后，JavaHelp 系统就会读取在 helpset 中所列出的 map 文件。map 文件使用 URL 将主题 ID 和 HTML 主题文件的路径联系起来。示例代码 3 显示了一个 map 文件示例：

  示例代码 3: Map.jhm

  /p>

  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"

  "http://java.sun.com/products/JavaHelp/map_1_0.dtd">

  4. 创建目录（TOC）文件

  目录文件描述了将显示在目录导航器中的目录以及目录的布局。目录文件的示例请参见示例代码 4。

  示例代码 4: SampleTOC.xml

  /p>

  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN"

  "../dtd/toc_2_0.dtd">

  presentationtype="javax.help.SecondaryWindow" presentationname="main"/>

  presentationtype="javax.help.Popup"/>

  示例目录的运行结果如图 2 所示。

  图 2: 目录示例

  5. 创建索引文件

  索引文件向索引导航器描述索引的内容和布局。示例代码 5 显示了一个索引文件的示例。

  示例代码 5: SampleIndex.xml

  /p>

  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"

  "http://java.sun.com/products/JavaHelp/index_1_0.dtd">

  target="proj.importdirectory"/>

  target="proj.existingbeans"/>

  target="proj.existingbeans"/>

  target="proj.existingbeans"/>

  示例索引文件运行结果见图 3。

  图 3: 索引文件示例

  眼见为实

  这时，您就可以查看以上所创建的帮助信息了。对它进行实验的最简单的方法就是按照以下的步骤：

  在 c:/ 下创建一个目录，名称可任取。为了演示方便，我将该目录称为 myhelp。

  将 Sample.hs、 map.jhm、 SampleTOC.xml、 SampleIndex.xml 拷贝至 myhelp 目录下

  在 myhelp 下创建一个子目录，叫做 help。

  将文件 welcome.html 拷贝至该子目录。

  运行如下命令 (helpset 查看器) 以查看以上创建的帮助信息。

  prompt> java -jar c:/jh2.0/demos/bin/hsviewer.jar -helpset c:/myhelp/Sample.hs

  如果一切正常，您将会看到类似图 4 的情况。

  图 4: 帮助信息示例

  如上所述，您可以将所有的帮助信息文件封装并压缩到一个 Java ARchive (JAR) 文件中。方法是：

  c:/myhelp> java -cvf help.jar *

  现在，您就可以用以下的命令查看帮助系统了：

  prompt> java -jar c:/jh2.0/demos/bin/hsviewer.jar -helpset c:/myhelp/help.jar

  创建全文搜索

  全文搜索引擎使用了自然语言搜索技术，它除了检索文档外，也可以定位到查询结构可能存在于其中的这些文档的特定段落。 它包括一个用于文档分析的概念性的索引引擎，以生成其内容的索引，它也包括一个查询引擎，该引擎使用索引在材料当中查找相关的段落。

  搜索数据库是用 jhindexer 命令创建而成的。这将在 JavaHelpSearch 目录下创建 6 个文件。这和其他的元数据文件位于同一个文件夹下。举个例子，假设您在该文件夹下有三个子目录叫做 "topic-a"、 "topic-b"和 "topic-c"。这些主题应该指定为 jhindexer 命令的参数：

  jhindexer topic-a topic-b topic-c

  当完成数据库的创建后，它将保存到 JavaHelpSearch 下。

  要验证它是一个有效的数据库，请运行如下命令：

  jhsearch JavaHelpSearch

  您将看到：

  initialized; enter query

  现在输入一个查询或者一个术语进行搜索，或者输入一个点（.）退出。

  将 JavaHelp 添加到应用程序中

  现在您已经为应用程序开发了一个帮助信息系统，那么接下来的问题很自然就是如何如何将该系统加入到您的应用程序当中。 将帮助信息系统集成到应用程序中所需代码的数量取决于您希望将该帮助信息系统作为应用程序的一部分，还是希望将该帮助信息系统作为另外一个独立的应用程序，例如，当单击帮助按钮时，就显示出该窗口。然而，在两种情况下，将 JavaHelp 添加到一个应用程序中就和下面的 1-2-3 一样容易:

  创建 HelpSet 和 HelpBroker 对象。

  将帮助赋给单个组件。

  为单个组件添加适当的帮助回调。

  示例代码 6 显示了如何将上面所开发的帮助信息系统添加到一个应用程序中，当选中帮助菜单项时，系统会显示出帮助信息窗口。作为一个练习，您可能希望对代码进行重新的设计，使其能够容易的集成到任何的应用程序当中。

  示例代码 6: HelpMenu.java

  import java.net.*;

  import javax.help.*;

  import javax.swing.*;

  import java.awt.event.*;

  public class HelpMenu {

  JFrame f;

  JMenuItem topics;

  public HelpMenu() {

  f = new JFrame("Menu Example");

  JMenuBar mbar = new JMenuBar();

  // a file menu

  JMenu file = new JMenu("File");

  JMenu help = new JMenu("Help");

  // add an item to the help menu

  help.add(topics = new JMenuItem("Help Topics"));

  // add the menu items to the menu bar

  mbar.add(file);

  mbar.add(help);

  // 1. create HelpSet and HelpBroker objects

  HelpSet hs = getHelpSet("sample.hs");

  HelpBroker hb = hs.createHelpBroker();

  // 2. assign help to components

  CSH.setHelpIDString(topics, "top");

  // 3. handle events

  topics.addActionListener(new CSH.DisplayHelpFromSource(hb));

  // attach menubar to frame, set its size, and make it visible

  f.setJMenuBar(mbar);

  f.setSize(500, 300);

  f.setVisible(true);

  }

  /**

  * find the helpset file and create a HelpSet object

  */

  public HelpSet getHelpSet(String helpsetfile) {

  HelpSet hs = null;

  ClassLoader cl = this.getClass().getClassLoader();

  try {

  URL hsURL = HelpSet.findHelpSet(cl, helpsetfile);

  hs = new HelpSet(null, hsURL);

  } catch(Exception ee) {

  System.out.println("HelpSet: "+ee.getMessage());

  System.out.println("HelpSet: "+ helpsetfile + " not found");

  }

  return hs;

  }

  public static void main(String argv[]) {

  new HelpMenu();

  }

  }

  实验该代码的最简单的方法是将 HelpMenu.java 拷贝至 c:/myhelp下。编译并运行它。如果一切正常，您会看到类似图 5 的情况。如果单击帮助主题（ Help Topics）， 那么就会出现图 4 中的帮助信息窗口。

  图 5: 单击帮助主题以调用 helpset 查看器

  基于服务器的帮助

  JavaHelp 2.0 的一个新的功能特点是基于服务器的帮助（ server-based help）。这是一个重要的功能，可使 JavaHelp 在浏览器窗口为基于 web 的应用程序提供帮助信息。使用新的 JavaHelp JST 标签库，可以很容易的将帮助信息添加到基于 web 的应用程序中。工作流程是：当浏览器发出一个 JSP 请求，Java 服务器将该请求转换成一个 Java Servlet，它使用 JavaHelp 库（jh.jar）和 JavaHelp 标签库（jhtags.jar）中的类从 helpset 中访问适当的信息，并向浏览器返回 HTML，也可能是 JavaScript 或者动态 HTML。图 6 显示的是一个基于 Web 的应用程序的帮助信息示例。

  图 6：基于服务器的帮助

  单击放大

  要了解有关基于服务器的帮助的更多信息，请参考：JavaHelp 2.0 规范。

  结束语

  JavaHelp API 是需要运行于异构环境当中的在线帮助信息系统之作者和开发人员的首选技术。JavaHelp 系统可为开发人员增值，并提供完整的软件应用程序，同时无需对编程和开发进行大量投资。此外，许多公司已经认可了 JavaHelp 系统，并计划使用该 API 来建立统一的界面，以进行显示和在内部和外部文档间导航。

  本文中的示例代码描述了如何创建帮助信息文档，这些文档可以很容易的集成到新的和现有的应用程序当中。