用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 系统是基于文件的系统。相互关联的主题应该进行分组。最好用文件夹的分级结构来组织帮助主题。从一个主题到另一个主题的链接应该在含有该链接的文件中进行指定，且不能使用绝对路径。而且，您应该使用正斜杠  "/" 作为文件分隔符。举例如下：

＜a href="../subtopicC/topic.html"＞New Topic＜/a＞

　　1. 创建 HTML 主题 

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

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

　　示例代码 1: welcome.html

＜!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"＞   
＜HTML＞   
＜HEAD＞   
＜TITLE＞   
Help Overview   
＜/TITLE＞   
＜/HEAD＞   
＜BODY BGCOLOR="#ffffff"＞   
＜H1＞My Sample Online Help＜/H1＞   
This help system is organized into the following main   
＜br＞   
topics. You can access these topics directly from the     
＜br＞   
Help menu.   
＜p＞   
＜table width=98% border=0 cellpadding=5＞   
＜tr valign="top"＞   
＜td width=30%＞＜A HREF="manager.html"＞Managing Projects＜/A＞   
＜/td＞   
＜td width=70%＞   
How to create and use projects and   
＜br＞portfolios   
＜/td＞   
＜/tr＞   
＜tr valign="top"＞   
＜td width=30%＞＜A HREF="debug.html"＞Debugging Projects＜/A＞   
＜/td＞   
＜td width=70%＞   
How to debug Java programs   
＜/td＞   
＜/tr＞   
＜tr valign="top"＞   
＜td width=30%＞＜A HREF="profile.html"＞Profiling Projects＜/A＞   
＜/td＞   
＜td width=70%＞   
How to analyze the performance of   
＜br＞   
Java programs   
＜/td＞   
＜/tr＞   
＜/table＞   
＜/ul＞   
＜hr＞   
＜pre＞   
＜font size="-1"＞   
Some Copyright Information Goes Here!   
＜/font＞   
＜/pre＞   
＜hr＞   
＜/BODY＞   
＜/HTML＞   

　　2. 创建 Helpset 文件

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

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

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

　　·Helpset 标题: ＜title＞ 是在 helpset 文件中定义的，它显示在主窗口和任何在 helpset 文件中所定义的子窗口的顶部。

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

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

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

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

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

　　示例代码 2: Sample.hs

＜?xml version='1.0' encoding='ISO-8859-1' ?＞   
＜!DOCTYPE helpset   
  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"   
         "../dtd/helpset_2_0.dtd"＞   

＜helpset version="1.0"＞   

  ＜!-- title --＞   
  ＜title＞My Sample Help - Online＜/title＞   

  ＜!-- maps --＞   
  ＜maps＞   
     ＜homeID＞top＜/homeID＞   
     ＜mapref location="Map.jhm"/＞   
  ＜/maps＞   

  ＜!-- views --＞   
  ＜view＞   
    ＜name＞TOC＜/name＞   
    ＜label＞Table Of Contents＜/label＞   
    ＜type＞javax.help.TOCView＜/type＞   
    ＜data＞SampleTOC.xml＜/data＞   
  ＜/view＞   

  ＜view＞   
    ＜name＞Index＜/name＞   
    ＜label＞Index＜/label＞   
    ＜type＞javax.help.IndexView＜/type＞   
    ＜data＞SampleIndex.xml＜/data＞   
  ＜/view＞   

  ＜view＞   
    ＜name＞Search＜/name＞   
    ＜label＞Search＜/label＞   
    ＜type＞javax.help.SearchView＜/type＞   
    ＜data engine="com.sun.java.help.search.DefaultSearchEngine"＞   
      JavaHelpSearch   
    ＜/data＞   
  ＜/view＞   

  ＜presentation default="true" displayviewimages="false"＞   
     ＜name＞main window＜/name＞   
     ＜size width="700" height="400" /＞   
     ＜location x="200" y="200" /＞   
     ＜title＞My Sample Help - Online＜/title＞   
     ＜image＞toplevelfolder＜/image＞   

     ＜toolbar＞   
 ＜helpaction＞javax.help.BackAction＜/helpaction＞   
 ＜helpaction＞javax.help.ForwardAction＜/helpaction＞   
 ＜helpaction＞javax.help.SeparatorAction＜/helpaction＞   
 ＜helpaction＞javax.help.HomeAction＜/helpaction＞   
 ＜helpaction＞javax.help.ReloadAction＜/helpaction＞   
 ＜helpaction＞javax.help.SeparatorAction＜/helpaction＞   
 ＜helpaction＞javax.help.PrintAction＜/helpaction＞   
 ＜helpaction＞javax.help.PrintSetupAction＜/helpaction＞   
     ＜/toolbar＞   

  ＜/presentation＞   

  ＜presentation＞   
     ＜name＞main＜/name＞   
     ＜size width="400" height="400" /＞   
     ＜location x="200" y="200" /＞   
     ＜title＞My Sample Help - Online＜/title＞   
  ＜/presentation＞   

＜/helpset＞

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

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

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

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

　　·＜title＞: 定义显示在窗口上部标题栏中的文本。

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