使用Rational Software Architect

級別: 初級

Martha Andrews
軟件工程師, 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 目錄結構：

PatternFiles/ Pattern1/ Pattern1.emx Pattern1.rmd Pattern2/ Pattern2.emx Pattern2.rmd MyPatterns.rmd列表 1. PatternFiles 目錄結構

生成幫助文件
你可以從模式庫的關聯菜單啟動生成幫助文件命令（在Pattern Authoring View視圖中點擊右鍵），來為模式庫生成幫助。這將導致如下動作： 使用模式庫 RAS 描述符的信息生成一個 HTML 文件 為模式庫生成一個內容文件表 使用模式 RAS 描述符的信息為程序庫中的每個模式生成多個 HTML 文件 為每個模式生成一個內容文件表 在內容文件表中增加關于庫的 plugin.xml 的引用

在生成幫助之后，目錄 2顯示 MyPatterns 的 PatternFiles 部分的內容：

PatternFiles/ Pattern1/ Pattern1.em Pattern1.rmd PatternHelp/ Pattern1Description.html Pattern1Overview.html Pattern1Parameters.html Pattern1ToC.xml Pattern2/ Pattern2.emx Pattern2.rmd PatternHelp/ Pattern2Description.html Pattern2Overview.html Pattern2Parameters.html Pattern2ToC.xml PatternHelp/ MyPatterns.html MyPatternsToC.xml MyPatterns.rmd列表 2. PatternFiles 部分

正如你所見到的，生成幫助的過程建立了三個目錄和多個文件。文章接下來的部分將詳細解釋每一個生成的文件。

模式庫幫助內容文件
模式庫幫助內容文件是一個HTML 文件，它包含來自庫的 RAS 聲明文件的信息。在例子項目中，MyPatterns.rmd 是模式庫的 RAS 聲明文件。

模式庫幫助內容文件包含有一些信息，例如簡短說明，版本，程序庫的ID及庫中的模式列表。幫助內容文件存儲于PatternFiles目錄下的PatternHelp目錄中，并與庫具有相同的名字。在例子項目中，MyPatterns.html 是模式庫幫助文件。

原文轉自：http://www.anti-gravitydesign.com