JavaアプリケーションからOS独立なヘルプを使うためのライブラリJavaHelpを使うための方法を解説します。JavaHelpはすべてJavaで記述されており、Windows以外のシステムでもJavaアプリケーションからヘルプを参照できるようになります。 また、JavaHelpパッケージは再配布可能となっており、自分の作ったJavaアプリケーションに同梱して配布することができるため、ユーザが改めてJavaHelpパッケージをダウンロードする必要はありません。
ここではJavaHelp2.0_02を使用する方法を説明しています。
JavaHelpで作成したヘルプ画面のスクリーンショット
インストール
JavaHelpパッケージをダウンロードする。
2009/6/28現在、最新版はjavahelp-2_0_05.zipとなっています。
ダウンロード後、zipファイルを任意のディレクトリで展開する。展開するとjh2.0というディレクトリができ、その下にJavaHelpを使用するためのすべてのファイルやドキュメント類が格納されています。必要に応じてデモを動かしたり、ドキュメントを参照したりしてください。
以下ではJavaHelpを展開したディレクトリを「C:\jh2.0」であるとして説明します。
(2017/1/14追記)
現在公式サイトからはzipファイルがダウンロードできず、SVNから個々のファイルをダウンロードするかできなくなっています。zipファイルを格納しているミラーサイトがまだいくつか残っているので、適当なところから入手可能です。JavaHelpは死にゆく運命なのか……。
Java公式のSVN
ミラーサイト一覧
ヘルプファイルの作成
JavaHelpを使用するためには以下の手順を踏む必要があります。
- ヘルプを記述したHTMLファイルを作る。
- ヘルプセットファイルを作る。
- マップファイルを作る。
- 目次ファイルを作る。
- インデックスファイルをつくる。
- できあがったヘルプファイル群をjarファイルにまとめる。
以下、それぞれの手順について説明します。
※ この他にも全文検索用のデータベースを構築したり、お気に入りを登録したりといったことができますがここでは省略し、実験でき次第追記していきます。
ヘルプを記述したHTMLファイルを作る。
ヘルプの内容を記述したHTMLファイルを作ります。適当なフォルダを作ってフォルダごとにトピックを管理すると便利だと思います。ディレクトリ構造は任意ですので作成者が作りやすいように決めてください。 ここではサンプルとして以下のようなディレクトリ・ファイル構造とします。「※」のついたファイル(赤字のファイル・ディレクトリ)はJava Helpシステムが使用するメタデータです。これらについてはそれぞれ節を設けて作成方法を説明します。
C:\jhdemo\top.html
\demo_helpset.hs (※ ヘルプセット)
\demo_map.jhm (※ マップファイル)
\demo_toc.xml (※ 目次データ)
\demo_index.xml (※インデックスデータ)
\topic1\topic.html
\subtopicA\topic.html
\subtopicB\topic.html
\topic2\topic.html
ヘルプファイルを作る際は以下の点に注意してください。 リンクは相対リンクとする。
- 例えば \topic1\subtopicA\topic.html から \top.html を参照する場合は、
○ <A href="../../top.html>トップに戻る</A>
のようにしてください。次のように絶対パスで書いてはいけません。
× <A href="c:/project/help/top.html>トップに戻る</A> - ファイルセパレータは'/'(半角スラッシュ)を使う。
Windowsではバックスラッシュも使えるようですが、他のOSで正しく動作しなくなるのでスラッシュで統一した方が良いです。
サンプルとして以下のリンクのようなHTMLファイル群を作成してみました。参照してみてください。
JavaHelpの作り方(デモ)
ヘルプセットファイルを作る。
ヘルプセットファイルとはヘルプを構成するファイル構造などを定義するファイルで、アプリケーションからヘルプを呼び出すときにまず始めに参照するファイルです。ファイルはXMLで記述します。 拡張子は「.hs」とするのが推奨されています。
詳細なフォーマットはユーザーズガイド(JavaHelp2.0_02ではjhug.pdfファイルの4.4節(42ページ以降)にある)を参照してください。ここでは最低限の設定方法について説明します。
以下はユーザーズガイドから必要な部分を抜粋したサンプルです。サンプルと異なる部分を赤字にしています。
demo_helpset.hs
<?xml version='1.0' encoding='Shift_JIS' ?>
<!DOCTYPE helpset
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"
"http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="2.0">
<!-- title -->
<title>JavaHelpの使い方(デモ)</title>
<!-- maps -->
<maps>
<homeID>top</homeID>
<mapref location="demo_map.jhm" />
</maps>
<!-- views -->
<view xml:lang="ja" mergetype="javax.help.UniteAppendMerge">
<name>TOC</name>
<label>Table Of Contents</label>
<type>javax.help.TOCView</type>
<data>demo_toc.xml</data>
</view>
<view xml:lang="ja">
<name>Search</name>
<label>Search</label>
<type>javax.help.SearchView</type>
<data engine="com.sun.java.help.search.DefaultSearchEngine">
JavaHelpSearch
</data>
</view>
<view xml:lang="ja" mergetype="javax.help.SortMerge">
<name>Index</name>
<label>Index</label>
<type>javax.help.IndexView</type>
<data>demo_index.xml</data>
</view>
</helpset>
viewを定義することで、ヘルプ画面のview(スクリーンショット画面中で丸で囲った部分)として何を使用するかを指定します。上記の例では、目次・索引・全文検索を定義しています。
マップファイルを作る。
マップファイルはトピックIDとURLとを関連づけるためのファイルです。通常はあるトピックごとにHTMLファイルを作成しているはずなので、HTMLファイルで記述しているトピック名とそのHTMLファイルのパスの対応関係をすべて記述します。フォーマットはXMLです。
demo_map.jhm
<?xml version='1.0' encoding='Shift_JIS' ?>
<!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN"
"http://java.sun.com/products/javahelp/map_2_0.dtd">
<map version="2.0">
<mapID target="top" url="top.html" />
<mapID target="topic1" url="topic1/topic.html" />
<mapID target="topic1.subtopicA" url="topic1/subtopicA/topic.html" />
<mapID target="topic1.subtopicB" url="topic1/subtopicB/topic.html" />
<mapID target="topic2" url="topic2/topic.html" />
</map>
目次ファイルを作る。
目次ファイルは目次を表示するための管理ファイルです。フォーマットはXMLです。
demo_toc.xml
<?xml version='1.0' encoding='Shift_JIS' ?>
<!DOCTYPE toc
PUBLIC
"-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN"
"http://java.sun.com/products/javahelp/toc_2_0.dtd">
<toc version="2.0">
<tocitem text="JavaHelpの使い方(デモ)" image="openbook">
<tocitem text="概要" image="topic" target="top" />
<tocitem text="topic1" image="chapter" target="topic1">
<tocitem text="subtopicA" image="topic" target="topic1.subtopicA" />
<tocitem text="subtopicB" image="topic" target="topic1.subtopicB" />
</tocitem>
<tocitem text="topic2" image="chapter" target="topic2" />
</tocitem>
</toc>
マップファイルで定義したmapIDを使って目次の階層関係を定義します。階層はtocitemを入れ子にすることによって定義します。またそれぞれの目次項目の前に表示するグラフィックイメージをimage属性で指定することができます(任意)
インデックスファイルを作る。
インデックスファイルは目次の索引を定義するファイルです。フォーマットはXMLです。
demo_index.xml
<?xml version='1.0' encoding='Shift_JIS' ?> <!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 2.0//EN" "http://java.sun.com/products/javahelp/index_2_0.dtd"> <index version="2.0"> <indexitem text="topic1" target="topic1" /> <indexitem text="topic2" target="topic2" /> </index>
全文検索用のデータを作成する。
全文検索に用いるデータをJavaHelpに同梱されているツールを用いて作成します。ヘルプが日本語でも大丈夫のようです。
作成するヘルプのトップディレクトリで以下のようにコマンドを実行してください。引数として、ヘルプを構成するHTMLファイルやHTMLファイルが格納されているディレクトリを指定します。ディレクトリを指定した場合は再帰的にその下のディレクトリ内のHTMLファイルも処理してくれます。
C:\jhdemo\>c:\jh2.0\javahelp\bin\jhindexer top.html topic1 topic2
これにより、カレントディレクトリにJavaHelpSearch?というディレクトリができ、その下に検索用に用いるデータが格納されます。
できあがったヘルプを表示する。
ここまでで最低限のヘルプシステムは完成です。JavaHelpに同梱されているツールhsviewerを利用して、作成したヘルプを見ることができます。JavaHelpを展開してできたディレクトリ内で、hsviewer.jarがあるディレクトリをカレントディレクトリとして、以下のようにコマンドを実行してください。 (以下の例ではJavaHelpの展開先を「C:\jh2.0」としています)
C:\jh2.0\demos\bin>java -jar hsviewer.jar -helpset C:\jhdemo\demo_helpset.hs
できあがったヘルプファイル群をjarファイルにまとめる。
作成したヘルプ構成ファイルは、jarコマンドでひとまとめにして圧縮しておいた方が配布するヘルプの容量を小さくできるので便利です。 ヘルプのトップディレクトリ直下(この例ではC:\jhdemo)でjarコマンドを以下のように実行してください。
C:\jhdemo>c:\j2sdk1.4.2_10\bin\jar -cvf demo_help.jar * マニフェストが追加されました。 bullet026.gif を追加中です。(入 = 96) (出 = 98)(-2% 収縮されました) demo_helpset.hs を追加中です。(入 = 795) (出 = 411)(48% 収縮されました) demo_index.xml を追加中です。(入 = 325) (出 = 220)(32% 収縮されました) demo_map.jhm を追加中です。(入 = 533) (出 = 251)(52% 収縮されました) demo_toc.xml を追加中です。(入 = 641) (出 = 311)(51% 収縮されました) top.html を追加中です。(入 = 872) (出 = 523)(40% 収縮されました) topic1/ を追加中です。(入 = 0) (出 = 0)(0% 格納されました) topic1/subtopicA/ を追加中です。(入 = 0) (出 = 0)(0% 格納されました) topic1/subtopicA/topic.html を追加中です。(入 = 538) (出 = 401)(25% 収縮されました) topic1/subtopicB/ を追加中です。(入 = 0) (出 = 0)(0% 格納されました) topic1/subtopicB/topic.html を追加中です。(入 = 691) (出 = 519)(24% 収縮されました) topic1/topic.html を追加中です。(入 = 1198) (出 = 658)(45% 収縮されました) topic2/ を追加中です。(入 = 0) (出 = 0)(0% 格納されました) topic2/topic.html を追加中です。(入 = 563) (出 = 427)(24% 収縮されました)
このjarファイルをhsviewerで参照することもできます。
C:\jh2.0\demos\bin>java -jar hsviewer.jar -helpset C:\jhdemo\demo_help.jar
アプリケーションからヘルプを呼び出す。
アプリケーションからヘルプを呼び出す場合はヘルプセットをjarでまとめておくより、ディレクトリ構造をそのまま利用した方が便利かもしれません。特にEclipseでJavaアプリケーションをつくっている場合は、アプリケーションのjarファイルにヘルプファイル群をまとめるときに、ヘルプがjarになっていない方が作業しやすいです。 以下ではヘルプをjarにまとめないでおく方法を紹介します。
まずユーザアプリケーションのソースディレクトリの直下に、例えばhelpというディレクトリを作成して、これまで作ってきたヘルプセットの全ファイル(C:\jhdemo\の下のファイル・ディレクトリ)をコピーします。
JavaHelpパッケージで必要なクラスをimportする。
import java.net.URL; import javax.help.CSH; import javax.help.HelpBroker; import javax.help.HelpSet;
以下のようなコードを適当な場所(メニューアイテムのイベントハンドラなど)。
HelpSet helpset = null;
HelpBroker broker = null;
try {
URL url = URL url = getClass().getResource("/help/demo_helpset.hs");
helpset = new HelpSet(null, url);
} catch (Exception ex) {
ex.printStackTrace();
return ;
}
broker = helpset.createHelpBroker();
ActionListener helper = new CSH.DisplayHelpFromSource(hb);
この変数helperをメニューアイテムのイベントハンドラに追加する。
サンプルとして、Eclipse+Visual Editorで作ったコードをデモプログラムのソースを示しておきます。
アプリケーションにヘルプを統合する。
JavaHelpパッケージのライブラリは再配布可能となっているため、以下の４つのライブラリから必要に応じて一つ選んで、アプリケーションに同梱することができます。
| ライブラリ名 | 説明 |
| jh.jar | 標準的なライブラリ。目次・インデックス・全文検索用のライブラリを含む。 |
| jhbasic.jar | jh.jarから全文検索ライブラリを除いたもの。 |
| jhall.jar | JavaHelpシステムのすべてを含む。これにはライブラリと全文検索用のデータベースを作成するのに必要なツールを含んでいる。 |
| jsearch.jar | JavaHelpシステムが使用する全文検索エンジン。 |
配布するファイルのサイズが非常に重要な場合以外は、jh.jarを選んでおけば良いでしょう。
これまで説明してきたヘルプと、前節で示したデモアプリケーションをパッケージングしたjarファイルを置いておきます。以下のファイルを適当なディレクトリに置いてJavaHelpDemo.jarを実行してください。
EclipseでのJarファイルの統合
Eclipse本体の機能では複数のjarファイルを統合することができないようなので、EclipseからAntを呼び出してjarファイルの統合を行います。
次のようなビルドファイルをプロジェクトのルートディレクトリに置いて、AntビューからAntを実行すれば良いです。この場合、プロジェクトのルートディレクトリにJavaHelpDemo?.jarというファイルが作成されます。 target_name, main_class, javahelp_jarは適宜変更してください。
build.xml
<project name="JavaHelpDemo" default="packaging" basedir=".">
<property name="target_name" value="JavaHelpDemo.jar" />
<property name="main_class" value="jp.asamomiji.test.JavaHelpDemo" />
<property name="javahelp_jar" value="c:/jh2.0/javahelp/lib/jh.jar" />
<target name="packaging">
<delete file="${target_name}" />
<jar jarfile="${target_name}">
<fileset dir="bin"/>
<zipfileset src="${javahelp_jar}" excludes="META-INF/*"/>
<manifest>
<attribute name="Main-Class" value="${main_class}" />
</manifest>
</jar>
</target>
</project>
コメント