この章では、ヘルプ・システムをオンライン形式で表示するために作成するマークアップしたヘルプ・ファイルの処理方法を説明します。また、デスクトップのフロントパネルのヘルプビューアからヘルプ・ボリュームにアクセスする方法も説明します。
ヘルプ・ボリュームを表示するには、ヘルプタグ・ソフトウェアでファイルを処理し、実行時のヘルプ・ファイルを作成しなければなりません。実行時のファイルは、セマンティック・デリバリ言語 (Semantic Delivery Language) と呼ばれるオンライン・プレゼンテーション形式を使用します。実行時のヘルプ・ファイルは、ファイル拡張子 .sdl で識別できます。
ヘルプ・システムは、ヘルプ固有ファイルのデスクトップでのアクションとデータ型を定義します。これにより、デスクトップから実行時のヘルプ・ファイルを簡単に処理および表示できます。
ヘルプタグ・ソフトウェアは、ファイル・マネージャでヘルプのソース・ファイルをダブルクリックすると自動的に起動されます。または、手動で dthelptag コマンドを端末ウィンドウで実行すると起動されます。
ヘルプタグには 2 つの重要なタスクがあります。
ヘルプタグのパーサは、マークアップされたファイルを、ヘルプ・システムが理解できる内部形式 (セマンティック・デリバリ言語) に変換します。マークアップにエラーがある場合は、volume.err というファイルにエラーが報告されます。
パーサのエラーがない場合はマスタのヘルプ・ボリューム・ファイル (volume.sdl)が作成されます。
ヘルプタグでのソース・ファイルの処理が終わると、いつでもヘルプ・ボリュームを表示できます。表示するには、ファイル・マネージャで volume.sdl のファイル・アイコンをダブルクリックするか、端末ウィンドウで dthelpview コマンドを使用します。
アプリケーション用のヘルプを記述していて、そのアプリケーションが使用できる状態であれば、アプリケーションを実行してヘルプを呼び出せばヘルプを表示できます。
ヘルプタグを実行すると、volume.htg ファイル、volume.ctg ファイル、エンティティを使って指定された追加のソース・ファイルを読み取ります。また、使用するグラフィック・ファイルが存在するかどうかも確認します。
検索パスに /usr/dt/bin/dthelptag コマンドがあることを確認してください (確認の仕方がわからない場合は、システム管理者に問い合わせてください)。
ファイル・マネージャを開き、ディレクトリを volume.htg ファイルのあるディレクトリに変更します。
ファイル・アイコンを選択します。
ファイル・マネージャの [選択] メニューで [コンパイル] を選択します。
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 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
次の例は、オプションが 1 つずつ別の行にあるサンプル helptag.opt ファイルです。これは、ボリュームのドラフト版を作成するのに適した方法です。
memo onerror=go search=graphics/ search=entityFiles/
ヘルプ・ボリュームの最終版を作成する前に、memo と onerror=go の行を削除してください。
第 13 章「インストール・パッケージの準備」は、アプリケーション・インストール・パッケージにどのヘルプ・ファイルが含まれているかを説明しています。
ヘルプタグ実行後、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 の参照
要素に終了タグを付け忘れるのはよくあるミスです。リスト、図、注、注意、警告などの要素を作成するときには、必ず終了タグを付けてください。特に、リスト中の図のように、ある要素を他の要素の中にネストした場合は、マークアップを丁寧にチェックしてください。
間違ったエンティティ名を使用するエラーもよく起こります。ほとんどの場合は単なるつづりの間違いです。その他は、エンティティ名が変更されたのに元の名前への相互参照が見落とされた場合です。エンティティ名を変更するときには、ソース・ファイルでそのエンティティ名のすべてのインスタンスを忘れずに検索してください。
同じように、要素に関連付けられた ID を変更すると、そのトピックへの相互参照やリンクに影響します。
ヘルプ・ビューアはどのヘルプ・ボリュームでも表示できます。ヘルプ・ビューアは、アプリケーション定義リンクを除くすべての型のハイパーリンクをサポートしています (アプリケーション定義リンクはどう解釈すべきかヘルプ・ビューアにはわからないからです)。
アプリケーション用ヘルプを記述していて、そのアプリケーションが使用できる状態であれば、アプリケーションを実行し、ユーザがするようにヘルプを呼び出せば、ヘルプを表示できます。
ファイル・マネージャを開き、ディレクトリを volume.sdl ファイルのあるディレクトリに移動します。
アイコンをダブルクリックします。
デフォルトでは、ヘルプ・ビューアを使ってファイルが表示されます。
表示したいボリュームの 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
デスクトップは、ブラウザ・ボリュームと呼ばれる特別なヘルプ・ボリュームを提供しています。ブラウザ・ボリュームにはシステムで使用可能なヘルプ・ボリュームがリストされます。ブラウザ・ボリュームは、フロントパネルで [ヘルプ・ビューア] コントロールをクリックすると表示されます。
ブラウザ・ボリュームから各種のヘルプ・ボリュームを直接表示できます。これにより、アプリケーションを起動しなくてもアプリケーション固有のヘルプにアクセスできます。また、スタンドアロン・ヘルプを記述している場合は、ユーザがそのヘルプを得られる唯一の方法です。
ヘルプ・ボリュームをブラウザ・ボリュームで使用できるようにするには、ヘルプ・ファミリ・ファイルを作成します。アプリケーションがデスクトップに登録されてファミリ・ファイルができると、ヘルプ・ボリュームがブラウザ・ボリュームの中に取り込まれます。
デスクトップ・ユーティリティはブラウザ・ボリュームを作成および更新します。ユーザが初めてフロントパネルの [ヘルプ・ビューア] をクリックすると、このユーティリティが自動的に実行されます。このユーティリティは、ヘルプ検索パス・ディレクトリにあるヘルプ・ボリュームとヘルプ・ファミリ・ファイルを識別します。このユーティリティは、browser.hv というファイルをユーザの HomeDirectory/.dt/help/$DTUSERSESSION ディレクトリに作成します。一度作成された後は、ボリュームは変更があった場合にのみ更新されます。
ブラウザ・ボリュームを手動で更新するには、「ブラウザ・ヘルプ・ボリュームの作成 (dthelpgen)」を参照してください。
ブラウザ・ボリュームにリストされているヘルプ・ボリュームはどれでも、ボリューム・タイトルを選択すれば表示できます。異なるボリュームから表示やナビゲートができるので、ブラウザ・ヘルプ・ウィンドウには [トップレベル] というボタンがあります。1 つまたは複数のボリュームを表示した後に、このボタンを使ってブラウザ・リストに戻ることができます。
デスクトップ・ユーティリティは、どのヘルプ・ボリュームがブラウザ・ボリュームに集められているか識別するために、ヘルプ・ファミリ・ファイルを調べます。図 4-1 は、ブラウザ・ボリュームにリストされている「Common Desktop Environment (共通デスクトップ環境)」と「Overview and Basic Desktop Skills (概要とデスクトップの基本スキル)」という 2 つのヘルプ・ファミリを示します。各ファミリ・ファイルは、1 つまたは複数の関連するヘルプ・ボリュームから成ります。たとえば、「Common Desktop Environment (共通デスクトップ環境)」ファミリには、デスクトップを説明する異なったボリュームが含まれています。
アプリケーションとそのヘルプ・ファイルをデスクトップにインストールする方法の詳細は、『Solaris 共通デスクトップ環境 上級ユーザ及びシステム管理者ガイド』を参照してください。
プロダクトに独自のファイル名を付けます。ヘルプ・ファミリのファイルだと識別できるように拡張子 .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 にはヘルプタグ・マークアップを指定できません。このファイルはヘルプタグ・ソフトウェアでは処理されません。
icon file はオプションです。指定する場合、ファイルの位置を指定するのに使用するパスは絶対パス名でなければなりません。アイコンを付けない場合は、ファミリ・ファイルに *.bitmap リソースを指定しないでください。
volume 名のリストは、そのファミリにどのボリュームが属すのかを識別します。ボリュームは、この行に表示される順番にリストされます。1 つのボリュームが複数のファミリにリストされることもあります。
いずれかの値が 1 行を超える場合、最後の行以外の各行を ¥ で終わらせます。
ファイル内で ! (感嘆符) で始まる行はコメント行であり、無視されます。
最終的なプロダクトを準備するとき、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
実際にデスクトップ・ソフトウェアに指定されているヘルプ・ファミリは、この図のとおりではありません。
サポートされている文字セット名のリストは、「文字セットおよびマルチバイト文字」を参照してください。
デスクトップのフロントパネルから [ヘルプ・ビューア] コントロールを選択します。
ヘルプ・ウィンドウをスクロールして、システムで使用可能なヘルプ・ファミリを表示します。
ヘルプ・ファミリ・タイトルを選択してボリュームを表示します。
ヘルプ・システムに関するヘルプ情報を参照するには、[デスクトップの紹介] を選択してから [ヘルプの使い方] を選択してください。
次のように dthelpview コマンドを実行します。
dthelpview -helpvolume browser
「ヘルプ・トピックの表示 (dthelpview)」には dthelpview コマンド行がリストされています。
dthelpgen(1) のマニュアル・ページ
ヘルプ・ボリュームを表示した後、ヘルプ・トピックを印刷できます。図 4-2 のダイアログ・ボックスで、個々のトピック、目次および索引情報、ヘルプ・ボリューム全体を印刷できます。印刷出力ではグラフィックは省かれます。
ヘルプ・ボリュームのテストは、他のソフトウェア・プロダクトのテストと同じように重要です。テストを計画するのに役立つヒントをいくつか紹介します。
ヘルプ・ボリュームを表示して、すべてのハイパーリンクを試します。下線 (実線または破線) の付いたテキストは、すべてハイパーリンクです。また、ハイパーリンクになっているすべてのグラフィックもテストします。グラフィック・ハイパーリンクは、ハイパーリンクの印として、イメージの周りに (破線または実線の) 隅が開いている枠を使用しています。
アプリケーション固有のヘルプを記述していて JumpNewView、Man、AppDefined リンクのいずれかを指定した場合は、これらのリンクをアプリケーションからテストしなければなりません。これらのリンクを dthelpview を使ってテストしても、アプリケーション内から正しく動作する保証にはなりません。
特定のヘルプ・トピックへのアクセスに ID を使用するアプリケーション固有のヘルプを記述している場合、ID がヘルプ・ボリューム内で正しく確立されているかを調べる方法は 2 つあります。
アプリケーションを実行して、ユーザがするようにヘルプを要求してエントリ・ポイントを 1 つずつ確認します。これにより、アプリケーションが正しい ID を使用しているかも検査できます。
アプリケーションが (開発中で) まだ使用できない場合は、各 ID に対して dthelpview を実行することで各 ID をテストできます。
dthelpview -helpVolume volume.sdl -locationId id
id は、テストしたい位置 ID です。dthelpview が正しいトピックを表示していれば、その ID は大丈夫です。
ユーザは、ヘルプ・トピックを見つけるためにヘルプ・ボリュームの索引を検索したりブラウズしたりします。あいまいな用語や重複したエントリがないように、索引エントリを丁寧に検査してください。また、各索引エントリを選択して、表示されるトピックが最も適切な情報かをチェックしてください。
グラフィックが、カラー、グレースケール、白黒ディスプレイで表示可能なことを検査するために、物理的にアプリケーションをさまざまなディスプレイで表示します。
デスクトップが使用するカラーの数を変更して、他のディスプレイをシミュレートすることもできます。そのためには、スタイル・マネージャを開き、[色の数] を選択し、異なるカラー・オプションを選択します。
ヘルプ・ボリュームの開発中には、helptag.opt ファイルに onerror=go オプションを設定していると便利です。指定してある場合は、最終的にはこのオプションを削除してからソース・ファイルを処理し、エラーが 1 つも発生しないことを確認してください。