距离我上次向dev2dev投稿已经很长时间了。我没有出现在这些页面上的原因是我一直忙于建立WebLogic Workshop 8.1的帮助系统。现在又开始重新撰写文章，我将为大家介绍一下这个帮助系统的一些内幕。

现在，也许您会认为IDE帮助系统方面的工作是不可见的，而且不是那种可供阅读的有趣内容。我承认一般情况下内部的东西确实是看不见的，但是Workshop帮助系统不只是为Workshop提供帮助，这个帮助系统是可扩展的。一旦知道了如何去扩展帮助系统，您就能在Workshop IDE中为自己、团队和客户迅速提高工作效率。

本文将对WebLogic Platform 8.1 SP2发布版本的帮助系统进行介绍。

为何要建立自定义帮助系统？

现在有大量的现成文档和帮助工具可供使用。在WebLogic Workshop（版本7.0）的第一个发布版本中，我们就使用了一个。那么，为什么要为8.1发布版本建立自定义系统呢？

原因是我们有一些非常特殊的需求。在我们所知的现成方案中，没有一个能满足这些需求。这些需求包括：

动态帮助内容
WebLogic Workshop 8.1引入了自定义Java控件，而SP2发布版本则引入了对IDE扩展的支持。您也可以添加自定义的JSP标签库和应用模板。我将把所有的扩展类型统称为“扩展”。

随着时间的过去，我们期望会有大量来自第三方的扩展可供使用。我们希望扩展的开发人员能够提供可以动态、无缝地集成到现有帮助系统的帮助内容。我们试用过的现成帮助工具只能生成静态的、“编译”的帮助系统，这些系统在提交给用户后很难修改。

全面的上下文敏感帮助
我们希望Workshop IDE的用户能通过IDE获取帮助。我们最终的目标是为IDE中所有可以选择的内容提供某种有用的F1帮助，这些内容包括用户可能一时兴起安装的扩展中的实体。

旁白：在8.1发布版本中，我们可能只实现了一半的目标。对于设计和源代码视图、属性编辑器中的所有内容，都能够使用F1获取到帮助，但是IDE本身的面板、对话框和IDE窗口部件（按钮等）仍然无法使用F1帮助。

轻松的帮助创作
我们希望扩展开发人员能够轻松地为他们的扩展创建帮助。尤其是我们不希望扩展帮助的作者使用任何特殊创作工具。

帮助系统体系结构

帮助系统由三个主要用户可见要素组成：

·         使用XML建立和描述的动态内容表（TOC）

·         帮助内容的集合（HTML文件）

·         全文搜索索引

随后的部分将就这些要素进行详细介绍。

除了用户可见要素，还有两个内部概念对于帮助系统的运作非常重要：

·         帮助路径。帮助路径是帮助内容位置的列表。位置可能是本地或者远程的，帮助路径中的条目或者是本地系统上的一个目录，或者是远端服务器上帮助内容的基准URL地址。

·         上下文标识符。帮助系统使用URN（通用资源名称）为上下文标识符定义了一个命名空间。上下文标识符指出了显示帮助的特定上下文。上下文标识符可以表示Java类、Javadoc标签、JSP标签或语言关键词。

在内部，我们需要区分那些准备帮助内容进行显示的Java代码和那些用于显示、允许用户浏览帮助内容的JavaScript代码。我们将Java代码称为帮助系统，而将JavaScript代码称为帮助查看器。

帮助路径
帮助路径包含帮助系统所知道的帮助内容位置列表。TOC和搜索索引都是使用帮助路径建立的，而上下文敏感（F1）帮助不是依靠帮助路径建立的。

帮助路径随着Workshop IDE的启动动态建立，用户也能从IDE属性对话框中进行修改。帮助路径由帮助组件组成。每一个帮助组件使用关联组件TOC代表一个帮助内容集合。

帮助路径组件包括：

·         所有通过extension.xml中的<help-root>元素标识的组件。extension.xml文件中包含了所有已安装的IDE扩展。IDE扩展超出了本文介绍的范围，但是即使是开箱即用的 Workshop IDE都包含多个扩展。这种机制用于配置随Workshop一起安装的核心帮助组件，包括Web服务、Java控件、页面流的所有文档（都在workshop组件中）；WebLogic Portal（portal组件）；WebLogic Integration （integration组件）；EJB项目（wls组件）；平台漫游（tour组件）；以及Extensibility Developer Kit （edk 组件）。.

·         Workshop帮助系统的合作伙伴目录中的所有厂商目录。进行第三方控件的安装时，其帮助将拷贝到合作伙伴目录。

·         用户添加的所有用户帮助目录。该功能使用户可以向系统添加任意的帮助内容，但这项功能是未记载且不被支持的功能。要使用该功能，在主目录中的.workshop.pref文件（Windows系统中的典型目录路径是C:/Documents and Settings/<username>/.workshop.pref）添加下面的黑体文本：

                 <preferences>

                  <components>

                   <component name="com.bea.ide.Application">

                    <node name="help">

                       <option name="help.userHelpDirs" value="<path>" />

                  </node>

<path>可以包含一个以上目录路径，不同路径使用分号隔开。

·         和WebLogic Server、WebLogic Integeration、WebLogic Portal相关联的BEA API的Javadoc集合的特殊路径组件。这些路径组件可以在IDE的帮助偏好中设置，例如，如果将一个或多个API的javadoc拷贝到本地机上，就可以设置IDE在本地查找这些帮助。

·         用于HTML标签帮助的特殊路径组件。该路径组件可以在IDE的帮助偏好中设置。

·         用于java.sun.com上J2SE和J2EE API javadoc的特殊路径组件。这些路径组件在IDE的帮助偏好中可以设置。

内容表的创建
TOC通过一个称为TOC合并的过程创建。 每个帮助组件的单独toc.xml文件合并到一个框架TOC中来生成最终的toc.xml文件，该框架在toc-master.xml文件中定义。然后最终的toc.xml文件使用XSL进行转换生成JavaScript文件，这些JavaScript文件用于在帮助查看器中管理和显示TOC。

toc-master.xml文件定义了顶层的"books"，其将存在于最终的TOC中。每一book由toc-master.xml文件中的<toc-anchor>元素代表。每个组件的toc.xml中的<toc-reference>元素是对toc-master.xml 文件中的<toc-anchor>元素进行引用。例如，toc-master.xml文件可能定义了元素<toc-anchor name="deployment" label="foo"/>，然后多个组件可以通过定义元素<toc-reference anchor="deployment" label="bar">定义主题，这些主题将会加入到Deployment book。TOC合并时，所有这些内容都会被收集和合并到最终TOC中的那部book中。

注意，尽管TOC合并操作和搜索索引操作都使用帮助路径查找内容，但它们是完全独立的。TOC合并操作不查看HTML文件，搜索索引操作不查看toc.xml文件。一些开发人员错误地认为这些过程是互相依赖的。

当额外的帮助内容随着第三方Java控件安装时，TOC会自动重新构建。也可以通过从IDE 的Help菜单中选择Rebuild Search Index来强制重建TOC（该操作将重建TOC和搜索索引）。

搜索索引
Workshop帮助系统使用来自Apache Jakarta 项目的Lucene搜索引擎。Lucene是一个灵活的、基于Java的全文搜索引擎。当WebLogic Workshop生成时，将会为所有的帮助内容生成搜索索引。

搜索查询通过Help Viewer的Search面板来执行。参阅下面的Help Viewer部分。

当额外的帮助内容和第三方Java控件一起安装时，搜索索引将会自动重建。也可以通过从IDE的Help菜单中选择Rebuild Search Index来强制重建搜索索引（该操作将重建TOC和搜索索引）。

上下文敏感帮助上下文标识符
如上所述，帮助系统的一个主要目标是提供完全的上下文敏感帮助。传统的访问上下文敏感帮助的方式是按F1功能键。按F1键将导致和用户当前上下文相关帮助内容的显示。在WebLogic Workshop的IDE中，“上下文”通常代表当前选择的实体。

IDE始终知道当前选择的实体是什么，但它需要一种方法来唯一确定每一个实体。Workshop通过将IDE中可以选择的实体分类，并与实体详情结合来建立一个自定义名称空间来实现这一点。一种特殊的结合方式称为上下文标识符。

Workshop将上下文标识符表示为URN（通用资源名称）。URN是URL（通用资源定位器）的堂兄弟，您可能已经从World Wide Web上对URL非常熟悉。但是，URN只是资源的一个唯一名字，并不像URL那样意味着一个特定的地址。URN字符串使用下面的形式：

urn:<schema>:<schema-specific-part>

Workshop IDE中大多数的实体可以分类为以下四种：Java类，Javadoc标签（Workshop-speak中的注解），JSP标签（包括HTML标签），或者语言关键词。在上下文标识符中，这四种分类分别使用schema名称java-class、javadoc-tag、taglib和keyword进行编码。

schema-specific部分是令人惊奇的，如下所述：

java-class上下文标识符
Java类上下文标识符的形式如下：

  urn:java-class:[.[.]*][[#fragment]]

schema-specific部分是Java完全限定的Java类名称，并使用可选的fragment来表示类的特定属性或方法。Java类上下文标识符有意地采用了与Javadoc文档的URL同样的格式。下面是一个Java类的URN的例子：

  urn:java-class:weblogic.jws.control.Context#setMaxAge(java.util.Date)

java-class URN也允许只包含一个包名称，而没有类名称（或fragment）。帮助系统会试图为指定的类查找一个名称为package-summary.html的文件。

javadoc-tag上下文标识符

Javadoc标签上下文标识符采用下面的形式：

  urn:javadoc-tag:[<prefix>.]<tagname>[#fragment]

schema-specific部分是一个放置在标签名称前面的标签前缀，并使用可选的fragment来表示标签的特定属性。下面是一个Javadoc标签URN的例子：

  urn:javadoc-tag:jws.conversation#phase

taglib上下文标识符和taglib（JSP标签)上下文标识符采用下面的形式：

  urn:taglib:<taglib-uri>/<tagname>

schema-specific部分是一个放置在标签名称前面的taglib URI。taglib URI是标签库的TLD文件中<uri>元素的值，其表示该标签库的唯一标识符。如果taglib URI包含协议规范（如http://），当组成上下文标识符URN时，其将被剥掉。下面是一个标签URN的例子：

  urn:taglib:www.bea.com/workshop/jsp-tags-html-1.0/html

这个URN表示Workshop页面流JSP页面中的<netui:html>标签。

关键词上下文标识符

关键词上下文标识符采用下面的形式：

  urn:keyword:<language>.<keyword>

schema-specific部分是放置在关键词前面的语言的名称。下面是一个标签URN的例子：

  urn:keyword:java.import

目录结构
WebLogic Workshop帮助系统安装在下面目录中：

/weblogic81b/workshop/help

help目录包含下面的结构：

help

  en

    core

    <other components>

    workshop

      guide

      <other conceptual content directories>

      java-class

      javadoc-tag

      keyword

      taglib

WebLogic Workshop的帮助系统将全部帮助内容分为两类：上下文敏感帮助主题和总体的帮助主题。上下文敏感主题指那些可以从IDE中通过F1键访问的帮助内容，它们倾向于包含一些参考资料。总体的帮助主体无法从IDE中通过F1键访问，它们倾向于包含特色和概念方面的背景资料。上下文敏感主题典型地包含指向相关总体主题的链接，反之亦然。

目录core包含HTML和JavaScript文件，这些文件用于协助帮助查看器的外观显示。

目录workshop表示一个帮助组件，该组件不属于那些组成整个帮助系统的组件。子目录guide代表总体帮助主题的集合。

子目录名称java-class、javadoc-tag、keyword和taglib是帮助系统必需的。注意这些子目录名称要和上面所说的上下文标识符schema名称相同。帮助组件不必包括所有这些子目录。例如，如果一个帮助组件不包括JSP标签参考主题，该组件就不需要子目录javadoc-tag。

这些目录下的目录结构也由帮助系统指定：对于一个给定的上下文标识符，帮助系统会用“/”替换上下文标识符URN中的所有“.”，并查找相关的文件路径。比如对于java-class上下文标识符，目录结构就正是Javadoc工具生成的结构。例如，给定上下文标识符URN：

  urn:java-class:weblogic.jws.control.Context#setMaxAge(java.util.Date)

帮助系统将为下面的文件在帮助路径中搜索条目。

  [java-class/]weblogic/jws/control/Context.html

（当帮助路径条目是远程路径时，如用于访问J2SE或J2EE Javadoc的http://java.sun.com/，java-class部分会被剥离掉。）

本地化
Workshop帮助系统支持国际化。帮助的作者可以提供本地化的帮助内容，当按下F1键时，帮助系统将试图定位本地化的帮助。

为了提供本地化的帮助内容，需要复制上面显示的目录结构。例如，为了提供日文帮助，要创建下面的结构：

help

  en

     <English content>

  ja

     <Japanese content>

IDE会在内部把帮助路径条目中的语言缩写词用记号替换。当按下F1键时，帮助系统总是首先尝试用本地语言替换记号，并分辨帮助主题。如果该主题不存在，帮助系统则会查找英文（en）的相应主题。

“本地语言”是java.util.Locale.getDefault().getLanguage()的返回值。

F1分辨
当用户在IDE中按下F1键时，IDE会执行以下步骤：

1. 从当前选择的实体确定当前的上下文。

2. 生成一个或多个代表上下文的上下文标识符URN。在许多情况下，IDE可能生成不只一个上下文标识符。这使得帮助系统可以定位最精确的可用帮助，但又可以在需要时使用稍微差一点的帮助。例如，如果选中SampleApp应用程序中的HellowWorld.jws的Hello方法，产生的上下文标识符如下：

urn:java-class:HelloWorld#Hello()

urn:java-class:com.bea.jws.WebService#Hello()

urn:java-class:java.lang.Object#Hello()

urn:java-class:HelloWorld#Hello

urn:java-class:com.bea.jws.WebService#Hello

urn:java-class:java.lang.Object#Hello

urn:java-class:HelloWorld

urn:java-class:com.bea.jws.WebService

urn:java-class:java.lang.Object

在有java方法的情况下，IDE生成的上下文标识符可以表示：带有参数的方法（对于对象类体系中的每一个类）、不带参数的方法、或只有类名称。

注意，如果某人（用户、用户团队成员、第三方开发人员等）已经建立了HelloWorld.html文件，并已经将其安装到了目录结构中合适的位置，用户将在HelloWorld 类上得到特定帮助。默认情况下，由于不存在这样的主题，用户会看到接口com.bea.jws.WebService的帮助。

同时要注意的是，帮助系统通过浏览整个层次体系来为继承的方法或属性定位帮助：其将在分辨到HelloWorld （不带#fragment）前先分辨到WebService#Hello（如果存在的话）。

3. 试图依靠帮助路径条目按顺序分辨上下文标识符。实际算法如下：

for each context ID URN

   for each help path entry

      if  (path-entry + context ID) exists

         done

某些合并路径缩短了。例如，Workshop使用专门的URI http://www.bea.com/workshop/jsp-tags-html-1.0/来识别标准的HTML标签。处理taglib上下文标识符时，IDE将识别这种模式并直接为HTML标签转向到帮助路径条目。对于java.*和javax.*包中的类的java-class上下文，也有类似的捷径。

如果IDE成功地依靠帮助路径条目分辨出上下文标识符，就会返回结果URL。

4. IDE使用浏览器打开分辨出的帮助URL。如果依靠帮助路径条目没有分辨出上下文标识符，将会显示默认帮助主题。

帮助查看器
帮助查看器是HTML文件和JavaScript代码的集合，这些文件和代码用于显示帮助内容，并允许用户浏览这些内容。所有这些组成帮助查看器的代码都可以在目录/workshop/help/doc/en/core中找到。

帮助查看器用三个主框架定义了一个框架集，这三个主框架是：横幅、导航面板和内容面板。横幅包含控制导航面板显示内容的按钮：内容表、搜索、书签（在未来版本中）。内容面板显示当前的帮助主题。

帮助主题通过导入或调用为帮助查看器提供功能的脚本来参与到帮助系统中。在每个帮助主题的开始处，您会看到下面的语句：

<head>

<title>The WebLogic Workshop Development Environment</title>

<link href="../workshop.css" rel="stylesheet" type="text/css">

<a href="../core/index.html" id="index"></a>

<script language="JavaScript" src="../core/topicInfo.js"></script>

<script language="JavaScript" src="../core/CookieClass.js"></script>

<script language="JavaScript" src="../core/displayContent.js"></script>

</head>

<title> 标签的值用于搜索结果中，并且在那个上下文中非常有用。

指向core/index.html和所有脚本文件（.js）的相对路径必须正确。根据一个特定主题在帮助内容中存在层次的深度，路径有明显的区别。

workshop.css是CSS样式表，它包含用于整个Workshop帮助内容的样式定义。如果您希望您的帮助在外观上和Workshop帮助内容一致，可以使用workshop.css中定义的样式。

脚本在每个主题中使用了指向core/index.html的<a>标签。该链接本身不被使用，但从一个特定主题调用脚本时，脚本将使用链接来确定当前的深度。

URL驱动

帮助查看器提供了一种我们称之为URL驱动的能力。我们之所以这样称它是因为您能简单地通过传递一个合适的URL给浏览器来“驱动”帮助查看器。WebLogic Workshop IDE使用该功能响应F1键并显示帮助主题。如下所述，使用URL浏览帮助主题会引起内容表和主题的同步。

帮助主题调用JavaScript完成URL驱动。如果检查Workshop的帮助主题，将会发现下面的代码紧跟在主题开放的<body> 标签后：

<script language="JavaScript">

   displayInFrames();

</script>

搜索
帮助查看器为帮助系统的全文搜索索引提供界面。搜索功能使用一个Java applet调用Lucene搜索引擎提交查询并返回结果。然后返回结果转换为HTML格式，并显示在搜索结果面板中。搜索结果按照相关的程度按顺序显示。

搜索结果的返回值是主题的<title>标签的值。每个主题必须有一个标题，当一次返回数十条结果时，标题就会对用户十分有用。例如，“示例”和“教程”都不是很有效的主题标题，因为它们可能会和许多其他与示例、教程相关的主题同时返回。

主题，反馈和版本信息

在帮助查看器中，您可以注意到每个主题底部都显示以下四项内容

·         “Feedback”链接。该链接使用mailto: URL调用用户默认电子邮件客户端来发送邮件。邮件的目的地址是可以定义的（参阅下面的介绍）。用户在阅读文档的过程中碰到错误或遗漏时，能利用这种链接立即提交反馈意见。

·         “Show in Table of Contents”链接。当通过点击搜索结果访问并查看主题时，该链接很有用。点击该链接将会把导航面板切换到内容表，并滚动到当前的主题。

·         “可移植的”主题URL。因为Workshop帮助查看器使用了框架集，浏览器地址栏中的URL总是框架集中顶端页面的地址（以core/index.html结束），当希望将一个特定的主题地址发送给其他人时，这个URL地址是没有用的。为了解决这个问题，我们在每个主题底部添加了一个“可移植的”URL，您可以将这个链接拷贝粘贴到电子邮件中来将其发送给接收者。您可以在每个主题底部、</body>标签前看到一个JavaScript调用writeTopicInfo()，该调用的部分工作就是创建这个链接。

每次Workshop有新版本发布时，就会在edocs.bea.com 上发布整个Workshop的帮助。因此对于Workshop的帮助，用作可移植链接的根URL总是位于edocs服务器上。但是，如果向帮助系统中添加帮助，并希望为存放在其他地方的某个版本帮助提供可移植URL，可以定制用于可移植链接的基准URL。请参阅下面的介绍。

·         版本字符串。为了在报告文档错误时区分文档版本，我们在每个主题的底部添加了一个版本字符串。这个版本字符串是一个采用YYYY.MMDD.HHMMSS格式的日期和时间字符串，它代表创建帮助内容的日期和时间。

定制反馈和可移植主题URL

反馈链接和可移植URL的基准URL由每个主题底部的JavaScript调用写到页面上。该功能的默认版本是writeTopicInfo()，它将使用默认的反馈电子邮件地址（wlw-doc-fb.com）和默认的可移植链接基准URL（http://edocs.bea.com/workshop/docs81/doc/）。

如果向帮助系统中添加帮助，可以通过调用writeCustomTopicInfo(customHelpURL, customFeedbackAddress) - 不是writeTopicInfo() - 定制反馈电子邮件地址、可移植基准URL、或者同时定制两者。customHelpURL应当指向存放帮助内容的web服务器的URL地址；customFeedbackAddress是希望接收帮助主题反馈内容的目的地址。

添加帮助

向帮助系统中添加帮助有两种方法：可以使用扩展（如自定义Java控件）提供帮助，或者在帮助路径中放置帮助。

第二种技术在为附加的类（如您的团队开发或购买的类库）添加javadoc时很有用。为了添加这种帮助，需要修改userHelpDirs属性，本文前面的部分曾经进行过介绍。

对于WebLogic Platform 8.1 SP2发布版本，F1键可以在所有BEA开发的Design Views和Source Views中使用（也就是对于JWS、JCS、JCX、JPF、JPD和入口文件）。您的安装中也可以包括第三方IDE扩展。在大多数情况下，第三方源代码编辑器应当继承基本Source View提供的功能。

F1键除了可以在变量、类或包名称、HTML或JSP标签的可视化表示上工作之外，也可以在这些实体上直接工作。在源代码视图中，F1也可以在Java语言关键词和Javadoc标签（也称为注解）上工作。在Property Editor的属性上，F1同样也可以工作，这些属性是Workshop Javadoc标签的可视化表示。

当然也可以使F1在更多Java类、关键词和JSP标签库上工作，相关内容请参阅前面的添加帮助部分。

将来的工作

我们对将来发布版本中的帮助系统有一个大计划。下面就是其中一些我们正在工作的内容。注意所有这些功能会随着产品设计过程改变，可能会、也可能不会出现在下面提到的版本中。

在线帮助
在WebLogic Platform 8.1 SP2发布版本中，所有帮助内容都通过产品安装过程安装到了您的机器上。在SP3发布版本中，我们计划采用在线帮助系统。帮助内容默认情况下将不会安装到您的机器上，相反，帮助内容会放置在BEA服务器上。这样就允许我们直接进行文档的更新和更正工作，而无需等待产品的发布。

我们也计划为离线帮助提供一个选项，从而可以将帮助内容下载到您的机器中，这样您就可以在没有Internet连接时也能访问帮助内容。

帮助查看器
历史和书签。如果您已经使用过Workshop帮助查看器，您可能已经注意到有两个有用的功能无法找到或无法正常工作：后退按钮和书签。我们正在进行这两个方面的工作。在下一个SP版本中，后退按钮将会如您预期地工作，而且也将会有一个全新的自定义书签功能。

基于服务器的帮助查看器。如果帮助查看器有时候看起来好像工作不正常，那是因为它不得不完全在浏览器中运行——没有服务器来实现全文搜索等逻辑。一旦我们转向了在线帮助，我们就能实现一个更加丰富、可定制的、使用服务器端功能的帮助查看器。特别是，我们开始显示出Page Flows和WebLogic Portal的能力了。

结束语

希望本文能帮助您理解WebLogic Workshop帮助系统的设计和运作。现在大部分的帮助系统已经完成了，可能我又可以定期向dev2dev投稿了。