この章では、ヘルプ・システムをオンライン形式で表示するために作成するマークアップしたヘルプ・ファイルの処理方法を説明します。また、デスクトップのフロントパネルのヘルプ・ビューアからヘルプ・ボリュームにアクセスする方法も説明します。 ヘルプ・ボリュームを表示するには、DocBook ソフトウェアでファイルを処理し、実行時のヘルプ・ファイルを作成しなければなりません。実行時のファイルは、セマンティッック・デリバリ言語 (SDL - Semantic Delivery Language) と呼ばれるオンライン・プレゼンテーション形式を使用します。実行時のヘルプ・ファイルは、ファイル記述子 .sdl で識別できます。 ユーティリティ dtdocbook は、DocBook 2.2.1 文書型定義 (DTD) の副要素 Part に準拠するドキュメントを受け取り、DtHelp ビューアの入力になることができる SDL 1.2 文書型定義 (DTD) に準拠するドキュメントを出力します。 翻訳では、ドキュメントの実行時の表示速度を向上させるために、いくつかの項目が事前に処理されます。これらの項目には、目次、キーワード索引、相互参照の解決、および順序付けされたリストのラベル付けがあります。翻訳によって出力される SDL に準拠したドキュメントは、デフォルトで圧縮されます。 ヘルプ・システムは、ヘルプ固有ファイルのデスクトップでのアクションとデータ型を定義します。これにより、デスクトップから実行時のヘルプ・ファイルを簡単に処理および表示できます。 DocBookソフトウェアは、ファイル・マネージャでヘルプのソース・ファイルをダブルクリックすると自動的に起動されます。または、手動で dtdocbook コマンドを端末ウィンドウで実行すると起動されます。 dtdocbook には、２つの重要なタスクがあります。 DocBook のパーサは、マークアップされたファイルを、ヘルプ・システムが理解できる内部形式（セマンティック・デリバリ言語）に変換します。マークアップにエラーがある場合は、volume.log というファイルにエラーが報告されます。 パーサのエラーがない場合は、マスタのヘルプ・ボリューム・ファイル (volume.sdl) が作成されます。 DocBook でのソース・ファイルの処理が終了すると、いつでもヘルプ・ボリュームを表示できます。表示するには、ファイル・マネージャで、volume.sdl のファイル・アイコンをダブルクリックするか、端末ウィンドウで dthelpview コマンドを使用します。 アプリケーション用のヘルプを記述していて、そのアプリケーションが使用できる状態であれば、アプリケーションを実行してヘルプを呼び出せば、ヘルプを表示できます。 dtdocbook を実行すると、volume.sgm ファイル、および、エンティティを使用して指定された追加ファイルを読み取ります。また、使用するグラフィック・ファイルが存在するかどうかも確認します。 検索パスに /usr/dt/bin/dtdocbook コマンドがあることを確認してください。（確認方法がわからない場合には、システム管理者に問い合わせてください。） ファイル・マネージャを開き、ディレクトリを volume.sgm ファイルのあるディレクトリに変更します。 ファイル・アイコンを選択します。 ファイル・マネージャの[選択]メニューで[コンパイル]を選択します。 volume.sgm ファイルが処理され、volume.sdl ファイルと volume.log ファイルが作成されます。 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 options volume options が、volume 名の前にあることをみてください。 には、すべての有効なオプションをリストされています。 次のコマンドは、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 は、アプリケーション・インストール・パッケージにどのヘルプ・ファイルが含まれているかを説明しています。 最初のエラー・メッセージは、SGML パーサから出力されます。これらのほとんどは、SGML のシンタクスに関するエラー・メッセージですが、「ファイルがみつからない」という種類のものもあります。 ソース・ファイルを SGML から SDL に翻訳する処理の２つのパスも、シンタクスに関するエラー・メッセージや「ファイルがみつからない」というメッセージを生成しますが、件数は多くありません。２つのパスのうち２番目のパスは、まれにしかエラー・メッセージを発行しません。すべてのシンタクスと内容は、それまでにチェックされてしまうからです。 dtdocbook を実行後、volume.log ファイル（ここで volume は、ユーザのvolume.sgm ファイルのベース名です）の内容をみてください。 ひとつの単純なエラーが、数個のエラー・メッセージを出力する可能性は、おおいにあります。なぜなら、エラーによって、パーサが意図したコンテキストの解析順序を失い、引き続くマークアップを適切に解釈することが不可能になるからです。 処理エラーのほとんどは、以下の一般的なミスによるものです。 終了タグの付け忘れ 間違ったエンティティ名の使用 無効な要素IDの参照 要素に終了タグを付け忘れるのは、よくあるミスです。事実上、すべての DocBook の要素には、終了タグが必要です。リスト内の図のように、複雑な要素を別の要素内に、構造的にネストする場合は、マークアップをチェックしてください。 また、不正確なエンティティ名を使用するとエラーが出力されます。ほとんどの場合、これは単純なスペルミスです。ある場合には、エンティティ名が変更されているにもかかわらず、元の名前への相互参照が、エラーの原因となります。エンティティ名を変更した場合には、ソース・ファイルを検索して、すべてのエンティティ名のインスタンスをチェックすることを忘れないでください。 また、要素に割り当てられたIDを変更すると、あらゆる相互参照やトピックへのリンクに影響するため、エラーが出力されることがあります。IDを変更した場合には、ソース・ファイルを検索して、そのIDのすべてのインスタンスをチェックすることを忘れないでください。 ヘルプ・ビューアは、どのヘルプ・ボリュームでも表示できます。ヘルプ・ビューアは、アプリケーション定義リンクを除く（これはユーザのリンクをどのように解釈すべきかわからないためです）すべての型のハイパーリンクをサポートしています。 アプリケーション用ヘルプを記述していて、そのアプリケーションが使用できる状態であれば、アプリケーションを実行し、ユーザが操作するようにヘルプを呼び出せば、ヘルプを表示できます。 ファイル・マネージャを開き、ディレクトリを volume.sdl ファイルのあるディレクトリに移動します。 アイコンをダブルクリックします。 デフォルトでは、ヘルプ・ビューアを使用してファイルが表示されます。 表示したいボリュームの volume.sdl ファイルが、現在のディレクトリにあるか、または登録されている場合は、次のコマンドを実行します。 dthelpview -helpVolume volume.sdl あるいは、volume.sdl が別のディレクトリにある（そして未登録である）場合は、次のコマンドを実行します。 dthelpview -helpVolume /full-path/ volume.sdl これらのコマンドで、-helpVolume パラメータは、短縮して -h にすることができます。 ヘルプ・ボリュームを編集したばかりとしましょう。まず、DocBook ソフトウェアで、これを処理します。 dtdocbook MyVolume.sgm エラーがなければ、次のコマンドで表示することができます。 dthelpview -h MyVolume.sdl プロジェクト期間中に、自分が開発しているヘルプ・ボリュームにアクセスしたいけれども、システムのすべてのユーザに公開したくはない場合があります。たとえば、作業ディレクトリが、/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 と呼ばれるファイルを作成します。初期作成後は、ボリュームは変更が発生したときのみ更新されます。 索引ボリュームを手動で更新するには、 を参照してください。 索引ボリュームにリストされたどのヘルプ・ボリュームも、ボリューム・タイトルを選択することによって表示することができます。複数の異なるボリュームを表示して、その間を移動できるため、索引ヘルプのウィンドウには、[トップレベル]と呼ばれるボタンが追加されます。このボタンを使用して、ひとつまたは複数のボリュームを表示した後、索引リストに戻ることができます。 デスクトップ・ユーティリティは、どのヘルプ・ボリュームが索引ボリュームに集められているか識別するために、ヘルプ・ファミリ・ファイルを調べます。 の は、索引ボリュームにリストされている「共通デスクトップ環境」と「概要およびデスクトップの基本スキル」という２つのヘルプ・ファミリを示します。各ファミリ・ファイルは、ひとつまたは複数の関連するヘルプ・ボリュームから成ります。たとえば、「共通デスクトップ環境」ファミリには、デスクトップを説明する異なるボリュームが含まれています。 アプリケーションとそのヘルプ・ファイルをデスクトップにインストールする方法の詳細については、『共通デスクトップ環境 上級ユーザおよびシステム管理者ガイド』を参照してください。 プロダクトに独自のファイル名を付けます。ヘルプ・ファミリのファイルであることが識別できるように、拡張子 .hf を使用します。 family.hf 次の行をファイルに入力します。 *.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 には、DocBook マークアップを指定できません。このファイルは、DocBook ソフトウェアでは処理されません。 icon file はオプションです。指定する場合、ファイルの位置を指定するのに使用するパスは絶対パス名でなければなりません。アイコンを付けない場合は、ファミリ・ファイルに *.bitmap リソースを指定しないようにしてください。 volume 名のリストは、そのファミリにどのボリュームが属すのかを識別します。ボリュームは、この行に表示される順番にリストされます。ひとつのボリュームが複数のファミリにリストされることもあります。 いずれかの値が１行を超える場合、最後の行以外の各行を、バックスラッシュ (\) で終わらせます。 ファイル内で ! (感嘆符) で始まる行はコメント行であり、無視されます。 最終的なプロダクトを準備するとき、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 実際にデスクトップ・ソフトウェアに指定されているヘルプ・ファミリが、この図のとおりになっているとはかぎりません。 サポートされている文字セットの名前のリストについては、 を参照してください。 デスクトップのフロントパネルから[ヘルプ・ビューア]コントロールを選択します。 ヘルプ・ウィンドウをスクロールして、システムで使用可能なヘルプ・ファミリを表示します。 必要ならば、ヘルプ・ファミリ・タイトルを選択して、ボリュームを表示します。 ヘルプ・システムに関するヘルプ情報を表示するには、「共通デスクトップ環境」のタイトル、次に「デスクトップ ヘルプ・システム」を選択してください。 dthelpview コマンドを、次のように実行します。 dthelpview -helpVolume index は dthelpview コマンド行をリストしています。 dthelpgen(1) マニュアル・ページ ヘルプ・ボリュームを表示した後、ヘルプ・トピックを印刷することができます。 のダイアログ・ボックスで個々のトピック、目次および索引情報、ヘルプ・ボリューム全体を印刷できます。印刷出力では、グラフィックは省略されます。

テストヘルプハイパーリンクの検証ハイパーリンクハイパーリンクの検証アプリケーションのエントリ・ポイントの検証アプリケーションのエントリ・ポイント、検証アプリケーションのエントリ・ポイント、検証ポイント、エントリ、アプリケーションにおける検証テストさまざまなディスプレイ上のグラフィックグラフィック、さまざまなディスプレイ上のテストディスプレイ、さまざまな〜上のグラフィックのテスト ヘルプ・ボリュームのテストは、他のソフトウェア・プロダクトのテストと同じように重要です。テストを計画するときに役立つヒントをいくつか紹介します。 ヘルプ・ボリュームを表示して、すべてのハイパーリンクを試します。（実線または破線の下線の付いた）テキストは、すべてハイパーリンクです。また、ハイパーリンクになっているすべてのグラフィックもテストします。グラフィック・ハイパーリンクは、ハイパーリンクの印として、イメージの周りに（破線または実線の）隅が開いている枠を使用しています。 アプリケーション固有のヘルプを記述していて JumpNewView、Man、または AppDefined リンクのいずれかを指定した場合は、これらのリンクをアプリケーションからテストしなければなりません。これらのリンクを dthelpview を使用してテストしても、アプリケーション内から正しく動作する保証にはなりません。 特定のヘルプ・トピックへのアクセスにIDを使用するアプリケーション固有のヘルプを記述している場合、IDがヘルプ・ボリューム内で正しく確立されているかを調べる方法は２つあります。 アプリケーションを実行して、ユーザ がするようにヘルプを要求し、エントリ・ポイントをひとつずつ確認します。これにより、アプリケーションが正しいIDを使用しているかという検証もできます。 アプリケーションが（開発中で）まだ使用できない場合は、各IDに対して dthelpview を実行することで、各IDをテストできます。 dthelpview -helpVolume volume.sdl -locationId id id は、テストしたい位置IDです。dthelpview が正しいトピックを表示していれば、そのIDは大丈夫です。 ユーザは、ヘルプ・トピックをみつけるために、ヘルプ・ボリュームの索引を検索したり、ブラウズしたりします。あいまいな用語や重複したエントリがないように、索引エントリも丁寧に検査してください。また、各索引エントリを選択して、表示されるトピックがもっとも適切な情報か検証してください。 グラフィックが、カラー、グレースケール、白黒ディスプレイで表示可能なことを検査するために、物理的にアプリケーションをさまざまなディスプレイで表示します。 デスクトップが使用するカラーの数を変更して、他のディスプレイをシミュレートすることもできます。そのためには、スタイル・マネージャを開き、[色の数]を選択し、異なるカラー・オプションを指定します。