用JavaHelp系統開發和交付更好的文檔
在線幫助系統是任何軟件系統整體不可或缺的一部分。幫助系統可提供直觀的幫助信息，使用戶可以輕松的瀏覽、查找和顯示幫助信息，同時有助于用戶學習系統的使用，如此一來，許多應用程序的學習周期就大大縮短。然而，從傳統上講，由于 Java 語言中沒有集成幫助系統，那么 Java 開發人員不得不從零開始創建自己定制的幫助系統。這樣不僅成本高，而且費時。
現在有了 JavaHelp 技術，Java 開發人員就不再需要為應用程序所運行的每個平臺構建自己的幫助系統。JavaHelp 技術的目的是滿足當今的工業強度的應用程序。
本文將詳細介紹如何使用 JavaHelp 系統來為您的軟件系統提供更好的幫助信息。內容包括：
·幫助信息實現方法概述。
·JavaHelp 技術介紹。
·JavaHelp 技術的功能特點和優勢的討論。
·開發幫助信息所應用的風格。
·可用于您自己應用程序中的示例代碼。
幫助系統的可選方案
Java 開發人員可用以下幾種方案來實現其應用程序的幫助系統：
·無幫助系統：讓用戶自行判斷和領會系統是如何工作的。然而，一個軟系統如果沒有文檔、幫助信息系統、或者手冊，那么該軟件系統就是不完全的。而且還會影響到使用它的用戶。設想一下沒有使用手冊的 Adobe Photoshop 會是什么一種情況！
·使用 HTML：這是一個低成本的選項，但是其功能和導航受到限制。
·自定義系統：這是一個高成本的選項，耗費資源和時間。
·第三方私有方案：這是一個可替代自定義系統的可行的方案；然而，它也有自己的后果，包括：成本和長期支持。如果軟件供應商破產，你能做些什么呢？
這就是為什么要設計 JavaHelp 技術的原因。
JavaHelp 技術
JavaHelp 是一個可擴展的、平臺獨立的幫助系統，可使作者和開發人員將在線幫助融合到applet、應用程序、操作系統和設備之中。它也可用來 Web 上和公司內部 Intranet 上傳遞在線文檔。它的設計理念之一就是以網絡為中心，幫助數據和搜索功能既可以在客戶端，也可以在服務器端，同時幫助數據可以通過 Web 進行更新。
JavaHelp 系統是用 Java 語言所寫，因此可以運行在任何支持 Java Runtime Environment (JRE)的平臺或者瀏覽器上。這說明，它可用于異構環境中，如 Web 或 公司內部 Intranet。此外，它還可以用來為任何軟件應用程序開發和提供在線幫助，而不只是針對那些用 Java 語言開發而成的應用程序。而且，它也可以自我應用，而不需與任何軟件相關聯－－正如以 Web 為中心的分類文檔（如人力資源、技術支持、等）的傳輸機制。
JavaHelp 1.0 在 1999 年首次發布，經歷了數年的發展和完善，該技術現在已經成熟。 JavaHelp 2.0 技術由 Java Community Process (JCP) 設計成 JSR-97。這說明和 WinHelp 不同，JavaHelp 具有 HTML 內容的跨平臺優勢，因為它并不將公司局限于單一的平臺。請務必注意：JavaHelp 系統可以用來為部署在任何平臺上的任何軟件應用程序（而不僅僅是基于 Java 語言的應用程序）傳遞和提供在線幫助。
JavaHelp 系統得到了來自行業和 主要幫助寫作工具供應商 的廣泛支持。
JavaHelp 的功能和優勢
JavaHelp 提供了幾個對文檔寫作十分有用的功能。此外，它所提供的幾個可重用的組件可為 Java 開發人員節省大量的時間。JavaHelp 的一些功能如下：
·幫助導航器：內容目錄 (TOC) 支持以可折疊和可擴展的方式顯示主題、無限分級、多目錄合并；一個索引支持多索引合并；和具有靈活和可配置特性的全文檢索。
·壓縮：基于 JavaHelp 的幫助系統可以壓縮并封裝到一個單一的 Java Archive （JAR）文件中。
·可擴展和可定制： JavaHelp API 可用來定制或者擴展用戶界面及其功能。 Extensions 可以自定義導航，甚至是語音和聲音。這就使得作者在設計幫助系統時有更大的靈活性和控制力。
·上下文幫助：這是由 Swing 提供的。
·合并功能：在提供給用戶之前可以對多個幫助組件進行合并。
·動態更新：許在線幫助系統在發布之后進行動態更新。
·適應性強：可使幫助系統適用于提供和顯示信息。在最終部署環境事先未知的情況下，這將十分有用。
·可本地化：Java 支持國際化(I18N)，因此 JavaHelp 系統可以輕松進入國際市場。
部署和操作情況
JavaHelp 技術為作者和開發人員提供了幾種在應用程序中部署或調用它的方法。由于它是以網絡為中心的，所以它可以獨立于它所支持的應用程序而運行。它甚至可以嵌入應用程序之中。并且由于它是用 Java 語言所寫，因此它具有平臺獨立和瀏覽器獨立的特點，可運行在任何支持Java Runtime Environment (JRE)的平臺和瀏覽器上。這使得它成為當今異構計算環境中的理想的選擇。
這里是 JavaHelp 提供幫助信息的幾種情況：
·獨立應用程序：這是一個運行在桌面上的無需瀏覽器的本地應用程序。JavaHelp 幫助查看器可以作為一個單獨的應用程序或者一個嵌入到該本地應用程序本身的應用程序而運行。
·網絡應用程序：這些是網絡應用程序，它們從遠程服務器提取數據。JavaHelp 系統從遠程服務器裝載幫助信息是可能的。這對軟件開發商來說十分有用，它們就可以為其客戶提供輕量級的客戶端應用程序，這些輕量級的應用程序從遠程服務器提取幫助信息。軟件供應商可以隨意更改幫助信息，而不需要發布新的軟件版本。
·Applets：運行于 web 瀏覽器中的小應用程序。JavaHelp 系統本身可以是瀏覽器的一部分，同時幫助數據可以是，也可以不是應用程序的一部分。
·基于服務器的應用程序：這是一個運行于 Java 服務器上的，但使用瀏覽器作為其 GUI 的應用程序。
參考實現
Sun Microsystems 提供一個參考實現 (JavaHelp System)，它將實現 JavaHelp 規范。它具有成熟、健壯和可靠的特點，并可供開發人員所使用。JavaHelp System 下載的地址是： http://java.sun.com/products/javahelp。其最新的版本是2.0_01.
參考實現是以壓縮文件的形式出現的，在選擇的目錄下對它進行解壓縮就可以輕松的進行安裝。 如果您選擇 Windows 的 c: 作為其目的，它將被安裝到 c:jh2.0 下。
參考實現附帶有文檔、工具和幾個演示程序。二進制演示程序位于 c:jh2.0demosin， 用 java -jar demoName.jar 命令可以方便的運行這些演示程序。除了這些演示程序外，目錄 c:jh2.0javahelpin 含有 jhindexer 和 jhsearch 工具，它們分別用來創建索引數據庫和搜索的。最后，目錄 c:jh2.0javahelplib 含有 JavaHelp API 的 JAR 文件，它們是：
·jh.jar: 使用標準導航器（目錄、索引、全文檢索）所需的標準庫。
·jhbasic.jar: 它是 jh.jar 的子集，不包含對全文搜索引擎的支持。對于那些大小很關鍵的幫助信息系統，或者不需要全文檢索數據庫的系統來說，這可能會十分有用。
·jhall.jar: 含有所有 JavaHelp 系統類，以及創建檢索數據庫所需的工具。
·jsearch.jar: 含有用于 JavaHelp 系統中的全文搜索引擎。
JavaHelp 幫助查看器
參考實現所附帶的一個有趣的演示程序是幫助查看器（c:jh2.0demosinhsviewer.jar），它是一個 helpset 查看器，可用來查看本文將要部署的幫助信息。值得注意的是它和 508 兼容。
如圖 1 所示的標準查看器是由一個工具欄（可用來顯示多種按鈕如 Back、Forward、Print，等等）和兩個窗格所組成：
·內容窗格: 使用 HTML 和 frame 、表格和輕量級組件顯示幫助主題
·導航窗格: 一個標簽界面，用戶可以在目錄、索引和全文搜索顯示模式之間進行切換。需要指出的是，導航器和內容查看器是同步的，所以用戶總是知曉相對位置和選項。
幫助信息寫作
為了用 JavaHelp 系統開發幫助信息，作者需要創建 JavaHelp 系統用來顯示信息的元數據文件。此外，作者也需要創建供用戶使用的主題。元數據和主題文件被稱為 helpset。有一些幫助制作工具對這些 helpset 的創建進行了簡化，但在本文中，我們將自己創建這些 helpset。
創建 helpset 包含以下步驟：
·使用您所喜歡的編輯器創建 HTML 主題。
·創建一個 helpset 文件。
·創建一個 map 文件。
·創建一個目錄。
·創建一個索引文件。
·創建一個全文檢索數據庫。
·將幫助文件壓縮并封裝到一個 JAR 文件中，以便提供給客戶。
注意：第 5 和第 6 步只有當您的幫助信息系統中集成有索引和全文檢索數據庫時才是必要的。
要查看您的 helpset，helpset 查看器提供有參考實現（RI）。 helpset 查看器位于 c:jh2.0demosinhsviewer.jar
當查看器處于打開狀態時，單擊 "Browse" 來定位到一個 helpset (擴展名為 .hs)。 您也可以用以下方法進行查看：
java -jar c:jh2.0demosinhsviewer.jar -helpset c:PathToMyHelpSet.hs
幫助主題包含在文件中，這些文件在幫助查看器中一次顯示一個，從這個意義上講，Java Help 系統是基于文件的系統。相互關聯的主題應該進行分組。最好用文件夾的分級結構來組織幫助主題。從一個主題到另一個主題的鏈接應該在含有該鏈接的文件中進行指定，且不能使用絕對路徑。而且，您應該使用正斜杠 "/" 作為文件分隔符。舉例如下：
＜a href="http://www.zhujiangroad.com/subtopicC/topic.html"＞New Topic＜/a＞
1. 創建 HTML 主題
實際的幫助信息是用 HTML 創建的； helpset 查看器能夠解析并運行 HTML。您的 HTML 文件可以含有與其他文件以及圖像的鏈接。示例代碼 1 顯示了 welcome.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
·＜name＞: 命名窗口，使得 Java 程序可以通過名稱對它進行調用。
·＜size＞: 指定窗口尺寸（寬和高）的像素值。
·＜location＞: 用橫坐標(x)和縱坐標(y)指定窗口的位置。
·＜title＞: 定義顯示在窗口上部標題欄中的文本。
·＜toolbar＞: 說明該窗口含有一個工具欄。 工具欄上的按鈕的定義是這樣的：每個動作都使用一個 ＜helpaction＞ 標簽，每個動作也都有一個 Java 類名。例如，代碼: ＜helpaction＞javax.help.PrintSetupAction＜/helpaction＞定義了一個打印設置動作，因此用戶就可以設置/選擇打印機。
3. 創建 Map 文件
在讀取 helpset 文件之后，JavaHelp 系統就會讀取在 helpset 中所列出的 map 文件。map 文件使用 URL 將主題 ID 和 HTML 主題文件的路徑聯系起來。示例代碼 3 顯示了一個 map 文件示例：
示例代碼 3: Map.jhm
4. 創建目錄（TOC）文件
目錄文件描述了將顯示在目錄導航器中的目錄以及目錄的布局。目錄文件的示例請參見示例代碼 4。
示例代碼 4: SampleTOC.xml
5. 創建索引文件
索引文件向索引導航器描述索引的內容和布局。示例代碼 5 顯示了一個索引文件的示例。
示例代碼 5: SampleIndex.xml
示例索引文件運行結果見圖 3。
眼見為實
這時，您就可以查看以上所創建的幫助信息了。對它進行實驗的最簡單的方法就是按照以下的步驟：
·在 c: 下創建一個目錄，名稱可任取。為了演示方便，我將該目錄稱為 myhelp。
·將 Sample.hs、 map.jhm、 SampleTOC.xml、 SampleIndex.xml 拷貝至 myhelp 目錄下
·在 myhelp 下創建一個子目錄，叫做 help。
·將文件 welcome.html 拷貝至該子目錄。
·運行如下命令 (helpset 查看器) 以查看以上創建的幫助信息。
prompt＞ java -jar c:jh2.0demosinhsviewer.jar -helpset c:myhelpSample.hs
如果一切正常，您將會看到類似圖 4 的情況。
如上所述，您可以將所有的幫助信息文件封裝并壓縮到一個 Java ARchive (JAR) 文件中。方法是：
c:myhelp＞ java -cvf help.jar *
現在，您就可以用以下的命令查看幫助系統了：
prompt＞ java -jar c:jh2.0demosinhsviewer.jar -helpset c:myhelphelp.jar
創建全文搜索
全文搜索引擎使用了自然語言搜索技術，它除了檢索文檔外，也可以定位到查詢結構可能存在于其中的這些文檔的特定段落。 它包括一個用于文檔分析的概念性的索引引擎，以生成其內容的索引，它也包括一個查詢引擎，該引擎使用索引在材料當中查找相關的段落。
搜索數據庫是用 jhindexer 命令創建而成的。這將在 JavaHelpSearch 目錄下創建 6 個文件。這和其他的元數據文件位于同一個文件夾下。舉個例子，假設您在該文件夾下有三個子目錄叫做 "topic-a"、 "topic-b"和 "topic-c"。這些主題應該指定為 jhindexer 命令的參數：
jhindexer topic-a topic-b topic-c
當完成數據庫的創建后，它將保存到 JavaHelpSearch 下。
要驗證它是一個有效的數據庫，請運行如下命令：
jhsearch JavaHelpSearch
您將看到：
initialized; enter query
現在輸入一個查詢或者一個術語進行搜索，或者輸入一個點（.）退出。
將 JavaHelp 添加到應用程序中
現在您已經為應用程序開發了一個幫助信息系統，那么接下來的問題很自然就是如何如何將該系統加入到您的應用程序當中。 將幫助信息系統集成到應用程序中所需代碼的數量取決于您希望將該幫助信息系統作為應用程序的一部分，還是希望將該幫助信息系統作為另外一個獨立的應用程序，例如，當單擊幫助按鈕時，就顯示出該窗口。然而，在兩種情況下，將 JavaHelp 添加到一個應用程序中就和下面的 1-2-3 一樣容易:
·創建 HelpSet 和 HelpBroker 對象。
·將幫助賦給單個組件。
·為單個組件添加適當的幫助回調。
示例代碼 6 顯示了如何將上面所開發的幫助信息系統添加到一個應用程序中，當選中幫助菜單項時，系統會顯示出幫助信息窗口。作為一個練習，您可能希望對代碼進行重新的設計，使其能夠容易的集成到任何的應用程序當中。
示例代碼 6: HelpMenu.java
基于服務器的幫助
JavaHelp 2.0 的一個新的功能特點是基于服務器的幫助（ server-based help）。這是一個重要的功能，可使 JavaHelp 在瀏覽器窗口為基于 web 的應用程序提供幫助信息。使用新的 JavaHelp JST 標簽庫，可以很容易的將幫助信息添加到基于 web 的應用程序中。工作流程是：當瀏覽器發出一個 JSP 請求，Java 服務器將該請求轉換成一個 Java Servlet，它使用 JavaHelp 庫（jh.jar）和 JavaHelp 標簽庫（jhtags.jar）中的類從 helpset 中訪問適當的信息，并向瀏覽器返回 HTML，也可能是 JavaScript 或者動態 HTML。圖 6 顯示的是一個基于 Web 的應用程序的幫助信息示例。
要了解有關基于服務器的幫助的更多信息，請參考：JavaHelp 2.0 規范。
結束語
JavaHelp API 是需要運行于異構環境當中的在線幫助信息系統之作者和開發人員的首選技術。JavaHelp 系統可為開發人員增值，并提供完整的軟件應用程序，同時無需對編程和開發進行大量投資。此外，許多公司已經認可了 JavaHelp 系統，并計劃使用該 API 來建立統一的界面，以進行顯示和在內部和外部文檔間導航。
本文中的示例代碼描述了如何創建幫助信息文檔，這些文檔可以很容易的集成到新的和現有的應用程序當中。
現在有了 JavaHelp 技術，Java 開發人員就不再需要為應用程序所運行的每個平臺構建自己的幫助系統。JavaHelp 技術的目的是滿足當今的工業強度的應用程序。
本文將詳細介紹如何使用 JavaHelp 系統來為您的軟件系統提供更好的幫助信息。內容包括：
·幫助信息實現方法概述。
·JavaHelp 技術介紹。
·JavaHelp 技術的功能特點和優勢的討論。
·開發幫助信息所應用的風格。
·可用于您自己應用程序中的示例代碼。
幫助系統的可選方案
Java 開發人員可用以下幾種方案來實現其應用程序的幫助系統：
·無幫助系統：讓用戶自行判斷和領會系統是如何工作的。然而，一個軟系統如果沒有文檔、幫助信息系統、或者手冊，那么該軟件系統就是不完全的。而且還會影響到使用它的用戶。設想一下沒有使用手冊的 Adobe Photoshop 會是什么一種情況！
·使用 HTML：這是一個低成本的選項，但是其功能和導航受到限制。
·自定義系統：這是一個高成本的選項，耗費資源和時間。
·第三方私有方案：這是一個可替代自定義系統的可行的方案；然而，它也有自己的后果，包括：成本和長期支持。如果軟件供應商破產，你能做些什么呢？
這就是為什么要設計 JavaHelp 技術的原因。
JavaHelp 技術
JavaHelp 是一個可擴展的、平臺獨立的幫助系統，可使作者和開發人員將在線幫助融合到applet、應用程序、操作系統和設備之中。它也可用來 Web 上和公司內部 Intranet 上傳遞在線文檔。它的設計理念之一就是以網絡為中心，幫助數據和搜索功能既可以在客戶端，也可以在服務器端，同時幫助數據可以通過 Web 進行更新。
JavaHelp 系統是用 Java 語言所寫，因此可以運行在任何支持 Java Runtime Environment (JRE)的平臺或者瀏覽器上。這說明，它可用于異構環境中，如 Web 或 公司內部 Intranet。此外，它還可以用來為任何軟件應用程序開發和提供在線幫助，而不只是針對那些用 Java 語言開發而成的應用程序。而且，它也可以自我應用，而不需與任何軟件相關聯－－正如以 Web 為中心的分類文檔（如人力資源、技術支持、等）的傳輸機制。
JavaHelp 1.0 在 1999 年首次發布，經歷了數年的發展和完善，該技術現在已經成熟。 JavaHelp 2.0 技術由 Java Community Process (JCP) 設計成 JSR-97。這說明和 WinHelp 不同，JavaHelp 具有 HTML 內容的跨平臺優勢，因為它并不將公司局限于單一的平臺。請務必注意：JavaHelp 系統可以用來為部署在任何平臺上的任何軟件應用程序（而不僅僅是基于 Java 語言的應用程序）傳遞和提供在線幫助。
JavaHelp 系統得到了來自行業和 主要幫助寫作工具供應商 的廣泛支持。
JavaHelp 的功能和優勢
JavaHelp 提供了幾個對文檔寫作十分有用的功能。此外，它所提供的幾個可重用的組件可為 Java 開發人員節省大量的時間。JavaHelp 的一些功能如下：
·幫助導航器：內容目錄 (TOC) 支持以可折疊和可擴展的方式顯示主題、無限分級、多目錄合并；一個索引支持多索引合并；和具有靈活和可配置特性的全文檢索。
·壓縮：基于 JavaHelp 的幫助系統可以壓縮并封裝到一個單一的 Java Archive （JAR）文件中。
·可擴展和可定制： JavaHelp API 可用來定制或者擴展用戶界面及其功能。 Extensions 可以自定義導航，甚至是語音和聲音。這就使得作者在設計幫助系統時有更大的靈活性和控制力。
·上下文幫助：這是由 Swing 提供的。
·合并功能：在提供給用戶之前可以對多個幫助組件進行合并。
·動態更新：許在線幫助系統在發布之后進行動態更新。
·適應性強：可使幫助系統適用于提供和顯示信息。在最終部署環境事先未知的情況下，這將十分有用。
·可本地化：Java 支持國際化(I18N)，因此 JavaHelp 系統可以輕松進入國際市場。
部署和操作情況
JavaHelp 技術為作者和開發人員提供了幾種在應用程序中部署或調用它的方法。由于它是以網絡為中心的，所以它可以獨立于它所支持的應用程序而運行。它甚至可以嵌入應用程序之中。并且由于它是用 Java 語言所寫，因此它具有平臺獨立和瀏覽器獨立的特點，可運行在任何支持Java Runtime Environment (JRE)的平臺和瀏覽器上。這使得它成為當今異構計算環境中的理想的選擇。
這里是 JavaHelp 提供幫助信息的幾種情況：
·獨立應用程序：這是一個運行在桌面上的無需瀏覽器的本地應用程序。JavaHelp 幫助查看器可以作為一個單獨的應用程序或者一個嵌入到該本地應用程序本身的應用程序而運行。
·網絡應用程序：這些是網絡應用程序，它們從遠程服務器提取數據。JavaHelp 系統從遠程服務器裝載幫助信息是可能的。這對軟件開發商來說十分有用，它們就可以為其客戶提供輕量級的客戶端應用程序，這些輕量級的應用程序從遠程服務器提取幫助信息。軟件供應商可以隨意更改幫助信息，而不需要發布新的軟件版本。
·Applets：運行于 web 瀏覽器中的小應用程序。JavaHelp 系統本身可以是瀏覽器的一部分，同時幫助數據可以是，也可以不是應用程序的一部分。
·基于服務器的應用程序：這是一個運行于 Java 服務器上的，但使用瀏覽器作為其 GUI 的應用程序。
參考實現
Sun Microsystems 提供一個參考實現 (JavaHelp System)，它將實現 JavaHelp 規范。它具有成熟、健壯和可靠的特點，并可供開發人員所使用。JavaHelp System 下載的地址是： http://java.sun.com/products/javahelp。其最新的版本是2.0_01.
參考實現是以壓縮文件的形式出現的，在選擇的目錄下對它進行解壓縮就可以輕松的進行安裝。 如果您選擇 Windows 的 c: 作為其目的，它將被安裝到 c:jh2.0 下。
參考實現附帶有文檔、工具和幾個演示程序。二進制演示程序位于 c:jh2.0demosin， 用 java -jar demoName.jar 命令可以方便的運行這些演示程序。除了這些演示程序外，目錄 c:jh2.0javahelpin 含有 jhindexer 和 jhsearch 工具，它們分別用來創建索引數據庫和搜索的。最后，目錄 c:jh2.0javahelplib 含有 JavaHelp API 的 JAR 文件，它們是：
·jh.jar: 使用標準導航器（目錄、索引、全文檢索）所需的標準庫。
·jhbasic.jar: 它是 jh.jar 的子集，不包含對全文搜索引擎的支持。對于那些大小很關鍵的幫助信息系統，或者不需要全文檢索數據庫的系統來說，這可能會十分有用。
·jhall.jar: 含有所有 JavaHelp 系統類，以及創建檢索數據庫所需的工具。
·jsearch.jar: 含有用于 JavaHelp 系統中的全文搜索引擎。
JavaHelp 幫助查看器
參考實現所附帶的一個有趣的演示程序是幫助查看器（c:jh2.0demosinhsviewer.jar），它是一個 helpset 查看器，可用來查看本文將要部署的幫助信息。值得注意的是它和 508 兼容。
如圖 1 所示的標準查看器是由一個工具欄（可用來顯示多種按鈕如 Back、Forward、Print，等等）和兩個窗格所組成：
·內容窗格: 使用 HTML 和 frame 、表格和輕量級組件顯示幫助主題
·導航窗格: 一個標簽界面，用戶可以在目錄、索引和全文搜索顯示模式之間進行切換。需要指出的是，導航器和內容查看器是同步的，所以用戶總是知曉相對位置和選項。
|
幫助信息寫作
為了用 JavaHelp 系統開發幫助信息，作者需要創建 JavaHelp 系統用來顯示信息的元數據文件。此外，作者也需要創建供用戶使用的主題。元數據和主題文件被稱為 helpset。有一些幫助制作工具對這些 helpset 的創建進行了簡化，但在本文中，我們將自己創建這些 helpset。
創建 helpset 包含以下步驟：
·使用您所喜歡的編輯器創建 HTML 主題。
·創建一個 helpset 文件。
·創建一個 map 文件。
·創建一個目錄。
·創建一個索引文件。
·創建一個全文檢索數據庫。
·將幫助文件壓縮并封裝到一個 JAR 文件中，以便提供給客戶。
注意：第 5 和第 6 步只有當您的幫助信息系統中集成有索引和全文檢索數據庫時才是必要的。
要查看您的 helpset，helpset 查看器提供有參考實現（RI）。 helpset 查看器位于 c:jh2.0demosinhsviewer.jar
當查看器處于打開狀態時，單擊 "Browse" 來定位到一個 helpset (擴展名為 .hs)。 您也可以用以下方法進行查看：
java -jar c:jh2.0demosinhsviewer.jar -helpset c:PathToMyHelpSet.hs
幫助主題包含在文件中，這些文件在幫助查看器中一次顯示一個，從這個意義上講，Java Help 系統是基于文件的系統。相互關聯的主題應該進行分組。最好用文件夾的分級結構來組織幫助主題。從一個主題到另一個主題的鏈接應該在含有該鏈接的文件中進行指定，且不能使用絕對路徑。而且，您應該使用正斜杠 "/" 作為文件分隔符。舉例如下：
＜a href="http://www.zhujiangroad.com/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" "http://www.zhujiangroad.com/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＞定義了一個打印設置動作，因此用戶就可以設置/選擇打印機。
3. 創建 Map 文件
在讀取 helpset 文件之后，JavaHelp 系統就會讀取在 helpset 中所列出的 map 文件。map 文件使用 URL 將主題 ID 和 HTML 主題文件的路徑聯系起來。示例代碼 3 顯示了一個 map 文件示例：
示例代碼 3: Map.jhm
＜?xml version='1.0' encoding='ISO-8859-1' ?＞ ＜!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN" "http://java.sun.com/products/javahelp/map_1_0.dtd"＞ ＜map version="1.0"＞ ＜mapID target="toplevelfolder" url="images/toplevel.gif" /＞ ＜mapID target="top" url="help/welcome.html" /＞ ＜mapID target="intro" url="help/welcome.html" /＞ ＜mapID target="start" url="help/start.html" /＞ ＜mapID target="overview" url="help/welcome.html" /＞ ＜mapID target="one" url="help/start.html" /＞ ＜mapID target="two" url="help/start.html" /＞ ＜mapID target="bean.story" url="help/welcome.html" /＞ ＜mapID target="bean.story" url="help/start.html" /＞ ＜mapID target="bean.story" url="help/welcome.html" /＞ ＜/map＞
4. 創建目錄（TOC）文件
目錄文件描述了將顯示在目錄導航器中的目錄以及目錄的布局。目錄文件的示例請參見示例代碼 4。
示例代碼 4: SampleTOC.xml
＜?xml version='1.0' encoding='ISO-8859-1' ?＞ ＜!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN" "http://www.zhujiangroad.com/dtd/toc_2_0.dtd"＞ ＜toc version="2.0"＞ ＜tocitem text="My Sample Help" image="toplevelfolder"＞ ＜tocitem text="Introduction to Sample Online Help" target="intro"/＞ ＜tocitem text="Tutorial" target="start" expand="true"＞ ＜tocitem text="Welcome" target="overview"/＞ ＜tocitem text="Tutorial One: Help One" target="one"/＞ ＜tocitem text="Tutorial Two: Help Two" target="two"/＞ ＜/tocitem＞ ＜tocitem text="Beans In IDE" target="bean.story"/＞ ＜tocitem text="Beans In IDE - in SecondaryWindow" target="bean.story" // presentationtype="javax.help.SecondaryWindow" presentationname="main"/＞ ＜tocitem text="Beans In IDE - in Popup" target="bean.story" presentationtype="javax.help.Popup"/＞ ＜/tocitem＞ ＜/toc＞示例目錄的運行結果如圖 2 所示。
|
5. 創建索引文件
索引文件向索引導航器描述索引的內容和布局。示例代碼 5 顯示了一個索引文件的示例。
示例代碼 5: SampleIndex.xml
＜?xml version='1.0' encoding='ISO-8859-1' ?＞ ＜!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN" "http://java.sun.com/products/javahelp/index_1_0.dtd"＞ ＜index version="1.0"＞ ＜indexitem text=".prof extension (profile data)" target="prof.profile"/＞ ＜indexitem text="accelerators (keyboard), see 'keyboard commands'"/＞ ＜indexitem text="adding an existing project" expand="false"＞ ＜indexitem text="naming the project" target="proj.importdirectory"/＞ ＜indexitem text="naming the storage directory" target="proj.importdirectory"/＞ ＜indexitem text="procedures for" target="proj.importproject2"/＞ ＜/indexitem＞ ＜indexitem text="arguments" expand="false"＞ ＜indexitem text="passing" target="debug.arguments"/＞ ＜indexitem text="specifying" target="debug.arguments"/＞ ＜/indexitem＞ ＜indexitem text="beans" expand="false"＞ ＜indexitem text="adding existing sources to a bean project" target="proj.existingbeans"/＞ ＜indexitem text="changing bean file status" target="proj.existingbeans"/＞ ＜indexitem text="creating a bean project" target="proj.beansproject"/＞ ＜indexitem text="removing existing sources from a bean project" target="proj.existingbeans"/＞ ＜/indexitem＞ ＜/index＞
示例索引文件運行結果見圖 3。
|
眼見為實
這時，您就可以查看以上所創建的幫助信息了。對它進行實驗的最簡單的方法就是按照以下的步驟：
·在 c: 下創建一個目錄，名稱可任取。為了演示方便，我將該目錄稱為 myhelp。
·將 Sample.hs、 map.jhm、 SampleTOC.xml、 SampleIndex.xml 拷貝至 myhelp 目錄下
·在 myhelp 下創建一個子目錄，叫做 help。
·將文件 welcome.html 拷貝至該子目錄。
·運行如下命令 (helpset 查看器) 以查看以上創建的幫助信息。
prompt＞ java -jar c:jh2.0demosinhsviewer.jar -helpset c:myhelpSample.hs
如果一切正常，您將會看到類似圖 4 的情況。
|
如上所述，您可以將所有的幫助信息文件封裝并壓縮到一個 Java ARchive (JAR) 文件中。方法是：
c:myhelp＞ java -cvf help.jar *
現在，您就可以用以下的命令查看幫助系統了：
prompt＞ java -jar c:jh2.0demosinhsviewer.jar -helpset c:myhelphelp.jar
創建全文搜索
全文搜索引擎使用了自然語言搜索技術，它除了檢索文檔外，也可以定位到查詢結構可能存在于其中的這些文檔的特定段落。 它包括一個用于文檔分析的概念性的索引引擎，以生成其內容的索引，它也包括一個查詢引擎，該引擎使用索引在材料當中查找相關的段落。
搜索數據庫是用 jhindexer 命令創建而成的。這將在 JavaHelpSearch 目錄下創建 6 個文件。這和其他的元數據文件位于同一個文件夾下。舉個例子，假設您在該文件夾下有三個子目錄叫做 "topic-a"、 "topic-b"和 "topic-c"。這些主題應該指定為 jhindexer 命令的參數：
jhindexer topic-a topic-b topic-c
當完成數據庫的創建后，它將保存到 JavaHelpSearch 下。
要驗證它是一個有效的數據庫，請運行如下命令：
jhsearch JavaHelpSearch
您將看到：
initialized; enter query
現在輸入一個查詢或者一個術語進行搜索，或者輸入一個點（.）退出。
將 JavaHelp 添加到應用程序中
現在您已經為應用程序開發了一個幫助信息系統，那么接下來的問題很自然就是如何如何將該系統加入到您的應用程序當中。 將幫助信息系統集成到應用程序中所需代碼的數量取決于您希望將該幫助信息系統作為應用程序的一部分，還是希望將該幫助信息系統作為另外一個獨立的應用程序，例如，當單擊幫助按鈕時，就顯示出該窗口。然而，在兩種情況下，將 JavaHelp 添加到一個應用程序中就和下面的 1-2-3 一樣容易:
·創建 HelpSet 和 HelpBroker 對象。
·將幫助賦給單個組件。
·為單個組件添加適當的幫助回調。
示例代碼 6 顯示了如何將上面所開發的幫助信息系統添加到一個應用程序中，當選中幫助菜單項時，系統會顯示出幫助信息窗口。作為一個練習，您可能希望對代碼進行重新的設計，使其能夠容易的集成到任何的應用程序當中。
示例代碼 6: HelpMenu.java
import java.net.*; import javax.help.*; import javax.swing.*; import java.awt.event.*; public class HelpMenu { JFrame f; JMenuItem topics; public HelpMenu() { f = new JFrame("Menu Example"); JMenuBar mbar = new JMenuBar(); // a file menu JMenu file = new JMenu("File"); JMenu help = new JMenu("Help"); // add an item to the help menu help.add(topics = new JMenuItem("Help Topics")); // add the menu items to the menu bar mbar.add(file); mbar.add(help); // 1. create HelpSet and HelpBroker objects HelpSet hs = getHelpSet("sample.hs"); HelpBroker hb = hs.createHelpBroker(); // 2. assign help to components CSH.setHelpIDString(topics, "top"); // 3. handle events topics.addActionListener(new CSH.DisplayHelpFromSource(hb)); // attach menubar to frame, set its size, and make it visible f.setJMenuBar(mbar); f.setSize(500, 300); f.setVisible(true); } /** * find the helpset file and create a HelpSet object */ public HelpSet getHelpSet(String helpsetfile) { HelpSet hs = null; ClassLoader cl = this.getClass().getClassLoader(); try { URL hsURL = HelpSet.findHelpSet(cl, helpsetfile); hs = new HelpSet(null, hsURL); } catch(Exception ee) { System.out.println("HelpSet: "+ee.getMessage()); System.out.println("HelpSet: "+ helpsetfile + " not found"); } return hs; } public static void main(String argv[]) { new HelpMenu(); } } 實驗該代碼的最簡單的方法是將 HelpMenu.java 拷貝至 c:myhelp下。編譯并運行它。如果一切正常，您會看到類似圖 5 的情況。如果單擊幫助主題（ Help Topics）， 那么就會出現圖 4 中的幫助信息窗口。
|
基于服務器的幫助
JavaHelp 2.0 的一個新的功能特點是基于服務器的幫助（ server-based help）。這是一個重要的功能，可使 JavaHelp 在瀏覽器窗口為基于 web 的應用程序提供幫助信息。使用新的 JavaHelp JST 標簽庫，可以很容易的將幫助信息添加到基于 web 的應用程序中。工作流程是：當瀏覽器發出一個 JSP 請求，Java 服務器將該請求轉換成一個 Java Servlet，它使用 JavaHelp 庫（jh.jar）和 JavaHelp 標簽庫（jhtags.jar）中的類從 helpset 中訪問適當的信息，并向瀏覽器返回 HTML，也可能是 JavaScript 或者動態 HTML。圖 6 顯示的是一個基于 Web 的應用程序的幫助信息示例。
|
要了解有關基于服務器的幫助的更多信息，請參考：JavaHelp 2.0 規范。
結束語
JavaHelp API 是需要運行于異構環境當中的在線幫助信息系統之作者和開發人員的首選技術。JavaHelp 系統可為開發人員增值，并提供完整的軟件應用程序，同時無需對編程和開發進行大量投資。此外，許多公司已經認可了 JavaHelp 系統，并計劃使用該 API 來建立統一的界面，以進行顯示和在內部和外部文檔間導航。
本文中的示例代碼描述了如何創建幫助信息文檔，這些文檔可以很容易的集成到新的和現有的應用程序當中。