test

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

第 4 章 ヘルプ・ボリュームの処理と表示

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

概要

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

Graphic

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

ヘルプタグ・ソフトウェア

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

ヘルプタグには 2 つの重要なタスクがあります。

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

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

ボリュームの表示

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

Graphic

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

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

ヘルプタグを実行すると、volume.htg ファイル、volume.ctg ファイル、エンティティを使って指定された追加のソース・ファイルを読み取ります。また、使用するグラフィック・ファイルが存在するかどうかも確認します。

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

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

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

    Graphic

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

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

    volume.htg ファイルが処理され、volume.sdl ファイルと volume.err ファイルが作成されます。

ヘルプタグの出力

ヘルプタグの出力先は実行時のヘルプ・ボリュームで、名前は volume.sdl です。処理中に何らかのエラーが発生すると、エラー・ファイル (volume.err) に報告されます。エラーがない場合は、volume.err ファイルには著作権情報といくつかのステータス行が入ります。

helptag.opt ファイルに onerror=go オプションを設定すると、パーサはエラーを検出した後でも (可能であれば) 処理を続行します。onerror=go オプションを設定しないと、パーサは最初のエラーが検出されたところで停止します。volume.sdl ファイルは、ソース・ファイルにエラーがなくなるまでは作成されません。

ヘルプ・トピックを表示するために、volume.sdl ファイルとグラフィック・ファイルがヘルプ・システムに読み取られます。実行時のヘルプ・ファイルは、volume.htg ファイルと同じベース名を持ちます。たとえば、volume.htg ファイル名が Librarian.htg の場合、ヘルプ・ボリューム名は Librarian.sdl です。

注意 - 注意 -

ヘルプタグ実行後は、実行時のヘルプ・ファイルまたはグラフィック・ファイル名を変更しないでください。volume.sdl ファイルに格納される情報は元の名前に基づいています。volume.htg ファイル名を変更する場合は、ヘルプタグを再実行してください。

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

    dthelptag コマンドを次のように実行します。

       dthelptag  command-options  volume  parser-options

    command-options は volume 名の前に入力するオプションで、parser-options は volume 名の後に入力するオプションです。使用できるオプションは、「ヘルプタグ・ファイルの処理 (dthelptag)」にリストされています。

例: コマンド

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

dthelptag MyVolume

-verbose オプションを指定すると、処理の進み具合が画面に表示されます。

dthelptag -verbose MyVolume

検索パスを追加すると、ヘルプタグは graphics という名前の (現在のディレクトリの) サブディレクトリに格納されているファイルを検索できます。

dthelptag -verbose MyVolume search=graphics

例: helptag.opt ファイル

次の例は、オプションが 1 つずつ別の行にあるサンプル helptag.opt ファイルです。これは、ボリュームのドラフト版を作成するのに適した方法です。

memo
onerror=go 
search=graphics/
search=entityFiles/

ヘルプ・ボリュームの最終版を作成する前に、memo と onerror=go の行を削除してください。

関連項目

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

    ヘルプタグ実行後、volume.err ファイルの中身を見てください (volume は volume.htg ファイルのベース名です)。

volume.err ファイルにリストされている各エラーは、アスタリスクの文字列 (*****) で始まっています。たとえば、actions ファイルの 54 行目で次のエラーが検出されました。

*****
Line 54 of actions,
Missing end tag for LIST:
...the execution host becomes the current working directory.

<s2 id=EverythingYouNeedToKnow> E...
Current element is LIST begun on Line 28 of actions.

エラーの状況がわかるように、ファイルの内容が数行表示されています。また、その要素は同じファイルの 28 行目から始まる LIST だというヒントがあります。<s2> はリスト内では許可されないので、設計者が <¥list> 終了タグを入力し忘れたようです。

1 つの単純なエラーがいくつかのエラー・メッセージを生成することがあります。これは、最初のエラーによってパーサが意図していたコンテキストを見失い、その後のマークアップを正しく解釈できなくなったためです。

一般的なエラー

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

要素に終了タグを付け忘れるのはよくあるミスです。リスト、図、注、注意、警告などの要素を作成するときには、必ず終了タグを付けてください。特に、リスト中の図のように、ある要素を他の要素の中にネストした場合は、マークアップを丁寧にチェックしてください。

間違ったエンティティ名を使用するエラーもよく起こります。ほとんどの場合は単なるつづりの間違いです。その他は、エンティティ名が変更されたのに元の名前への相互参照が見落とされた場合です。エンティティ名を変更するときには、ソース・ファイルでそのエンティティ名のすべてのインスタンスを忘れずに検索してください。

同じように、要素に関連付けられた ID を変更すると、そのトピックへの相互参照やリンクに影響します。

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

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

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

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

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

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

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

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

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

       dthelpview -helpVolume volume.sdl

    または、volume.sdl が他のディレクトリにある (そして登録されていない) 場合は、次のコマンドを実行します。

       dthelpview -helpVolume /full-path/volume.sdl

上記のどちらのコマンドでも、-helpVolume パラメータは -h に省略できます。

例

ヘルプ・ボリュームを編集する時には、まず、ヘルプタグ・ソフトウェアで処理します。

dthelptag MyVolume

エラーがなかった場合は、次のコマンドで表示できます。

dthelpview -h MyVolume.sdl

関連項目

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

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

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

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

次に、(ヘルプタグ・ソフトウェアによって作成される) Myvolume.sdl ファイルへのシンボリック・リンクを作成します。

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

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

dthelpview -helpVolume Myvolume

ブラウザ・ボリュームへのヘルプの追加

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

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

図 4-1 ヘルプ・ファミリを表示するブラウザ・ヘルプ・ボリューム

Graphic

ヘルプ・ボリュームをブラウザ・ボリュームで使用できるようにするには、ヘルプ・ファミリ・ファイルを作成します。アプリケーションがデスクトップに登録されてファミリ・ファイルができると、ヘルプ・ボリュームがブラウザ・ボリュームの中に取り込まれます。

ブラウザ・ボリューム

デスクトップ・ユーティリティはブラウザ・ボリュームを作成および更新します。ユーザが初めてフロントパネルの [ヘルプ・ビューア] をクリックすると、このユーティリティが自動的に実行されます。このユーティリティは、ヘルプ検索パス・ディレクトリにあるヘルプ・ボリュームとヘルプ・ファミリ・ファイルを識別します。このユーティリティは、browser.hv というファイルをユーザの HomeDirectory/.dt/help/$DTUSERSESSION ディレクトリに作成します。一度作成された後は、ボリュームは変更があった場合にのみ更新されます。

ブラウザ・ボリュームを手動で更新するには、「ブラウザ・ヘルプ・ボリュームの作成 (dthelpgen)」を参照してください。

ブラウザ・ボリュームにリストされているヘルプ・ボリュームはどれでも、ボリューム・タイトルを選択すれば表示できます。異なるボリュームから表示やナビゲートができるので、ブラウザ・ヘルプ・ウィンドウには [トップレベル] というボタンがあります。1 つまたは複数のボリュームを表示した後に、このボタンを使ってブラウザ・リストに戻ることができます。

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

デスクトップ・ユーティリティは、どのヘルプ・ボリュームがブラウザ・ボリュームに集められているか識別するために、ヘルプ・ファミリ・ファイルを調べます。図 4-1 は、ブラウザ・ボリュームにリストされている「Common Desktop Environment (共通デスクトップ環境)」と「Overview and Basic Desktop Skills (概要とデスクトップの基本スキル)」という 2 つのヘルプ・ファミリを示します。各ファミリ・ファイルは、1 つまたは複数の関連するヘルプ・ボリュームから成ります。たとえば、「Common Desktop Environment (共通デスクトップ環境)」ファミリには、デスクトップを説明する異なったボリュームが含まれています。

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

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

  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 文字列が使用する文字セットです。サポートされている文字セットのリストについては、「フォント・スキーマの理解」を参照してください。family title と family abstract にはヘルプタグ・マークアップを指定できません。このファイルはヘルプタグ・ソフトウェアでは処理されません。

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

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

    いずれかの値が 1 行を超える場合、最後の行以外の各行を ¥ で終わらせます。

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

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

    dtappintegrate スクリプトの実行方法は、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』に説明されています。

例

次の例は、デスクトップのオンライン・ヘルプ用のファミリ・ファイルです。ファイルの最初にあるコメントで、ファミリとリリース・バージョンが識別できます。

!##############################################
!#                                            #
!#          Desktop  Help Family              #
!#                                            #
!#                 Version 1.0                #
!#                                            #
!##############################################
*.charSet:      ISO-8859-1
*.title:        Desktop Version 1.0
*.bitmap:       /usr/dt/appconfig/help/C/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

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

関連項目

ブラウザ・ボリュームを表示するには

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

    Graphic

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

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

注 -

ヘルプ・システムに関するヘルプ情報を参照するには、[デスクトップの紹介] を選択してから [ヘルプの使い方] を選択してください。

手動でブラウザ・ボリュームを表示するには

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

   dthelpview -helpvolume browser

関連項目

ヘルプ・トピックの印刷

ヘルプ・ボリュームを表示した後、ヘルプ・トピックを印刷できます。図 4-2 のダイアログ・ボックスで、個々のトピック、目次および索引情報、ヘルプ・ボリューム全体を印刷できます。印刷出力ではグラフィックは省かれます。

図 4-2 ヘルプの [印刷] ダイアログ・ボックス

Graphic

ヘルプのテスト

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

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

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

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

索引エントリのチェック

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

グラフィックのテスト

パーサ・エラーのチェック

ヘルプ・ボリュームの開発中には、helptag.opt ファイルに onerror＝go オプションを設定していると便利です。指定してある場合は、最終的にはこのオプションを削除してからソース・ファイルを処理し、エラーが 1 つも発生しないことを確認してください。

関連項目