C ヘルプ・ブックの処理

この付録では、古いバージョンのOHJでヘルプ・ブック・ファイルおよびHelpBookオブジェクトが使用されていることについて説明します。ヘルプ・ブックは現行バージョンのOHJでもまだサポートされていますが、現行バージョンではヘルプセット（ヘルプセット・ファイルおよびHelpSetオブジェクト）を使用することをお薦めします。

ヘルプ・ブック・ファイルおよびHelpBookオブジェクトをまだ使用しており、ヘルプセットを使用していない場合は、次の項のヘルプ・ブック固有の情報を参照してください。

この付録の構成は、次のとおりです。

• 第C.1項「ヘルプ・ブック・ファイル名の拡張子」

• 第C.2項「OHJへのHelpデータの追加」

• 第C.3項「Oracle Help for the Web構成ファイルのロケール」

C.1 ヘルプ・ブック・ファイル名の拡張子

ヘルプ・ブックを使用する場合は、ファイル名および拡張子が正しいことを確認してください。OHJおよびOHWは、指定されたディレクトリで、サポートするファイル形式に対応したファイル名の拡張子（TOC、TOK、HHC、HHK、OHTおよびIDXを含む）を検索します。正しいファイル名および拡張子の詳細は、第4.2項「ファイル名の拡張子」を参照してください。

ヘルプセットを使用する場合は、関連する制御ファイルの名前に、指定された拡張子を使用する必要はありません。

C.2 OHJへのHelpデータの追加

ヘルプ・ブックをOHJに追加する場合は、まず、Helpオブジェクトを作成する必要があります。詳細は、第13.2項「Helpオブジェクトの構成」を参照してください。

注意: ヘルプ・ブックを使用してOHJシステムを実装している場合、マップ・ファイルにOHTファイル形式を使用する必要があります。ヘルプ・ブック・ファイルおよびOHTファイルは、OHJの初期バージョンのレガシーであり、現在は使用が推奨されていませんが、まだサポート対象となっています。マップ・ファイルの詳細は、第5.3項「マップ・ファイル」を参照してください。

Helpオブジェクトを作成した後、1つ以上のBookオブジェクトを追加する必要があります。Bookオブジェクトによって、コレクション（つまり、ヘルプ・コンテンツのブック）がカプセル化されます。

HelpBookブックのこの実装によって、レガシーOHJのファイル形式が処理されます。HelpBookクラスは、ディレクトリを調べて、既知の拡張子のファイルを識別し、ヘルプ・システムに追加します。

次の項では、ヘルプ・ブックおよび他のオプション機能を追加する方法について説明します。

• 第C.2.1項「ヘルプ・ブックの構築」

• 第C.2.2項「ヘルプへのブックの追加」

詳細は、oracle.help.library.helpset.HelpSetのAPIドキュメントを参照してください。

C.2.1 ヘルプ・ブックの構築

HelpBookの形式は、ディレクトリ・ベースです。コンストラクタを使用して、ヘルプ・コンテンツ（HTMLトピック・ファイル）のあるディレクトリの場所を指定します。

表C-1 HelpBook()コンストラクタ

コンストラクタ	説明
HelpBook(String baseURL, String baseName, String bookTitle)	baseURLに指定されたディレクトリからデータをロードする、指定されたタイトルのHelpBookを作成します。HelpBookオブジェクトでは、ディレクトリを調べ、指定されたbaseNameの名前が付けられた既知の制御ファイル（TOC、TOK、HHC、HHK、OHTおよびIDX）を識別します。このコンストラクタは、ヘルプ・コンテンツの正確な場所がわかっている場合に使用してください。 パラメータ: baseURL: ヘルプセット・ファイルの正確な場所をURL形式で指定する文字列。 baseName: 指定されたディレクトリ内に見つかった制御ファイルのベース名（たとえば、制御ファイルの名前が、userguide.hhc、userguide.hhkなどである場合、baseNameはuserguideです）。 bookTitle: 複数ブックのヘルプ・システムにおいてブック選択のプルダウン・メニューに表示されるブック名。多くの場合、タイトルはヘルプ作成者が指定します。
HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle)	baseClassおよびdirPathExtに指定されたディレクトリからデータをロードする、指定されたタイトルのHelpBookを作成します。HelpBookオブジェクトでは、ディレクトリを調べ、指定されたbaseNameの名前が付けられた既知の制御ファイル（TOC、TOK、HHC、HHK、OHTおよびIDX）を識別します。このコンストラクタは、アプリケーションの実装を基準としたヘルプ・コンテンツ・ディレクトリの相対パスのみがわかっている場合に使用してください。 パラメータ: baseClass: アプリケーション・クラスの1つ。HelpBookオブジェクトは、このクラスの場所を使用し、ヘルプ・コンテンツ・ディレクトリの場所を決定します。 dirPathExt: baseClassの場所を基準としたヘルプ・コンテンツ・ディレクトリの相対パス。このパラメータの値は、baseClassのあるディレクトリの絶対パスに追加されます。追加により生成されるパスは、ヘルプ・コンテンツ・ディレクトリのパスです。 baseName: 指定されたディレクトリ内に見つかった制御ファイルのベース名（たとえば、制御ファイルの名前が、discoverer.hhc、discoverer.hhkなどである場合、baseNameはdiscovererです）。 bookTitle: 複数ブックのヘルプ・システムにおいてブック選択のプルダウン・メニューに表示されるブック名。多くの場合、タイトルはヘルプ作成者が指定します。

C.2.2 ヘルプへのブックの追加

Bookインスタンスを、HelpBookコンストラクタまたはHelpSetコンストラクタを使用して構築した後、BookをHelpインスタンスに追加する必要があります。ヘルプにブックを追加するには、Helpインスタンスで次のメソッドを呼び出します。

表C-2 addBook()コンストラクタ

コンストラクタ	説明
addBook(Book book)	このメソッドでは、Bookインスタンスがヘルプ・システムに追加されます。Bookに含まれる作成者定義ビューがナビゲータ・ウィンドウに表示され、Bookからのトピックを表示できるようになります。 パラメータ: book: ヘルプ・システムに追加するBookインスタンス。

C.3 Oracle Help for the Web構成ファイルのロケール

Oracle Help for the Web構成ファイル（ohwconfig.xml）のロケールを構成する場合、<locales>セクションに単一のロケールまたは複数のロケールを指定できます。

この構成ファイルの詳細は、第8章「Oracle Help for the Web構成ファイル」を参照してください。

C.3.1 <locale>の子要素である<books>

<books>要素は、Oracle Help for the Webで表示されるコンテンツを指定します。<books>要素には、任意の数のヘルプ・ブック、またはヘルプセットとヘルプ・ブックの組合せを指定できます。ヘルプセットおよびヘルプ・ブックはブックとも呼ばれます。

表C-3に、<helpbook>子要素を示します。

表C-3 <books>の子要素

要素

説明

<helpBook>

このOHWインスタンスに含めるヘルプ・ブック。この要素の属性は、次のとおりです。 id: このブックの一意のID。この属性は必須です。 basename: ディレクトリにある制御ファイルの名前（拡張子を除いた部分）。たとえば、制御ファイルの名前が、myproject.hhc、myproject.hhk、myproject.idxなどの場合、basenameはmyprojectです。 location: ヘルプ・ブック・ファイルの場所。このパスは、OHW構成ファイルの場所を示す絶対パスまたは相対パスを指定できます。 title: ヘルプ・ブックまたはヘルプセットがマージされた場合に使用するタイトル。ヘルプ・ブックは、OHWユーザー・インタフェースのマージされたブック・リストに表示されます。ただし、このタイトルは、ヘルプセットのヘルプセット・ファイルの<title>要素に設定されています。 controlFileencoding: Javaでサポートされるエンコーディング名。サポートされるエンコーディングのセットは、JDKのバージョンに応じて異なります。Java SEでサポートされるエンコーディングのリストについては、http://download.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.htmlを参照してください。

次に例を示します。

<books>
 <helpBook id="disco" baseName="discoverer" location="discoverer/" title="Discoverer Help" />
</books>

<helpbook>には、ヘルプ・トピック・ファイルがOracle Helpの予期していない場所にある場合のために、0（ゼロ）以上の<contentLocation>要素を含めることができます。

<books>の他の子要素の詳細は、第8.4.1項「<books>子要素」を参照してください。

C.3.2 <contentLocation>要素

デフォルトでは、OHWは自動的に、ヘルプ・ブックのベース・ディレクトリと同じ場所にあるヘルプ・トピック・ファイルを処理します。

ヘルプ・ブックでは、OHWは、次の場所にあるヘルプ・トピックHTMLファイルを処理します。

• ヘルプ・ブックのベース・ディレクトリおよびそのサブディレクトリ内。

• ヘルプ・ブックがJARファイルの中にある場合、そのJARファイルに含まれるすべてのヘルプ・トピック・ファイル。

ヘルプ・トピック・ファイルが別の場所にある場合は、<contentLocation>要素を使用してその場所を指す必要があります。

<contentLocation>要素には、baseURI属性があります。この属性は、絶対パスまたは相対パスを使用して、ヘルプ・コンテンツのセットがあるルートの場所のURIを表します。

<contentLocation>要素は、<helpbook>の子要素として指定できます。<helpbook>には、0（ゼロ）以上の<contentLocation>要素を含めることができます。

この要素は必須です。これは、プレーンHTMLファイルとは異なり、Oracle Helpヘルプ・トピック・ファイルの表示には、サーブレットによる処理が必要となるためです。このため、ヘルプ・ブック内で参照されているヘルプ・トピック・ファイルがデフォルトの場所にない場合は、その場所を明示的にリストする必要があります。このことは、ヘルプセットのサブヘルプセットが別の場所や別のWebサーバー上にある場合、または状況依存のマップ・ファイルに、同じサーバー上の別の場所や別のサーバー上にあるヘルプ・トピック・ファイルへの参照が含まれる場合に発生する可能性があります。

詳細は、第8.4.2項「<contentLocation>要素」を参照してください。