C ヘルプ・ブックの処理

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

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

この付録の内容は次のとおりです。

ヘルプ・ブック・ファイル名の拡張子
OHJへのHelpデータの追加
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`: 複数ブックのヘルプ・システムにおいてブック選択のプルダウン・メニューに表示されるブック名。多くの場合、タイトルはヘルプ作成者が指定します。

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`インスタンス。

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`を参照してください。

<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>要素」を参照してください。