【特集】APIドキュメントを見やすくする

概要

Kaburobo SDKに含まれるHTML形式のKaburobo APIヘルプドキュメントをMicrosoft HTML Help形式へ変換する方法を紹介します。Microsoft HTML Help形式は検索機能が充実しています。通常のHTML形式のドキュメントをブラウザで見るよりも快適です。
変換後のAPIヘルプドキュメント
インクリメンタルサーチ全文検索などが可能になります。

手順

%KABUROBO_HOME%\doc\javadocフォルダに含まれるAPIヘルプドキュメントを、html2winhelpというプログラムで処理します。html2winhelpは、Javadocによって出力されたHTMLファイルをMicrosoft HTML Helpのソースへと変換します。変換されたソースは、Microsoft社が配布しているHTML Help Workshopを使用することで、Microsoft HTML Help形式のヘルプ(拡張子は*.chm)へ変換できます。

必要なプログラムの入手

Kaburobo SDKとJDKに加え、以下のプログラムが必要となります。
- HTML Help Workshop(Download Htmlhelp.exeリンクをクリック)
- html2winhelp(Ver.1.5.0リンクをクリック)

HTML Help Workshopのインストール

ダウンロードしたhtmlhelp.exeを開きます。警告が表示される場合は「実行」ボタンをクリックしてください。すると、ライセンスが表示されますので、同意する場合は「Yes」ボタンをクリックしてください。
HTML help Workshopライセンス
インストールを開始するか尋ねられるので、「はい」ボタンをクリックします。
インストール開始の確認
インストール先のフォルダを設定するダイアログが表示されます。デフォルトの設定では、C:\Program Files\HTML Help Workshopフォルダにインストールされます。今回はデフォルト設定のまま、インストールを続行します。「OK」ボタンをクリックします。
インストール先フォルダの確認
次のようなメッセージボックスが表示されれば、HTML Workshopのインストールは完了です。「OK」ボタンをクリックしてメッセージボックスを閉じてください。
インストールの完了

html2winhelpのインストール

ダウンロードしたhtml2winhelp-1.5.0.zipを適当なフォルダへ展開するだけでインストールは完了です。以下の解説では、C:\kaburobo\html2winhelp-1.5.0に展開したと仮定します。

ソースファイルの生成

コマンドプロンプトを開き、%KABUROBO_HOME%\docに移動します。
以下の説明では、%KABUROBO_HOME%の値がC:\kaburobo\kaburobo-sdk-2.0.3であると仮定します。
移動後、変換後のファイルを置くフォルダ「output」を作ります。
C:\>cd %KABUROBO_HOME%\doc

C:\kaburobo\kaburobo-sdk-2.0.3\doc>mkdir output

C:\kaburobo\kaburobo-sdk-2.0.3\doc>dir
 ドライブ C のボリューム ラベルは HDD です
 ボリューム シリアル番号は 50B2-B98B です

 C:\kaburobo\kaburobo-sdk-2.0.3\doc のディレクトリ

2007/08/22  10:42    <DIR>          .
2007/08/22  10:42    <DIR>          ..
2007/08/20  12:59    <DIR>          help
2007/08/20  12:59    <DIR>          javadoc
2007/08/22  10:42    <DIR>          output
               0 個のファイル                   0 バイト
               5 個のディレクトリ  40,663,379,968 バイトの空き領域
html2winhelpでソースファイルを作ります。
>html2winhelp 出力ファイル名 "ドキュメントタイトル" 入力元dir 出力先dir "エンコーディング"
出力ファイル名は、.chmファイルのファイル名の拡張子以外の部分となります。
"ドキュメントタイトル"は、.chmファイルを開いたときにトップレベルに表示されるタイトル名です。今回は、"カブロボSDK 2.0.3 APIリファレンス"を指定します。
入力元dirは、入力ファイルが置かれているフォルダへのパスを指定します。%KABUROBO_HOME%\doc\javadocを指定します。
出力先dirは、出力ファイルを置くフォルダへのパスを指定します。ここでは、先ほど作成したouputフォルダを指定することにします。
最後のエンコーディングは、Javadocによって生成されたHTMLファイルのエンコーディングを指定します。先頭に記述されたものから順番に読み込みを試みて、最初に成功したものが採用されます。一般的には"UTF8,ISO2022JP,EUC_JP,MS932"と指定すれば、困ることはないはずです。Kaburobo SDKのAPIリファレンスはShift_JISでエンコーディングされていますので、MS932を指定すれば十分かも知れません。
実行例を示します。
C:\kaburobo\kaburobo-sdk-2.0.3\doc>C:\kaburobo\html2winhelp-1.5.0\bin\html2winhe
lp KHelp203 "カブロボSDK 2.0.3 APIリファレンス" javadoc output "UTF8,ISO2022JP,E
UC_JP,MS932"
indexing javadoc\index-files\index-1.html
indexing javadoc\index-files\index-10.html
 : 中略
converting output\jp\tradesc\superkaburobo\sdk\trade\data
converting output\jp\tradesc\superkaburobo\sdk\trade\data\class-use
converting output\resources
以上で、ソースファイルの生成が完了します。

ソースファイルのコンパイル

続いて、HTML Help Workshopに含まれるhhcというプログラムを用いて、出力先フォルダに生成されたwinhelp.hhpをコンパイルします。
C:\kaburobo\kaburobo-sdk-2.0.3\doc>"C:\Program Files\HTML Help Workshop\hhc" out
put\winhelp.hhp
Microsoft HTML Help Compiler 4.74.8702

Compiling c:\kaburobo\kaburobo-sdk-2.0.3\doc\output\KHelp203.chm


Compile time: 0 minutes, 26 seconds
1,152   Topics
13,412  Local links
0       Internet links
1       Graphic


Created c:\kaburobo\kaburobo-sdk-2.0.3\doc\output\KHelp203.chm, 627,363 bytes
Compression decreased file by 3,662,811 bytes.

C:\kaburobo\kaburobo-sdk-2.0.3\doc>
コンパイルには、それなりに時間がかかります。
コンパイル終了後、outputフォルダにKHelp203.chmが生成されているはずです。
お疲れさまでした。