共通デスクトップ環境プログラマーズ・ガイド (ヘルプ・システム編)

新規にヘルプ・ボリュームを記述する例

通常は help ディレクトリの中にヘルプ・ファイルを入れます。この例では、スタンドアロンのヘルプ・ボリュームの作成および表示方法について示しています。(スタンドアロンのボリュームの場合は、アプリケーションとの対話はありません。)

ヘルプ・ボリュームを作成および処理するには、次の手順に従ってください。

ヘルプ・ファイル用のソース・ディレクトリを作成します。

ビルド・ディレクトリを作成します。

マスタ・ヘルプタグ・ファイルを作成します。

helptag.opt ファイルを作成します。

実行時のヘルプ・ファイルを作成します。

ヘルプ・ボリュームを表示します。

各タスクについては、次からの節で説明します。テキスト・ファイルで使用されているマークアップ言語については、この章で後述します。ヘルプタグのマークアップについては、第 3 章「ヘルプ・トピックの記述」と第 5 章「ヘルプタグ・マークアップのリファレンス」でさらに詳しく説明します。

ソース・ディレクトリの作成

ヘルプ・ファイルを作成および処理する helpfiles という名前のディレクトリを作成します。

作成したばかりのディレクトリに Commands という名前のテキスト・ファイルを作成します。

この例では、すべての情報は単一のファイルに格納されます。通常、ヘルプを記述しているシステムやアプリケーションについて完全に説明するためには複数のファイルを使用します。

Commands ファイルには、テキストと要素のタグが入っています。< と > (三角括弧) の内側にある要素のタグは、情報の構造を示します。

Commands ファイルに次のマークアップ・テキストを入力します。

  <hometopic>  Command Summary
                         <idx|commands|

 Your &product; is capable of the following operations:
<list bullet>
  * <xref ChannelChange>
  * <xref VolumeUp>
  * <xref VolumeDown>
  * <xref VolumeMute>
 <¥list>

 Choose one of the hyperlinks (underlined phrases)
 to find out how to perform that operation.

 <s1 id=ChannelChange>  Changing the Channel
                         <idx|channel, changing|
 Speak the command:
 <ex> channel<¥ex>
 followed by a number from one to ninety nine.
 <s1 id=VolumeUp>  Turning Up the Volume
                         <idx|volume, changing|
 Speak the command:
 <ex> volume up<¥ex>

 For additional volume, speak the command:
 <ex> more<¥ex>

 (See also <xref VolumeDown> )

 <s1 id=VolumeDown> Turning Down the Volume
                         <idx|volume, changing|
 Speak the command:
 <ex> volume down<¥ex>

 To further reduce the volume, speak the command:
 <ex> more<¥ex>

 (See also <xref VolumeUp>  and <xref VolumeMute> )

 <s1 id=VolumeMute> Turning Off the Sound
                         <idx|volume, changing|
                         <idx|sound, on/off|
 Speak the command:
 <ex> sound off<¥ex>

 To restore the sound, speak the command:
 <ex> sound on<¥ex>

 (See also <xref VolumeDown>  and <xref VolumeUp> )

情報にタイトルを付け、著作権情報と、オンライン・ヘルプに関する他の情報を提供するテキスト・ファイルを作成します。

この例では、Commands ファイルと同じディレクトリにある Metainfo という名前のファイルに次のテキストが格納されます。
```
<metainfo>
      <title> Using the &product;
      <copyright>
      &copy; 1995 Voice Activation Company.  All rights reserved.
      <abstract> Help for Using the &product;.
 <¥metainfo> 
```

ビルド・ディレクトリの作成

helpfiles ディレクトリに build という名前のサブディレクトリを作成します。

マスタ・ヘルプタグ・ファイルの作成

build サブディレクトリに、名前が volume.htg のような形式になるテキスト・ファイルを作成します。この例では、ファイルは voiceact.htg です。

.htg ファイルで、Commands ファイルと Metainfo ファイルの名前とエンティティ名とを関連付けるエンティティを定義します。また、Commands ファイルと Metainfo ファイルで (直接的にまたは間接的に) 使用されているエンティティも定義します。最後に、それぞれのエンティティ名で Commands ファイルと Metainfo ファイルを参照します。

この例では、voiceact.htg ファイルの内容は次のようになります。 内のテキストはコメントですので、無視されます。

<!-- Declare an entity for each of the source text files. -->
<!entity MetaInformation     FILE   "Metainfo">
<!entity Commands            FILE   "Commands">

<!-- Define an entity that names the product and includes
        the trademark symbol (&tm;). -->

<!entity product  "VoAc&tm; Voice-Activated Remote Control">

<!-- Include the text files. -->

&MetaInformation;
&Commands;

helptag.opt ファイルの作成

build サブディレクトリに、helptag.opt という名前のファイルを作成し、次のテキストをそのファイルに格納します。この情報はヘルプタグのオプションを選択し、FILE エンティティの宣言で定義されたファイルをどこから検索すべきかを示します。
```
   onerror=go
memo
search=./
search=../
```
onerror=go オプションは、エラーが発生した場合でもヘルプタグ・ソフトウェアが入力ファイルを処理し続けるように指示します。パーサ・オプションの説明については、「パーサ・オプション」を参照してください。パーサ・オプションの一覧と詳細は、dthelptag(1) のマニュアル・ページを参照してください。

端末エミュレータで次のコマンドを入力し、/usr/dt/bin ディレクトリが検索パスにあるか確認します。
```
   echo $PATH
```
そのディレクトリがパスにない場合は、PATH 環境変数に追加します。追加方法がよくわからない場合は、システムのドキュメントを参照するかシステム管理者に問い合わせてください。

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

ファイル・マネージャを開き、build サブディレクトリに移動します。voiceact.htg ファイルのアイコンを選択し、ファイル・マネージャの [選択] メニューから [コンパイル] を選択します。

この手順により、実行時のバージョンのオンライン・ヘルプ・ボリューム (voiceact.sdl) を作成するヘルプタグ・ソフトウェアが実行されます。ステータスとエラー・メッセージが新規ファイルに格納され、volume.err のような形式の名前が付けられます。

voiceact.err ファイルを開き、エラーもなくファイルが処理されていることを確認します。エラーが発生している場合、必要に応じてテキスト・ファイルの編集および名前の変更を行なって修正します。

注 -
端末エミュレータで、ヘルプタグを手動で実行することもできます。

そのためには、次のコマンドを実行します。
```
   dthelptag -verbose voiceact.htg
```
-verbose オプションは、画面にその経過状況を表示するようにヘルプタグに通知します。

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

build サブディレクトリから、voiceact.sdl ファイルのアイコンをダブルクリックします。

この手順により、デスクトップの [ヘルプ・ビューア] を使用してヘルプ・ボリュームが表示されます。情報をスクロールしたり、[ハイパーリンク] を選択して関連情報へジャンプできます。

注 -

端末エミュレータで、ヘルプ・ビューアを手動で実行することもできます。

そのためには、次のコマンドを実行します。新しいヘルプ・ボリュームが表示されます。

dthelpview -h voiceact.sdl