级别: 初级 |
软件工程师, IBM
2005 年 6 月 13 日
当你应用设计模式时，你需要编写关于如何应用和使用模式的文档。设计模式的作者可以通过Eclipse在线帮助提供此类的文档描述。本文描述模式作者如何为他们的模式建立文档并把它作为IBM Rational Software Architect中的标准在线帮助中的一部分来显示。
介绍
IBM Rational Software Architect允许你为创建的模式生成帮助。这篇文章说明帮助生成功能，你可以使用该功能在Rational Software Architect的在线帮助里添加关于模式的文档。除此之外，本文还概述了在不使用帮助生成功能的情况下，添加文档的步骤。
本文提供给那些使用Rational Software Architect来建立模式库的Java 开发者。如果你对Eclipse 的在线帮助系统和帮助锚非常熟悉，它将对你有益。关于Rational Software Architect中的设计模式的信息，在产品中提供的在线帮助中可以查到。关于使用帮助系统开发在线帮助插件及使用锚，你可能从《Help -- Part 1: Contributing a Little Help (Revised for 2.0)》一文中找到有用的资料，它列于本文后面的资源一节中。
本文提及Reusable Asset Specification（RAS），它为模式和模式程序库提供了一个标准的结构和组织。关于 RAS 和模式的更多信息，见Rational Software Architect在线帮助。
MyPatterns 项目
为了帮助描述在线帮助中的目录结构和生成的文件，本文引用一个项目实例。该项目是一个包含二个模式：Pattern1 和 Pattern2的模式库。每个模式有一个参数。
本文把重心集中在 PatternFiles 目录树中的文件。这些文件在模式设计期间，在包浏览器视图中是可见的。列表1显示，紧随项目的建立及模式添加之后的PatternFiles 目录结构：
|
生成帮助文件
你可以从模式库的关联菜单启动生成帮助文件命令（在Pattern Authoring View视图中点击右键），来为模式库生成帮助。这将导致如下动作：
- 使用模式库 RAS 描述符的信息生成一个 HTML 文件
- 为模式库生成一个内容文件表
- 使用模式 RAS 描述符的信息为程序库中的每个模式生成多个 HTML 文件
- 为每个模式生成一个内容文件表
- 在内容文件表中增加关于库的 plugin.xml 的引用
在生成帮助之后，目录 2显示 MyPatterns 的 PatternFiles 部分的内容：
|
正如你所见到的，生成帮助的过程建立了三个目录和多个文件。文章接下来的部分将详细解释每一个生成的文件。
模式库帮助内容文件
模式库帮助内容文件是一个HTML 文件，它包含来自库的 RAS 声明文件的信息。在例子项目中，MyPatterns.rmd 是模式库的 RAS 声明文件。
模式库帮助内容文件包含有一些信息，例如简短说明，版本，程序库的ID及库中的模式列表。帮助内容文件存储于PatternFiles目录下的PatternHelp目录中，并与库具有相同的名字。在例子项目中，MyPatterns.html 是模式库帮助文件。
模式库内容文件表
模式库内容文件表是一个以Eclipse中的 toc 格式存储的XML文件。该文件提供三种服务：
- 它链接库的生成帮助文件到Rational Software Architect Pattern的在线帮助
- 它为库描述帮助主题
- 它提供一个锚，以便在库中的模式可以插入帮助
模式库内容文件表储存在 PatternHelp 目录中，而且它以模式的名字附加上 ToC.xml 作为名字。在你的例子项目中，模式库内容文件表是 MyPatternsToC.xml 。
因为目录表如此重要，让我们更深入地探讨。列表 3显示 MyPatternsToC.xml 文件的内容：
|
生成的模式库的内容文件表规定了一个为模式库命名的主题。模工库主题指向生成的模式库帮助内容文件。在模式库主题里面，目录表定义了它自己的锚点。
toc 元素包含一个链接属性。该属性在Rational Software Architect中的模式功能帮助下面显示MyPatterns 库的帮助。模式的在线帮助提供一个在标准在线帮助toc文件中称为morePatterns的锚。所有的模式库可以链接到这个锚，所以，所有的已安装的模式都在相同的在线帮助集装箱（或工作薄）中被一起显示。结果是，所有的模式信息和相关的在线帮助在相同的位置被统一起来。
模式帮助内容文件
对于每个模式，有三个内容文件被建立，它们包含来自模式的 RAS 的声明文件的信息。关于模式的 RAS 声明是在以模式命名的目录中，包含关于模式和参数的信息。在例子项目中，Pattern1.rmd 和 Pattern2.rmd 是关于 Pattern1 和 Pattern2 RAS 的声明文件。
所有的内容文件都可以在以模式命名的目录下的 PatternHelp 目录中找到。下面是关于这些文件的一个简短描述：
- 概览内容文件：这一文件包括关于模式的一般信息，如简短描述，版本，作者和模式所属的组列表。当模式应用者在模式浏览器或应用模式向导中触发Show Pattern Documentation命令时，概览文件被显示出来。它的文件名是在模式名后面附加 Overview.html 。在例子项目中，Pattern1Overview.html 和 Pattern2Overview.html 分别是 Pattern1 和 Pattern2 的概览文件。
- 描述内容文件：该文件允许你提供如何应用模式的细节描述。如果你没有使用模式作者视图中的Import Description File相关菜单引入描述，该页将只包含模式的名称。该文件的名字通过在模式名后附加 Description.html 生成。在例子项目中，Pattern1Description.html 和 Pattern2Description.html 是描述文件。
- 参数内容文件：该文件包含关于模式参数的信息。文件被分成几部分，每部分说明一个参数。每个部分均包含类型，可见性，多样性，ID 和参数描述。如果你没有使用Import Description File相关菜单命令来导入描述，描述区域将是空白的。该文件通过在模式名后增加 Parameters.html 命名。在例子项目中，参数内容文件是 Pattern1Parameters.html 和 Pattern2Parameters.html 。
模式内容文件表
模式内容文件表是一个XML文件，它符合Eclipse中的 toc 文件格式。该文件链接到在模式库内容文件表中定义的锚。它包含为模式命名的标题，就如在前一节中描述的三个帮助内容文件。
让我们看看 Pattern1 的目录表，你会发现主题是如何被安排的。列表 4显示 Pattern1ToC.xml 文件的内容：
|
注意，toc 元素包含一个向后链接属性，它指向在模式库目录表中定义的锚点。因此，Pattern1 的帮助是嵌在Eclipse 帮助系统的模式库预定中。
在plugin.xml 中引用内容文件表
为模式库插入的 plugin.xml 文件必须为每个模式内容文件表包含 toc 元素。每当生成内容文件表时，帮助生成过程增加 toc 元素。
手动整合在线帮助
如果你不喜欢使用自动帮助生成，你可以提供帮助文件并且链接到Patterns Help锚，这样在线帮助中将出现与自动生成文件一样的目录表部分。本节描述链接你的模式帮助到Rational Software Architect的模式在线帮助的步骤。
本节引用 MyPatterns 例子项目。为了回顾一下，列表 5显示在加入帮助前的PatternFiles 目录树：
|
下面的步骤描述如何把目录和文件加入项目，以便使帮助对于 Pattern1是可用的。
应用你的模式的任何人都可以通过在模式浏览器选择特定模式并从相关菜单中选择Show Pattern Documentation来获得它的帮助。模式用户界面开启在线帮助，与在内容面板表中所选择的模式主题一起，显示关于模式的概览页面。
为了在不使用内建的帮助生成器的情况下提供这一能力，你必须提供一个以模式名附加Overview.html结尾的文件，以便应用程序界面可以显示帮助。这一文件必须在预期的目录结构中：一个以模式命名的目录，一个名为PatternHelp的子目录。为了使你的模式成为在线帮助窗囗的目录表的一部分，你必须链接到模式帮助提供的锚。
按照这些步骤嵌入帮助：
- 创建一个作为你的模式帮助主页的 HTML 文件。这个文件应该以模式名来命名，并附加上Overview.html。
- 把该页放在上面描述的目录结结构中：一个以模式名命名的目录中的PatternHelp子目录。
- 建立一个具有
链接属性的XML toc文件指向 /com.ibm.xtools.pttrn.user.doc/applypattern_TOC.xml#morePatterns。 - 增加你想要包括的任何主题的主题元素到XML toc 文件。确定包括了你在第 1 步中创建的主题概览文件。
- 增加内容文件表的引用到你的 plugin.xml 文件。你可以通过Eclipse打开 plugin.xml 文件，单击Extensions标签，选择org.eclipse.help.toc扩展，并使用关联菜单来增加一个新的 toc 元素。
在接着为为Pattern1提供了帮助后，MyPatterns 例子项目看起来象在列表 6 中显示的那样：
|
MyTableOfContents.xml 文件看起来应该象列表 7 这样：
|
在Eclipse Help目录表中的 Pattern1 主题列表将与具用帮助生成功能的库列表在同一级别出现。这是因为链接属性指向由Rational Software ArchitectPatterns功能定义的锚点。如果你想要模仿生成的帮助的结构，你可以提供你的库的帮助内容文件（HTML），并命名用链接属性把它放到模式功能帮助中。然后，你可以使用标准的Eclipse帮助toc结构在你的库主题下，为你的模式定义主题。
为了测试你的帮助，运行Rational Software Architect的调试工作台。在模式浏览器视图中右键点击你的模式，并选择Show Pattern Documentation。一个Eclipse Help窗囗将与你的文件一块右边面板中打开，同时你的文件的主题将在左边面板中被选择。如果文件在右边出现，但是左边的主题并未被选择，可能是你的目录文件表存在问题。如果你见到模式没有帮助的信息，这意味模式用户界面无法找你的概览文件；检查你已经在预期的目录中建立它并且把它命名为先前第 1 步所描述的名字。
结论
本文描述了你可以如何为模式和模式库生成在线帮助，及生成的帮助是如何与标准的在线帮助相连接。然后，它显示了你如何通过定义一个类似的结构来为模式提供你自己的帮助目录。
- 您可以参阅本文在 developerWorks 全球站点上的英文原文。
- Help -- Part 1: Contributing a Little Help (Revised for 2.0)一文提供关于开发在线帮助插件及在帮助系统中使用锚的信息。
- 从Trials and betas可以获得Rational Software Architect的评价版本。
- 关于Rational产品的更多技术资源，请访问developerWorks 中国网站 Rational 专区。你将会找到技术文档、教程、下载、产品信息及更多的其他信息。关于Rational Software Architect的特定信息，请访问RSA 技术资源页面。
- 可以通过访问Rational Software Architect的产品页获得更多与产品有关的信息。
- 关于Eclipse 3.0 平台的细节及更多信息，请访问Eclipse 主页。
- 通过参与developerWorks blogs获得有关developerWorks的交流。
- 在the Rational Software Architect, Software Modeler, Application Developer and Web Developer forum提出与Rational Software Architect相关的问题。
- 在Developer Bookstore 的 Rational 部分可以买到打折的Rational书籍。
- 请一定细读 Rational Software Architect 中的帮助页。这些页的面提供大量的信息，包括多媒体导航和演示。
| 关于作者 Martha Andrews是在Rational Architect中关于模式用户界面方面软件工程师。她有绝大多数Rational 工具和Eclipse方面的工作经验。 |
