# ヘルプ・ボリュームの処理と表示

この章では、ヘルプ・システムをオンライン形式で表示するために作成するマークアップしたヘルプ・ファイルの処理方法を説明します。また、デスクトップのフロントパネルのヘルプ・ビューアからヘルプ・ボリュームにアクセスする方法も説明します。

HRDC.CrHV.mkr.2
HRDC.CrHV.mkr.3
HRDC.CrHV.mkr.6
HRDC.CrHV.mkr.7
HRDC.CrHV.mkr.8
HRDC.CrHV.mkr.13
HRDC.CrHV.mkr.15

## 概要

ヘルプ・ボリュームを表示するには、DocBook ソフトウェアでファイルを処理し、実行時のヘルプ・ファイルを作成しなければなりません。実行時のファイルは、セマンティッック・デリバリ言語 (SDL - Semantic Delivery Language) と呼ばれるオンライン・プレゼンテーション形式を使用します。実行時のヘルプ・ファイルは、ファイル記述子 `.sdl` で識別できます。

ユーティリティ `dtdocbook` は、DocBook 2.2.1 文書型定義 (DTD) の副要素 Part に準拠するドキュメントを受け取り、DtHelp ビューアの入力になることができる SDL 1.2 文書型定義 (DTD) に準拠するドキュメントを出力します。

翻訳では、ドキュメントの実行時の表示速度を向上させるために、いくつかの項目が事前に処理されます。これらの項目には、目次、キーワード索引、相互参照の解決、および順序付けされたリストのラベル付けがあります。翻訳によって出力される SDL に準拠したドキュメントは、デフォルトで圧縮されます。

ヘルプ・システムは、ヘルプ固有ファイルのデスクトップでのアクションとデータ型を定義します。これにより、デスクトップから実行時のヘルプ・ファイルを簡単に処理および表示できます。

### DocBookソフトウェア

DocBookソフトウェアは、ファイル・マネージャでヘルプのソース・ファイルをダブルクリックすると自動的に起動されます。または、手動で `dtdocbook` コマンドを端末ウィンドウで実行すると起動されます。

`dtdocbook` には、２つの重要なタスクがあります。

1. DocBook のパーサは、マークアップされたファイルを、ヘルプ・システムが理解できる内部形式（セマンティック・デリバリ言語）に変換します。マークアップにエラーがある場合は、volume`.log` というファイルにエラーが報告されます。

2. パーサのエラーがない場合は、マスタのヘルプ・ボリューム・ファイル (volume`.sdl`) が作成されます。

### ボリュームの表示

DocBook でのソース・ファイルの処理が終了すると、いつでもヘルプ・ボリュームを表示できます。表示するには、ファイル・マネージャで、volume`.sdl` のファイル・アイコンをダブルクリックするか、端末ウィンドウで `dthelpview` コマンドを使用します。

アプリケーション用のヘルプを記述していて、そのアプリケーションが使用できる状態であれば、アプリケーションを実行してヘルプを呼び出せば、ヘルプを表示できます。

## 実行時のヘルプ・ファイルの作成

`dtdocbook` を実行すると、volume`.sgm` ファイル、および、エンティティを使用して指定された追加ファイルを読み取ります。また、使用するグラフィック・ファイルが存在するかどうかも確認します。

検索パスに `/usr/dt/bin/dtdocbook` コマンドがあることを確認してください。（確認方法がわからない場合には、システム管理者に問い合わせてください。）

### 実行時のヘルプ・ボリュームを作成するには

1. ファイル・マネージャを開き、ディレクトリを volume`.sgm` ファイルのあるディレクトリに変更します。

2. ファイル・アイコンを選択します。

3. ファイル・マネージャの[選択]メニューで[コンパイル]を選択します。

   volume`.sgm` ファイルが処理され、volume`.sdl` ファイルと volume`.log` ファイルが作成されます。

### DocBook の出力

DocBook は、その入力として、volume`.sgm` を受け取り、いくつかのファイルを出力します。

- もっとも重要なのは、最終的な出力ファイルが、volume`.sdl` という名前の実行時ヘルプ・ボリュームであることです。

- 処理中にエラーが発生すると、それらは、volume`.log` という名前のエラー・ファイルに報告されます。これは、通常、使用後に削除します。

volume`.sdl` ファイルは、ソース・ファイルのエラーがなくなるまで作成されません。

volume`.sdl` ファイル、およびユーザのグラフィック・ファイルは、ヘルプ・トピックを表示するために、ヘルプ・システムによって読み込まれます。

実行時のヘルプ・ファイルは、ユーザの volume`.sgm` ファイルと同じベース名をもちます。たとえば、ユーザのソース・ファイルの名前が、`Librarian.sgm` ならば、ヘルプ・ボリュームの名前は、`Librarian.sdl` になります。

`dtdocbook` ユーティリティは、引き数として単一のファイルを受け付けます。ファイル名が、“`.sgm`” という文字列で終わっていれば、これらの文字列がファイル名の拡張子であることが仮定され、すべての中間ファイル、および最終的な出力ファイルのファイル・ベース名を作成するために、削除されます。

既存の SDL ファイルの圧縮や伸張を要求するために、`dtdocbook -c` または `dtdocbook -d` オプションを指定する場合、入力ファイル名は、ldquo;`.sdl`” という文字列で終わります。もう一度、繰り返すと、これらの文字列はファイル名の拡張子と仮定され、すべての中間ファイルおよび最終的な出力ファイルのファイル・ベース名を作成するために、削除されます。

`-c` オプションが指定され、そのファイルがすでに圧縮されている場合、ファイルは伸張されてから圧縮されます。このアクションは、圧縮された SDL ファイルの集積状態を検証する手段として有用です。

`-d` が指定され、そのファイルがすでに伸張されている場合、、再度の解析とすべての事前計算処理の実行が行われ、ファイルは再度書き込まれます。このアクションは、SDL ファイルの集積状態を検証する手段として有用です。また、たとえば、SDL ファイルを直接編集したことによって再計算が必要になった場合に、個別のヘルプ・トピックのバイト・オフセットを含むそのような再計算を強制的に実行するときにも有用です。

最終的なファイル名の拡張子は、常に “`.sdl`” になります。`dtdocbook -o` オプションが指定された場合には、`dtdocbook -o` への引き数 filename が、与えられた出力ファイル名として使用されます。

`dtdocbook` を実行した後で、実行時ヘルプ・ファイルやグラフィック・ファイルの名前を、決して変更してはいけません。volume`.sdl` ファイルに格納された情報は、元の名前に依存します。volume`.sgm` ファイルやグラフィック・ファイルの名前を変更した場合は、必ず、`dtdocbook` を再実行してください。

### 手動で dtdocbook コマンドを実行するには

- `dtdocbook` コマンドは、次のように実行します。

  `dtdocbook` options volume

  options が、volume 名の前にあることをみてください。HRDC.CmdS.mkr.2 には、すべての有効なオプションをリストされています。

#### コマンド Options.sgm の例

次のコマンドは、`MyVolume` という名前のヘルプ・ボリュームを処理します。

    dtdocbook MyVolume

`-r` オプションを使用すると、`MyVolume.sgm` というソース・ファイルを処理することによって生成されたすべてのファイルが削除されます。

    dtdocbook -r MyVolume.sgm

次のコマンドは、`MyVolume.sgm` という名前のソース・ファイルを処理し、結果を `Other_File.sdl` という名前のファイルに出力します。

    dtdocbook -o Other_File.sdl MyVolume.sgm

`-v` オプションを使用すると、進行状況が画面に表示されます。

    dtdocbook -v MyVolume

#### 関連項目

- HRDC.Inst.mkr.1 は、アプリケーション・インストール・パッケージにどのヘルプ・ファイルが含まれているかを説明しています。

### パーサ・エラーをレビューおよび修正するには

最初のエラー・メッセージは、SGML パーサから出力されます。これらのほとんどは、SGML のシンタクスに関するエラー・メッセージですが、「ファイルがみつからない」という種類のものもあります。

ソース・ファイルを SGML から SDL に翻訳する処理の２つのパスも、シンタクスに関するエラー・メッセージや「ファイルがみつからない」というメッセージを生成しますが、件数は多くありません。２つのパスのうち２番目のパスは、まれにしかエラー・メッセージを発行しません。すべてのシンタクスと内容は、それまでにチェックされてしまうからです。

`dtdocbook` を実行後、volume`.log` ファイル（ここで volume は、ユーザのvolume`.sgm` ファイルのベース名です）の内容をみてください。

ひとつの単純なエラーが、数個のエラー・メッセージを出力する可能性は、おおいにあります。なぜなら、エラーによって、パーサが意図したコンテキストの解析順序を失い、引き続くマークアップを適切に解釈することが不可能になるからです。

#### 一般的なエラー

処理エラーのほとんどは、以下の一般的なミスによるものです。

- 終了タグの付け忘れ

- 間違ったエンティティ名の使用

- 無効な要素IDの参照

要素に終了タグを付け忘れるのは、よくあるミスです。事実上、すべての DocBook の要素には、終了タグが必要です。リスト内の図のように、複雑な要素を別の要素内に、構造的にネストする場合は、マークアップをチェックしてください。

また、不正確なエンティティ名を使用するとエラーが出力されます。ほとんどの場合、これは単純なスペルミスです。ある場合には、エンティティ名が変更されているにもかかわらず、元の名前への相互参照が、エラーの原因となります。エンティティ名を変更した場合には、ソース・ファイルを検索して、すべてのエンティティ名のインスタンスをチェックすることを忘れないでください。

また、要素に割り当てられたIDを変更すると、あらゆる相互参照やトピックへのリンクに影響するため、エラーが出力されることがあります。IDを変更した場合には、ソース・ファイルを検索して、そのIDのすべてのインスタンスをチェックすることを忘れないでください。

## ヘルプ・ボリュームの表示

ヘルプ・ビューアは、どのヘルプ・ボリュームでも表示できます。ヘルプ・ビューアは、アプリケーション定義リンクを除く（これはユーザのリンクをどのように解釈すべきかわからないためです）すべての型のハイパーリンクをサポートしています。

アプリケーション用ヘルプを記述していて、そのアプリケーションが使用できる状態であれば、アプリケーションを実行し、ユーザが操作するようにヘルプを呼び出せば、ヘルプを表示できます。

### ヘルプ・ボリュームを表示するには

1. ファイル・マネージャを開き、ディレクトリを volume`.sdl` ファイルのあるディレクトリに移動します。

2. アイコンをダブルクリックします。

   デフォルトでは、ヘルプ・ビューアを使用してファイルが表示されます。

#### 手動で dthelpview コマンドを実行するには

- 表示したいボリュームの volume`.sdl` ファイルが、現在のディレクトリにあるか、または登録されている場合は、次のコマンドを実行します。

  `dthelpview -helpVolume volume`.sdl``

  あるいは、volume`.sdl` が別のディレクトリにある（そして未登録である）場合は、次のコマンドを実行します。

  `dthelpview -helpVolume /full-path/ volume.sdl`

これらのコマンドで、`-helpVolume` パラメータは、短縮して `-h` にすることができます。

#### 例

ヘルプ・ボリュームを編集したばかりとしましょう。まず、DocBook ソフトウェアで、これを処理します。

    dtdocbook MyVolume.sgm

エラーがなければ、次のコマンドで表示することができます。

    dthelpview -h MyVolume.sdl

#### 関連項目

- HRDC.Inst.mkr.9

#### 例: 個人用ヘルプ・ディレクトリ

プロジェクト期間中に、自分が開発しているヘルプ・ボリュームにアクセスしたいけれども、システムのすべてのユーザに公開したくはない場合があります。たとえば、作業ディレクトリが、`/projects/help` で、ヘルプ・ボリュームが `Myvolume` という名前だとします。

まず、ボリュームを登録できるホーム・ディレクトリに個人用ヘルプ・ディレクトリを作成します。

    mkdir -p $HOME/.dt/help/C

次に（DocBook ソフトウェアによって作成される）`Myvolume.sdl` ファイルへのシンボリック・リンクを作成します。

    ln -s /projects/help/Myvolume.sdl $HOME/.dt/help/C/Myvolume.sdl

これで（現在のディレクトリとは無関係に）ボリュームを次のコマンドで表示できます。これは、ホーム・ディレクトリ内の `.dt/help/C` ディレクトリは、ヘルプ・システムがヘルプ・ボリュームを検索するときに最初に参照するからです。

    dthelpview -helpVolume Myvolume.sdl

## 索引ボリュームへのヘルプの追加

デスクトップは、索引ボリュームと呼ばれる特別なヘルプ・ボリュームを提供しています。索引ボリュームには、システムで使用可能なヘルプ・ボリュームがリストされます。索引ボリュームは、フロントパネルで、[ヘルプ・ビューア]コントロールをクリックすると表示されます。

索引ボリュームから各種のヘルプ・ボリュームを直接表示できます。これにより、アプリケーションを起動しなくても、アプリケーション固有のヘルプにアクセスできます。また、スタンドアロン・ヘルプを記述している場合は、ユーザがそのヘルプを得られる唯一の方法です。

### ヘルプ・ファミリを表示する索引ヘルプ・ボリューム

ヘルプ・ボリュームを索引ボリュームで使用可能にするには、ヘルプ・ファミリ・ファイルを作成します。アプリケーションがデスクトップに登録されている場合には、ファミリ・ファイルの存在によって、ヘルプ・ボリュームが索引ボリュームに取り込まれます。

### 索引ボリューム

デスクトップ・ユーティリティは、索引ボリュームの作成および更新を行います。ユーザが、初めてフロントパネルのヘルプ・ビューアをクリックすると、ユーティリティが自動的に実行されます。これは、ヘルプ検索パスのディレクトリにあるヘルプ・ボリュームとヘルプ・ファミリ・ファイルを識別します。ユーザの `HomeDirectory/.dt/help/$DTUSERSESSION` ディレクトリにある `index.hv` と呼ばれるファイルを作成します。初期作成後は、ボリュームは変更が発生したときのみ更新されます。

索引ボリュームを手動で更新するには、HRDC.CmdS.mkr.5 を参照してください。

索引ボリュームにリストされたどのヘルプ・ボリュームも、ボリューム・タイトルを選択することによって表示することができます。複数の異なるボリュームを表示して、その間を移動できるため、索引ヘルプのウィンドウには、[トップレベル]と呼ばれるボタンが追加されます。このボタンを使用して、ひとつまたは複数のボリュームを表示した後、索引リストに戻ることができます。

### ヘルプ・ファミリ・ファイル

デスクトップ・ユーティリティは、どのヘルプ・ボリュームが索引ボリュームに集められているか識別するために、ヘルプ・ファミリ・ファイルを調べます。HRDC.CrHV.mkr.9 の HRDC.CrHV.mkr.9 は、索引ボリュームにリストされている「共通デスクトップ環境」と「概要およびデスクトップの基本スキル」という２つのヘルプ・ファミリを示します。各ファミリ・ファイルは、ひとつまたは複数の関連するヘルプ・ボリュームから成ります。たとえば、「共通デスクトップ環境」ファミリには、デスクトップを説明する異なるボリュームが含まれています。

アプリケーションとそのヘルプ・ファイルをデスクトップにインストールする方法の詳細については、『共通デスクトップ環境 上級ユーザおよびシステム管理者ガイド』を参照してください。

### ヘルプ・ファミリを作成するには

1. プロダクトに独自のファイル名を付けます。ヘルプ・ファミリのファイルであることが識別できるように、拡張子 `.hf` を使用します。

   `family.hf`

2. 次の行をファイルに入力します。

       *.charSet:           character-set
       *.title:        family title
       *.bitmap:       icon file
       *.abstract:     family abstract
       *.volumes:      volume volume volume ...

   character-set は、family title 文字列と family abstract 文字列が使用する文字セットです。サポートされている文字セットのリストについては、HRDC.Lang.mkr.11 を参照してください。family title と family abstract には、DocBook マークアップを指定できません。このファイルは、DocBook ソフトウェアでは処理されません。

   icon file はオプションです。指定する場合、ファイルの位置を指定するのに使用するパスは絶対パス名でなければなりません。アイコンを付けない場合は、ファミリ・ファイルに `*.bitmap` リソースを指定しないようにしてください。

   volume 名のリストは、そのファミリにどのボリュームが属すのかを識別します。ボリュームは、この行に表示される順番にリストされます。ひとつのボリュームが複数のファミリにリストされることもあります。

   いずれかの値が１行を超える場合、最後の行以外の各行を、バックスラッシュ (`\`) で終わらせます。

   ファイル内で `!` (感嘆符) で始まる行はコメント行であり、無視されます。

3. 最終的なプロダクトを準備するとき、family`.hf` ファイルと残りのヘルプ・ファイルをインストールしてください。デスクトップ統合スクリプト (`dtappintegrate`) は、実行されると、ファミリ・ファイルへのシンボリック・リンクを作成します。

   `dtappintegrate` スクリプトの実行方法は、共通デスクトップ環境 上級ユーザおよびシステム管理者ガイドで説明しています。

#### 例

次の例は、デスクトップのオンライン・ヘルプ用のファミリ・ファイルです。

    *.charSet:      ISO-8859-1
    *.title:        Common Desktop Environment
    *.bitmap:       /usr/dt/appconfig/help/C/graphics/cdelogo.pm
    *.abstract:     Overview and Basic Desktop Skills \
                    * File Manager and the Desktop \
                    * Front Panel \
                    * Application Manager \
                    * Style Manager \
                    * Text Editor \
                    * Mailer
    *.volumes: Intromgr.sdl Filemgr.sdl FPanel.sdl
               Appmanager.sdl Stylemgr.sdl
               Textedit.sdl Mailer.sdl

実際にデスクトップ・ソフトウェアに指定されているヘルプ・ファミリが、この図のとおりになっているとはかぎりません。

#### 関連項目

- サポートされている文字セットの名前のリストについては、HRDC.Lang.mkr.5 を参照してください。

### 索引ボリュームを表示するには

1. デスクトップのフロントパネルから[ヘルプ・ビューア]コントロールを選択します。

2. ヘルプ・ウィンドウをスクロールして、システムで使用可能なヘルプ・ファミリを表示します。

3. 必要ならば、ヘルプ・ファミリ・タイトルを選択して、ボリュームを表示します。

ヘルプ・システムに関するヘルプ情報を表示するには、「共通デスクトップ環境」のタイトル、次に「デスクトップ ヘルプ・システム」を選択してください。

#### 手動で索引ボリュームを表示するには

- `dthelpview` コマンドを、次のように実行します。

      dthelpview -helpVolume index

#### 関連項目

- hrdc.cmds.mkr.4 は `dthelpview` コマンド行をリストしています。

- `dthelpgen`(1) マニュアル・ページ

## ヘルプ・トピックの印刷

ヘルプ・ボリュームを表示した後、ヘルプ・トピックを印刷することができます。 HRDC.CrHV.mkr.14 のダイアログ・ボックスで個々のトピック、目次および索引情報、ヘルプ・ボリューム全体を印刷できます。印刷出力では、グラフィックは省略されます。

### ヘルプの印刷ダイアログ・ボックス

## ヘルプのテスト

ヘルプ・ボリュームのテストは、他のソフトウェア・プロダクトのテストと同じように重要です。テストを計画するときに役立つヒントをいくつか紹介します。

### ハイパーリンクの妥当性テスト

- ヘルプ・ボリュームを表示して、すべてのハイパーリンクを試します。（実線または破線の下線の付いた）テキストは、すべてハイパーリンクです。また、ハイパーリンクになっているすべてのグラフィックもテストします。グラフィック・ハイパーリンクは、ハイパーリンクの印として、イメージの周りに（破線または実線の）隅が開いている枠を使用しています。

- アプリケーション固有のヘルプを記述していて `JumpNewView`、`Man`、または `AppDefined` リンクのいずれかを指定した場合は、これらのリンクをアプリケーションからテストしなければなりません。これらのリンクを `dthelpview` を使用してテストしても、アプリケーション内から正しく動作する保証にはなりません。

### エントリ・ポイントの確認

特定のヘルプ・トピックへのアクセスにIDを使用するアプリケーション固有のヘルプを記述している場合、IDがヘルプ・ボリューム内で正しく確立されているかを調べる方法は２つあります。

- アプリケーションを実行して、ユーザ がするようにヘルプを要求し、エントリ・ポイントをひとつずつ確認します。これにより、アプリケーションが正しいIDを使用しているかという検証もできます。

- アプリケーションが（開発中で）まだ使用できない場合は、各IDに対して `dthelpview` を実行することで、各IDをテストできます。

      dthelpview -helpVolume volume.sdl -locationId id

  id は、テストしたい位置IDです。`dthelpview` が正しいトピックを表示していれば、そのIDは大丈夫です。

### 索引エントリのチェック

ユーザは、ヘルプ・トピックをみつけるために、ヘルプ・ボリュームの索引を検索したり、ブラウズしたりします。あいまいな用語や重複したエントリがないように、索引エントリも丁寧に検査してください。また、各索引エントリを選択して、表示されるトピックがもっとも適切な情報か検証してください。

### グラフィックのテスト

- グラフィックが、カラー、グレースケール、白黒ディスプレイで表示可能なことを検査するために、物理的にアプリケーションをさまざまなディスプレイで表示します。

- デスクトップが使用するカラーの数を変更して、他のディスプレイをシミュレートすることもできます。そのためには、スタイル・マネージャを開き、[色の数]を選択し、異なるカラー・オプションを指定します。

#### 関連項目

- HRDC.CmdS.mkr.5