# 「ヘルプの使い方」の作成

この章では、ヘルプ・システムの機能とその使用方法を記述するヘルプ・ボリュームをアプリケーションに組み込む方法について説明します。このヘルプ・ボリュームは、ヘルプ・ダイアログ・ボックスの使い方に関するヘルプを提供します。

HRDC.H4Hlp.mkr.2
HRDC.H4Hlp.mkr.3
HRDC.H4Hlp.mkr.4
HRDC.H4Hlp.mkr.5
HRDC.H4Hlp.mkr.6
HRDC.H4Hlp.mkr.7

## 「ヘルプの使い方」の作成

「ヘルプの使い方」はヘルプ・システムの使用方法を通知します。特に、ハイパーリンクの使用、トピックのナビゲート、索引の使用、およびヘルプ・トピックの印刷などの作業について説明します。通常は、「ヘルプの使い方」は Help4Help という名前の個別のヘルプ・ボリュームとして提供されます。

Help4Help ボリュームとそのソース・ファイルは開発者用ツールキットに組み込まれています。デフォルト・ボリュームを「そのまま」使用するか、アプリケーションの設計に合わせてそれを変更することができます。

### アプリケーション・ヘルプの場合

アプリケーション特定のヘルプを記述する場合、アプリケーションのヘルプ・ダイアログに [ヘルプの使い方] を追加する方法には、次の２種類があります。

- デスクトップ上の「ヘルプの使い方」ボリュームを使用する。 たとえば、デスクトップを実行しているワークステーションには、標準の Help4Help ボリュームがインストールされます。

- 独自の「ヘルプの使い方」ボリュームを作成する。 Help4Help ボリュームの DocBook ソース・ファイルは、Ｃロケールの場合、`/usr/dt/dthelp/help4help/C` ディレクトリに作成されます。このディレクトリ内で Help4Help を実行して実行時のヘルプ・ファイルを作成してください。「ヘルプの使い方」ボリュームで使用されているグラフィック・ファイルは、`graphics` サブディレクトリに格納されます。

### スタンドアロン・ヘルプの場合

スタンドアロン・ヘルプを記述する場合、すでにインストールされ使用準備ができているヘルプビュー・プログラムを使用します。この場合、ヘルプビューは、デフォルトとして標準の Help4Help ボリュームにアクセスするので、「ヘルプの使い方」について心配する必要はありません。

### 「ヘルプの使い方」の検索方法

ヘルプ・システム（ヘルプビューを含む）を使用する各アプリケーションは、「ヘルプの使い方」トピックのためにアクセスされるヘルプ・ボリュームを識別する `helpOnHelpVolume` リソースをもっています。ヘルプビューの場合、このリソースは次のように設定されます。

    DtHelpview*helpOnHelpVolume:  Help4Help

独自の「ヘルプの使い方」ボリュームを作成する場合、システムにインストールされる可能性のある別の「ヘルプの使い方」ボリュームと競合しないように固有の名前を付けるようにしてください。

## アプリケーションの「ヘルプの使い方」へのアクセス

アプリケーションは「ヘルプの使い方」をサポートするために次のことを行います。

- `helpOnHelpVolume` リソースを設定し、アクセスしたいヘルプ・ボリュームを識別します。

- `Using Help` コマンドを、アプリケーションの[ヘルプ]メニューに追加します。

### helpOnHelpVolume リソースを設定するには

1. 次のように、アプリケーションのデフォルトのリソース・ファイルに１行追加します。

   App-class* `helpOnHelpVolume`: volume

   App-class はアプリケーションのクラス名で、volume はアクセスしたい「ヘルプの使い方」ボリュームの名前です。

   またはアプリケーション内で、作成した各ヘルプ・ダイアログ `helpOnHelpVolume` リソースを設定します。

#### 例

- `dthelpview` のデフォルトのリソース・ファイル (`DtHelpview`) にある次の行は、「ヘルプの使い方」ボリュームを指定します。

      DtHelpview*helpOnHelpVolume:  Help4Help

- ヘルプ・ダイアログの作成中に「ヘルプの使い方」ボリュームを作成するには、次のように作成関数に渡された引き数のリストに追加します。

      ac = 0;
      XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
      XtSetArg (al[ac], DtNhelpOnHelpVolume, "Help4Help"); ac++;
      helpDialog = DtCreateHelpDialog (parent, "helpDialog", al, ac);

### [ヘルプの使い方] コマンドを指定するには

1. [ヘルプ]メニューに`[ヘルプの使い方]`というラベルのボタンを追加します。また、必要な起動コールバックを起動して、`HelpRequestCB()` 関数を呼び出します。

2. `HelpRequestCB()` 関数にサポートを追加し、「ヘルプの使い方」を表示します。特に、次のことを実行します。

   - 簡易ヘルプ・ダイアログを作成する。

   - ダイアログのタイトルを「ヘルプの使い方」に設定する。

   - 「ヘルプの使い方」ボリュームのホーム・トピックを表示する。

   - 簡易ヘルプ・ダイアログを管理する。

#### 例

次の行は、`HelpRequestCB()` 関数を呼び出す `[ヘルプの使い方 …]` というラベルのメニュー・ボタンを作成します。

    /* Create the "ヘルプの使い方 ..." button. */
    labelStr = XmStringCreateLtoR ("使い方 ...",
    XmSTRING_DEFAULT_CHARSET);
    ac = 0;
    XtSetArg (al[ac], XmNlabelString, labelStr);     ac++;
    button = XmCreatePushButtonGadget (parent, "usingHelpButton", al,
    ac);
       XtManageChild (button);
       XmStringFree (labelStr);
       /* Add a callback to the button. */
       XtAddCallback (button,XmNactivateCallback,HelpRequestCB,
       USING_HELP);

`USING_HELP` は、ユーザがメニュー・ボタンを選択したときに `HelpRequestCB()` 関数に渡されるクライアント・データです。アプリケーションの別の場所（たとえば `Help.h` ファイル）で固有の整数として定義します。 integer:

    #define USING_HELP  47

`HelpRequestCB()` 関数が `USING_HELP` を処理する方法を確認するには、次の「ヘルプの使い方」を表示するには」にある例を参照してください。

### 「ヘルプの使い方」を表示するには

1. 簡易ヘルプ・ダイアログを作成します（またはキャッシュから取り出します）。

2. ダイアログに「ヘルプの使い方」ボリュームのホーム・トピックを表示します。

「ヘルプの使い方」は、一般ヘルプ・ウィンドウに表示できます。しかし、簡易ヘルプ・ダイアログのユーザ・インタフェースはもっと単純なので簡易ヘルプ・ダイアログを使用するようにしてください。このダイアログは、通常「ヘルプの使い方」を必要とする新しいユーザでも容易に使えるものです。

#### 例

次のプログラム・セグメントは、`HelpRequestCB()` 関数の一部です。仮定として、ユーザは、アプリケーションの[ヘルプ]メニューから[ヘルプの使い方]を選択するか、簡易ヘルプ・ダイアログの[ヘルプ]ボタンを選択するため、`USING_HELP` 定数は、その関数に渡されます。

次の例は、アプリケーションが[ヘルプの使い方]ダイアログをひとつしか作成せず、そのウィジェットIDを onHelpDialog と呼ばれる変数に保持するものと仮定しています。

    case USING_HELP:
       if (onHelpDialog == (Widget)NULL)
         {
            /* Get a quick help dialog for use as the "help on help" dialog. */
            onHelpDialog = FetchHelpDialog (True);
            if (onHelpDialog == (Widget)NULL)
              /* We didn't get a dialog! Add your error handling code here. */
         }
       /* Set the proper volume and ID to display the home topic of the help on help volume. Also, set the dialog's title. */
       ac = 0;   XtSetArg (al[ac], XmNtitle,  "Help On Help");     ac++;
       XtSetArg (al[ac], XmNhelpType,   DT_HELP_TYPE_TOPIC); ac++;
       XtSetArg (al[ac], XmNhelpVolume, "Help4Help");        ac++;
       XtSetArg (al[ac], XmNlocationId, "_hometopic");       ac++;
       XtSetValues (onHelpDialog, al, ac);
       /* If the "help on help" dialog is already managed, it might be in another workspace, so unmanage it. */
       if (XtIsManaged (onHelpDialog))
         XtUnmanageChild (onHelpDialog);

       /* Manage the "help on help" dialog. */
       XtManageChild (onHelpDialog);

       break;

`HelpRequestCB()` 関数の残りの構成方法を確認するには、 HRDC.HReq.mkr.10 を参照してください。

#### 関連項目

- HRDC.CrDia.mkr.7

- HRDC.HReq.mkr.5

## 独自の「ヘルプの使い方」ボリュームを記述する

独自の「ヘルプの使い方」ボリュームを作成する必要がある場合、既存の Help4Help ボリュームで開始し、必要な変更を行ってください。Help4Help ボリュームを記述するのに使用されるソース・ファイルは、すべて `/usr/dt/dthelp/help4help/C` ディレクトリに用意されています。

インストールの重複を避けるには、「ヘルプの使い方」ボリュームに Help4Help 以外の名前を付けます。ユーザのプロダクトに固有の名前を選ぶようにしてください。たとえば、アプリケーションのヘルプ・ボリュームが Newapp の場合は、「ヘルプの使い方」ボリュームは NetwappH4H という名前にします。

### 必須のエントリ・ポイント

ヘルプ・ダイアログのコンテキスト・ヘルプを正しく動作させるには、「ヘルプの使い方」ボリュームに、次のエントリ・ポイント（ID）を作成しなければなりません。（これらは、すでに Help4Help ソース・ファイルにあります。）

ID | トピック記述
`_hometopic` | ヘルプ・システムの使い方に関するイントロダクションを表示します。このトピックは、一般ヘルプ・ダイアログの[ヘルプ]メニューから[ヘルプの使い方]を選択したり、簡易ヘルプ・ダイアログ・の[F1]キーを押すと、表示されます。このIDは、PartIntro のために自動的に生成されるので、明示的に指定しないようにしてください。
`_copyright` | 「ヘルプの使い方」ボリュームに関する商標とバージョン情報を表示します。このトピックは、一般ヘルプ・ダイアログの[ヘルプ]メニューから[バージョン]を選択すると表示されます。このIDは、LegalNotice のために自動的に生成されるので、明示的に指定しないようにしてください。
`history` | [ヒストリ]ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ]を選択するか、[ヒストリ]ダイアログの[F1]キーを押すと表示されます。
`printing` | [印刷]ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ]を選択するか、[印刷]ダイアログの[F1]キーを押すと表示されます。
`index-search` | [索引検索]ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ]を選択するか、[索引検索]ダイアログの[F1]キーを押すと表示されます。
`volume-select` | [検索ボリューム選択]ダイアログの使用方法を記述しているトピックを表示します。このトピックは、[ヘルプ]を選択するか、[検索ボリューム選択]ダイアログの[F1]キーを押すと表示されます。

### Help4Help ソース・ファイルをコピーするには

1. 次のようにコマンドを使用して、`/usr/dt/dthelp/help4help/C` ディレクトリ全体を新しい作業ディレクトリ ( new-dir) にコピーします。

   `cp -r /usr/dt/dthelp/help4help/C new-dir`

   これは new-dir を作成し、すべてのファイルとディレクトリをその中にコピーします。

2. ファイル（読み取り専用としてコピーされる）の編集を可能にするには、次のようにコマンドを使用してアクセス権を変更します。

       chmod -R u+w new-dir

Help4Help ボリュームは、これらの DocBook ソース・ファイルを使用します。

- `MetaInfo.sgm`

- `Toc.sgm`

- `Tasks.sgm`

- `Home.sgm`

- `Concepts.sgm`

- `Ref.sgm`

- `Appendix.sgm`

グラフィック・ファイルは、`graphics` サブディレクトリに保存されます。

DocBook を実行する前に `Help4Help.sgm` ファイルの名前が変更されていることを確認してください。「ヘルプの使い方」ボリュームの名前は、他の「ヘルプの使い方」ボリュームと重複しないように、固有の名前でなければなりません。

#### 例

次のコマンドは「ヘルプの使い方」ボリュームのコピーを作成し、そのファイルを書き込み可能にします。（`projects` サブディレクトリがすでに存在していると仮定しています。）

    cp -r /usr/dt/dthelp/help4help/C /users/dex/projects/NewHelp4Help
    chmod -R u+w /users/dex/projects/NewHelp4Help

実行時のヘルプ・ファイルの新しいバージョンを作成するには、最初にディレクトリ `/usr/dt/bin` が検索パス内にあることを確認します。次に、新規ディレクトリに移動し、`Help4Help.sgm` ファイルの名前を変更し、DocBook を実行します。

    cd /users/dex/projects/NewHelp4Help
    mv Help4Help.sgm NewH4H.sgm
    dtDocBook NewH4H

DocBook ソフトウェアを実行すると、次のコマンドを使用して新しい「ヘルプの使い方」ボリュームを表示できます。

`dthelpview -helpVolume NewH4H`