|
級別: 初級 |
軟件工程師, IBM
2005 年 6 月 13 日
當你應用設計模式時，你需要編寫關于如何應用和使用模式的文檔。設計模式的作者可以通過Eclipse在線幫助提供此類的文檔描述。本文描述模式作者如何為他們的模式建立文檔并把它作為IBM Rational Software Architect中的標準在線幫助中的一部分來顯示。
VBGX>介紹
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 的錨。所有的模式庫可以鏈接到這個錨，所以，所有的已安裝的模式都在相同的在線幫助集裝箱（或 javascript:tagshow(event, '%B9%A4%D7%F7');" href="javascript:;" target=_self>工作薄）中被一起顯示。結果是，所有的模式信息和相關的在線幫助在相同的位置被統一起來。
模式幫助內容文件
對于每個模式，有三個內容文件被建立，它們包含來自模式的 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 Architect Patterns 功能定義的錨點。如果你想要模仿生成的幫助的結構，你可以提供你的庫的幫助內容文件（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方面的工作經驗。 |
文章來源于領測軟件測試網 http://www.kjueaiud.com/
