test

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

第 2 章 ヘルプ・ボリュームの構成および記述

この章では、ヘルプ・ソース・ファイルの構成とコンポーネントについて説明します。また、ヘルプ・ソース・ファイルを処理してオンライン・ヘルプ・ボリュームを作成する方法についての手順の例も示します。

ヘルプ・ボリュームのコンポーネント

ヘルプ・ボリュームには、ホーム・トピック、トピック、サブトピック、エンティティの宣言、メタ情報、および用語集のおもに 6 種類のコンポーネントがあります。

ホーム・トピック

ホーム・トピックは、トピック階層の中でトップレベルにあるトピックです。最初のトピック、つまりヘルプ・ボリュームの先頭になります。その他のトピックはすべてサブトピックになります。トピック階層を複数のレベルの階層で構成することも可能です。しかし、階層内で迷わないようにするために、階層をできる限り浅くしておくべきです。

トピックとサブトピック

トピックとサブトピックは、ホーム・トピックの下に階層を形成します。通常、ホーム・トピックに続く第 1 レベルのトピックは、<chapter> 要素を使用して章に分割されます。章の内では、トピックはセクションに分割されます。<s1> セクションのサブトピックは <s2> と入力され、<s2> のサブトピックは <s3> のように入力されていきます。

章かセクションのどちらかの要素をホーム・トピックの後に続けることができます。階層を <chapter> と <s1> のどちらで始めてもその違いは表示からはわかりません。図 2-1 では、3 つの章がある単純な階層を示しています。各章には第 1 レベルのセクションがいくつかあります。3 番目の章には第 2 レベルのセクションが 2 つ追加されています。

図 2-1 ヘルプ・ボリュームのトピック構成

Graphic

エンティティ

設計者定義のエンティティには、文字列またはファイル名を指定します。エンティティ宣言は、エンティティ名とエンティティが表す文字列またはファイルを定義します。

エンティティは次の場合に有効です。

ヘルプ・ボリューム内の他のマークアップの前にすべてのエンティティの宣言を入力しなければなりません。定義済みのエンティティを入れるには、エンティティの参照を使用します。エンティティの参照は、ヘルプ・ボリューム内であればどこでも使用できます。ヘルプタグ・ソフトウェアでヘルプ・ボリュームを処理する場合、各エンティティの参照は、そのエンティティが指すテキストまたはファイルで置換されます。「エンティティの使い方」では、エンティティの定義方法と使い方について説明しています。

メタ情報

メタ情報はユーザの情報についての情報です。ボリュームのタイトル、著作権に関する記述、および要約などの情報が含まれています。要約は、ボリュームの内容についての簡単な説明です。

ヘルプ・システムは、メタ情報を使用して、ヘルプ・ボリュームのタイトルとその著作権情報を表示します。要約の記述は、フロントパネルのデスクトップ・ヘルプ・ビューアによって表示されます。ヘルプ・ボリュームを表示できる他のアプリケーションもまたこの情報を使用できます。

メタ情報には、通常のトピック階層の一部ではないヘルプ・トピックも含むことができます。メタ情報セクションにある非階層トピックには、リンクでアクセスします。

「メタ情報トピックの作成」は、メタ情報セクションの作成方法を示しています。

用語集

用語集には、ヘルプ・ボリュームで使用されている用語に対する定義が入っています。用語が <term> 要素を使用して入力される場合、自動的に定義リンクになり、選択されるとその用語に関する用語エントリを表示します。

一般的なマークアップのガイドライン

オンライン・ヘルプは通常のテキスト・ファイルで記述されています。特殊コード、またはタグを使用して、情報内の要素にマークを付けます。タグは、ヘルプタグと呼ばれるマークアップ言語を形成します。標準のテキスト・エディタを使用する場合、ヘルプタグ・マークアップが入力されます。または、エディタがマクロ・パッケージを提供している場合、タグはコマンド・キーを使用すると保存および挿入できます。ヘルプタグ・マークアップは構造化エディタを使用して生成することもできます (「正規マークアップ」を参照してください)。

ヘルプタグ・マークアップ言語は、章、セクション、サブセクションなどのハイレベル要素と、段落、リスト、および強調された語などのローレベル要素を定義する要素の階層を定義します。

ソース・ファイル内のマークアップ

ほとんどの要素のマークアップは、開始タグと終了タグで構成されます。開始タグは、三角括弧 (< と >) の間に要素名を入れて入力されます。終了タグも同様ですが、要素名の先頭に ¥ (バックスラッシュ) または 促 (円記号) が付きます。

<element>  ... text ... <¥element>

たとえば、本のタイトルの始めと終わりをマークするには、次のようにマークアップを使用します。

<book>Geographical Survey of Northern Wisconsin<¥book>

<book> は開始タグで、<¥book> は終了タグになります。

簡易マークアップ

簡易マークアップは、標準テキスト・エディタを使用して手動でタグ付けする設計者向けに設計されたむだを省いたタグ・セットです。簡易マークアップにはいくつかの省略方法が用意されています。まず、終了タグの使用を最小化します。たとえば、章、節、または段落には終了タグを入力する必要はありません。さらに可能であれば、中間タグは自動的に想定されます。たとえば、章と節の要素により <head> タグを省略できます。したがって、ヘッダを入力するだけで済みます。

簡易マークアップは、文体の変更だけでなく多くのインライン要素へのマークアップも簡単にできます。テキストを区切るには、開始と終了のタグを入力するよりも、次のように縦線が使用されます。

<element| ... text ... |

たとえば、次の例は前に表示した <book> 要素の略式です。

<book| Geographical Survey of Northern Wisconsin|

要素にパラメータがある場合、要素とパラメータは次のように最初の縦線の前に入力します。

<element parameters| ... text ... |

開始と終了のタグを特殊な 2 文字のショートカットで置き換えるようなさらに略した形式をサポートしている要素もあります。たとえば、<emph> (強調表示) 要素の場合、その通常の形式は次のようになります。

<emph>  ... text ... <¥emph>

上記の形式は、次のように簡易形式を使用して入力することもできます。

!! ... text ... !!

第 3 章「ヘルプ・トピックの記述」 では、簡易マークアップを紹介し、最も頻繁に使用される要素の例を示しています。第 5 章「ヘルプタグ・マークアップのリファレンス」では、要素をアルファベット順に並べて、各要素について詳細に説明しています。

正規マークアップ

正規マークアップを使用する場合は、パート II で説明されている情報を理解しておく必要があります。また、正規マークアップの詳細は、第 8 章「ヘルプタグ文書型定義の読み方」を参照してください。

ヘルプタグ記号の表示

時には、テキスト文字として < (左三角括弧)、¥ (バックスラッシュ)、または & (アンド記号) を使用する必要がある場合もあります。その場合は、各文字の先頭にアンド記号を付けてください (&<、&¥、または &)。

ヘルプ・ボリュームの例

次のマークアップは、入力に使用されるヘルプ・ボリュームとタグの重要な要素の例を示しています。この例では簡易マークアップを使用しますが、このマークアップは SGML 構造の中間タグを省略し、必須の終了タグの数を最小にします。インデントは、要素の階層関係を強調表示するために使用されます。したがって、記述するヘルプ・ファイルをインデントする必要はありません。

All entity declarations go here (before any other markup).
<helpvolume>
      <metainfo>
          <title>  Volume Title
          <copyright>
          Copyright topic goes here ...
          <abstract>
           The abstract describing your help volume goes here.
               There may be other meta information topics.
            .
            .
            .
      <¥metainfo> 

      <hometopic>  Home Topic Title
                   Help volume introduction goes here ...
           <s1>  Title of First Topic Goes Here
                   Body of the first topic goes here ...
           <s1>  Title of Second Topic
                   Body of the second topic goes here ...
                   <s2>  Title of Suptopic
                          Body of the subtopic goes here ...
             .
             .
             .
 
     <glossary>
      The body of the glossary, which contains term definitions, goes here ...
 <¥helpvolume>

ヘルプ・ソース・ファイル

オンライン・ヘルプは通常のテキスト・ファイルで記述されます。ヘルプタグ・ソフトウェアでこれらのファイルを処理またはコンパイルし、ヘルプ・システムによって読み込むことができる実行時のヘルプ・ファイルを作成します。

volume.htg ファイルの作成

ヘルプタグには、volume.htg または volume.ctg という名前のプライマリ・コントロール・ファイルが必要です。volume には選択したボリューム名が入ります。ファイル拡張子によって、コントロール・ファイルが簡易マークアップ (.htg) か正規マークアップ (.ctg) のどちらを参照するかを指定します。

ボリューム名が固有のもので、意味があるものか確認してください。ボリューム名が一般的すぎる場合は、他のユーザが作成した別のボリュームと重複してしまう可能性があります。アプリケーションのヘルプを記述する場合、アプリケーションのクラス名を使用することをお勧めします。たとえば、アイコン・エディタのクラス名は Dticon なので、そのヘルプ・ボリューム名は Dticon.htg と名付けます。

複数のソース・ファイル

volume.htg ファイルには、エンティティの宣言とヘルプ・ボリュームを作成するファイルへのエンティティの参照が記述されています。ヘルプタグは入力として単一の volume.htg ファイルを必要としますが、作業を複数のソース・ファイルに分割できます。追加のファイルは、ファイル・エンティティを使用して volume.htg ファイルにまとめられます。ファイル・エンティティは、他のファイルへのポインタのようなものです。そのファイルは実際には、volume.htg ファイル内でエンティティの名前が表示されたところであればどこでも挿入されます。参照されるファイルもまた、別のファイルを参照するエンティティを含むことができます。(エンティティはテキスト文字列を参照する場合にも使用できます。)

例

ヘルプ・ボリュームには 6 つの章があり、各章は独立したファイルであるとします。ファイルには、HomeTopic、Metainfo、TOC、Tasks、Reference、および Glossary があります。ヘルプ・ボリュームの volume.htg ファイルには、6 つのファイルそれぞれに対するファイル・エントリと、ファイルの処理をヘルプタグ・ソフトウェアに指示するエンティティ参照リストが含まれています。

<!entity HomeTopic              FILE "HomeTopic">
<!entity MetaInformation        FILE "Metainfo">
<!entity TableOfContents        FILE "TOC">
<!entity Tasks                  FILE "Tasks">
<!entity Reference              FILE "Reference">
<!entity Glossary               FILE "Glossary">

&HomeTopic;
&MetaInformation;
&TableOfContents;
&Tasks;
&Reference;
&Glossary;

実行中のヘルプタグの詳細は、「実行時のヘルプ・ボリュームを作成するには」で説明しています。

ファイル・マネージャのヘルプ・ファイル

ファイル・マネージャは、ヘルプ・ファイルをクエスチョン・マーク付きのファイル・アイコンで表現します。図 2-2には、ソース・ファイルが 2 つ (.ctg 拡張子と .htg 拡張子) と実行時のファイル (.sdl 拡張子) が 1 つあります。マークアップ・ファイルをダブルクリックすると、標準エディタが編集用のファイルを開きます。.sdl ファイルをダブルクリックすると、ヘルプ・ビューアを使用して実行時のファイルが表示されます。

図 2-2 ファイル・マネージャによるヘルプ・ファイル表示

Graphic

実行時のヘルプ・ボリュームを作成するには、ファイル・マネージャにある .htg または .ctg ファイルを最初に選択してください。次にファイル・マネージャの [選択] メニューから [コンパイル] を選択してください。

関連項目

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  3. 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> )

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

    この例では、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 という名前のサブディレクトリを作成します。

Graphic

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

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

  2. .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 ファイルの作成

  1. build サブディレクトリに、helptag.opt という名前のファイルを作成し、次のテキストをそのファイルに格納します。この情報はヘルプタグのオプションを選択し、FILE エンティティの宣言で定義されたファイルをどこから検索すべきかを示します。

       onerror=go
memo
search=./
search=../

    onerror=go オプションは、エラーが発生した場合でもヘルプタグ・ソフトウェアが入力ファイルを処理し続けるように指示します。パーサ・オプションの説明については、「パーサ・オプション」を参照してください。パーサ・オプションの一覧と詳細は、dthelptag(1) のマニュアル・ページを参照してください。

  2. 端末エミュレータで次のコマンドを入力し、/usr/dt/bin ディレクトリが検索パスにあるか確認します。

       echo $PATH

    そのディレクトリがパスにない場合は、PATH 環境変数に追加します。追加方法がよくわからない場合は、システムのドキュメントを参照するかシステム管理者に問い合わせてください。

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

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

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

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

    注 -

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

    そのためには、次のコマンドを実行します。

       dthelptag -verbose voiceact.htg

    -verbose オプションは、画面にその経過状況を表示するようにヘルプタグに通知します。

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

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

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

注 -

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

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

dthelpview -h voiceact.sdl

関連項目

トピック階層の作成

ヘルプ・ボリューム内のトピック階層は、ホーム・トピックから始まります。各ヘルプ・ボリュームにはホーム・トピックが必ず 1 つなければなりません。ホーム・トピックの下にある第 1 レベルのサブトピックは、<chapter> または <s1> と入力されます。

サブトピックのレベルを追加する場合は、<s2> や <s3> などのように入力します。ヘルプタグのマークアップ言語は、<s1> から <s9> までの 9 つのトピック・レベルをサポートしています。しかし、第 3 または 第 4 レベルよりも下にある情報は、多くの読者にとって見つけにくいものになってしまいます。

ヘルプ・ボリュームが表示されたら、ヘルプ・ウィンドウはそのトピック・ツリーにトピックのリストを表示します。<chapter> か <s1...s9> のタグが入力されているトピックは、トピック・ツリーに自動的に表示されます。トピックをブラウズし表示するには、この方法が簡単です。

トピック内から他の関連情報を表示するには、ハイパーリンクを作成します。そのためには、それぞれのトピックに固有の ID を割り当て、ハイパーリンクがヘルプ情報内のどこでも特定の ID を参照できるようにします。

例

このサンプルに一致する階層を作成したいとします。

Tutorial for New Users
       Module 1: Getting Started
       Module 2: Creating Your First Report 
       Module 3: Printing the Report
       Module 4: Saving Your Work and Quitting 
 Task Reference 
      Starting and Stopping 
           To Start the Program 
           To Quit the Program
       Creating Reports 
           To Create a Detailed Report
           To Create a Summary Report
  Concepts for Advanced Users
      Using Report Hot Links 
      Sharing Reports within a Workgroup
  Reference
      Command Summary 
      Report Attributes Summary

その場合、ヘルプ・ボリュームのマークアップの概要は次のようになります。(各トピックの本文や各トピックの ID は省略します。)

<hometopic>  Welcome to Report Master
   <chapter>  Tutorial for New Users
     <s1>  Module 1: Getting Started
     <s1>  Module 2: Creating Your First Report
     <s1>  Module 3: Printing the Report
     <s1>  Module 4: Saving Your Work and Quitting
   <chapter>  Task Reference
     <s1>  Starting and Stopping
       <s2>  To Start the Program
       <s2>  To Quit the Program
     <s1>  Creating Reports
       <s2>  To Create a Detailed report
       <s2>  To Create a Summary report
   <chapter>  Concepts for Advanced Users
     <s1>  Using Report Hot Links
     <s1>  Sharing Reports within a Workgroup
   <chapter>  Reference
     <s1>  Command Summary
     <s1>  Report Attributes Summary

ここでインデントが使用されているのは、ヘルプ・ボリュームの構造をより見やすくするためです。ソース・ファイルでインデントする必要はありません。

関連項目

ホーム・トピックを作成するには

    次のように <hometopic> 要素を使用します。

   <hometopic> Title
   Body of topic.

メタ情報セクション (<metainfo>) を入れる場合、必ずその後ろにホーム・トピックを続けてください。

例

次に、タイトルと本文 1 文のみで構成されているホーム・トピックの例を示します。

<hometopic> Welcome to My Application

 Congratulations, you've entered
 the online help for My Application.

次の例は、4 つのサブトピックにハイパーリンクするホームトピックです。

<hometopic> Welcome to Report Master

 Welcome to the online help for Report Master.
 Choose one of the following hyperlinks:
 <list bullet>
  * <xref Tutorial>
  * <xref Tasks>
  * <xref Concepts>
  * <xref Reference>
 <¥list>
 If you need help, press F1.

上記のマークアップの出力は次のとおりです。

Graphic

トピックを階層に追加するには

    別のトピックを同じレベルに追加するには、同じ要素を繰り返します。

    または、サブトピック (階層内でさらに 1 レベル下のトピック) を追加するには、前のトピックよりも 1 レベル下にある要素を使用します。

例

現在のトピックが <s1> である場合、<s2> を使用してサブトピックを入力します。

<s1 id=getting-started>  Getting Started

<s2 id=starting-the-program>  Starting the Program
Here's the body of the first subtopic.

<s2 id=stopping-the-program>  Stopping the Program
Here's the body of the second subtopic.

2 番目の <s2> も <s1> のサブトピックです。

注 -

親子兄弟メタファは、階層内のトピック間の関係を記述するのに使用されることもあります。前の例では、<s1> トピックは両方の <s2> (「子」トピック) の「親」です。2 つの <s2> はお互いに「兄弟」になります。3 つのすべてのトピックは、ホーム・トピックの「子孫」です。

メタ情報トピックの作成

メタ情報セクションには、本の中に著作権に関するページがあるのと同様に、ボリューム・タイトル、著作権、商標、およびその他の注意事項などの情報が含まれています。

メタ情報セクションの 2 番目の使用法は、通常のトピック階層の一部ではないヘルプ・トピックを入力することです。これらの非階層トピックは、簡易ヘルプ・ダイアログ・ボックスにあるトピックをポップアップするカスタム定義のリンクを作成するのに有用です。

メタ情報セクションを作成するには

  1. 次のように <metainfo> タグを入力してセクションを始め、必須の副要素である <title> と <copyright> を入力します。

       <metainfo>

<title> Volume Title Here

<copyright>
Body of copyright topic here..
.
.

  2. 次のようにオプションの要素のどれかを入力します。

       <abstract>
Body of the abstract topic here.
Do not use any HelpTag markup within the abstract!

  3. 終了タグ <¥metainfo> を入力してセクションを終了します。

       .
.
.
<¥metainfo>
    注 -

    メタ情報セクションにある要素の中には、トピックのヘッダの前に <head> タグが必要なものもあります。

    <abstract> セクションを使用することをお勧めします。ヘルプ・ボリュームにアクセスするアプリケーションはこの情報を使用してボリュームの簡単な説明を行います。その抜粋は単純なテキスト・ウィンドウ (複数のフォントやグラフィック・フォーマットはサポートしていない) に表示される可能性があるので、ヘルプタグのマークアップを取り込まないようにしてください。

例

次の例は、一般的なメタ情報セクションです。

<metainfo>
  <title>  Report Master, Version 1.0

   <copyright>
     <otherhead> Report Master

     <image>
     Version 1.0
     &copy; Copyright Reports Incorporated 1995
     All rights reserved.
     <¥image>

   <abstract>
     This is the online help for the mythical Report Master
     application. This help includes a self-guided tutorial,
     a summary of common tasks, general concepts, and quick
     reference summaries.

 <¥metainfo>

<image> 要素は、設計者が入力した改行を維持するために使用されます。&copy; は著作権のシンボルを挿入します。

関連項目

非階層トピックの追加

<chapter> または <s1...s9> の要素タグが入力されているトピックは、自動的にトピック・ツリーに表示されます。タイトルがトピック・ツリーで選択されると、対応するヘルプ・トピックが一般ヘルプ・ダイアログ・ボックスに表示されます。しかし、すでに作成されているトピック階層からは独立しているトピックを作成および表示したい場合もあります。たとえば、別の簡易ヘルプ・ウィンドウにトピックを表示したい場合などです。

非階層トピックを追加するには

    次のように <otherfront> 要素を使用して、メタ情報セクションの最後の直前にトピックを追加します。

   <otherfront id=id><head>  Topic Title
   Body of topic.

ID パラメータと <head> タグは必須です。

希望の数の <otherfront> トピックを追加できます。どんな順番でもかまいませんが、<metainfo> ... <¥metainfo> セクションの中の最後のトピックでなければなりません。

例

この部分的なヘルプ・ボリュームは、一般トピックがどのようにメタ情報セクションに追加されるかを示しています。トピックのタイトルは「Pop-up!」で、ID は my-popup-topic です。

<metainfo>

   <title> My Help
   <copyright>
      This is My Help, Version 1.0.  &copy; 1995.
         .
         .
         .

   <otherfront id=my-popup-topic> <head> Pop-up!

   This is a pop-up topic, displayed via a definition link
   somewhere in my help volume.
 <¥metainfo>

 <hometopic>  Welcome to My Help
         .
         .
         .

ヘルプ・ボリューム内の他のトピックのいくつかには、このトピックを表示するための定義リンクがある場合があります。

リンクは次のように定義されます。

Here's a sample of a pop-up <link my-popup-topic Definition> definition link<¥link>.

「definition link」という語はアクティブなハイパーリンクになり、破線の下線が付いて表示されます。そのリンクを選択すると、簡易ヘルプ・ダイアログ・ボックスの「Pop-up!」トピックが表示されます。

関連項目

トピックへのアクセス

ヘルプタグ言語の多くの要素は ID 属性をサポートしています。ID は、トピックとトピック内の要素を識別するために内部的に使用される独自の名前です。ID は一度しか定義されませんが、複数のハイパーリンクと相互参照は同じ ID を参照できます。ID はユーザには見えません。

アプリケーションのヘルプを記述している場合、ユーザがヘルプを要求したときに表示される特定のトピックを識別するために、アプリケーションが ID を使用することもあります。たとえば、アプリケーションのメニューを説明するいくつかのトピックを記述する場合などです。トピックに割り当てる ID は、アプリケーションの開発者によって使用されます。アプリケーション・コード内に同一の ID を定義することにより、開発者は特定のトピックを統合できます。これによりアプリケーションは、特定のメニューに関してヘルプが要求されたときに正しいトピックへアクセスし、表示できます。

ID 名に関する規則

ID をトピックに追加するには

    次のように要素の id パラメータを使用します。

<element id=id>  ...

新しいトピックを開始し、設計者定義 ID をサポートしている要素は次のとおりです。

組み込み ID

組み込み ID を持っている要素は数個ありますが、設計者定義 ID をサポートしていません。次の要素のそれぞれも新しいトピックを開始しますが、これらの要素は定義済み ID (括弧内のもの) を持っています。

<abstract>

(_abstract)

<copyright>

(_copyright)

<glossary>

(_glossary)

<hometopic>

(_hometopic)

<title>

(_title)

ID をトピック内の要素に追加するには

    要素が設計者定義 ID をサポートしている場合、次のように要素の id パラメータを使用します。

   <element id=id>  ...

ID 属性をサポートしている (トピック内の) 要素は、次のとおりです。

または、次のように <location> 要素を使用して、トピック内の任意の場所に ID を設定します。

<location id=id> text <¥location>

text は ID を追加したい語句です。<¥location> 終了タグは必須です。位置 ID に対するリンクを起動すると、ヘルプ・ビューアは ID が入っているトピックを表示し、ウィンドウを ID の位置までスクロールします。

例

ID を図に追加する場合、タイトルがなければなりません。図の ID に対して相互参照が行われる場合、タイトルが必要です。その場合、タイトルは図へのハイパーリンクになります。

次は、ID my−big−picture の図をマークアップする例です。

<figure id=my-big-picture entity=big-picture-TIFF>
 Here's My Figure
 <¥figure>

次の例は、「easier than ever」という句に ID easy-spot が割り当てられているパラグラフです。

Getting help is <location id=easy-spot> easier than ever<¥location>.

エンティティの使い方

エンティティには文字列やファイルの内容を指定できます。エンティティの宣言は、エンティティ名と特定の文字列やファイル名とを関連付けることによりエンティティを定義します。エンティティの参照は、dthelptag コマンドでヘルプ・ボリュームを処理すると文字列やファイルの内容に置き換えられます。

エンティティは次の作業を実行できます。

ファイル・エンティティにより、ヘルプタグ・ソースを複数のファイルに分割できます。他のファイルをマスタ・ヘルプタグ・ファイルに取り込んで処理を行うためには、エンティティの参照を使用してください。

エンティティの宣言に関する規則

テキスト・エンティティを作成するには

  1. 次のようにエンティティを宣言します。

       <!entity Entityname  "text">

    Entityname はエンティティ名で、text はエンティティへの各参照に代わる文字列です。エンティティの宣言はすべて、ヘルプ・ボリュームの他のマークアップの前にくる必要があるので注意してください。

  2. text 文字列を挿入する各位置に、次のようにエンティティの参照を入力します。

       &Entityname;

    & (アンド記号) と ; (セミコロン) の文字は、ヘルプタグ・ソフトウェアがエンティティの参照を適切に認識するために必要です。

例

次の行は「Society of Agricultural Engineers」という文字列が入っている Assoc という名前のテキスト・エンティティを宣言しています。

<!entity Assoc "Society of Agricultural Engineers">

次の文には、エンティティへの参照が記述されています。

Welcome to the &Assoc;.

ヘルプ・ボリュームがヘルプタグ・ソフトウェアで処理されると、エンティティの参照はエンティティの値に置き換えられます。そのため、文は次のように表示されます。

Welcome to the Society of Agricultural Engineers.

ファイル・エンティティを作成するには

  1. 次のようにエンティティを宣言します。

       <!entity Entityname FILE  "filename">

    Entityname はエンティティ名で、filename はファイル名です。キーワード FILE は必須です。

  2. 次のようにエンティティを参照します。

    • ファイルがテキスト・ファイルの場合、ファイルの内容を挿入する各位置に次のようにエンティティの参照を入力します。

         &Entityname;

      & (アンド記号) と ; (セミコロン) の文字は、ヘルプタグ・ソフトウェアがエンティティの参照を適切に認識するために必要です。

    • ファイルがグラフィック・ファイルの場合、次のマークアップ行のうちの 1 つにパラメータとしてエンティティ名を入れます。

         <figure entity=Entityname ... >

      または 

         <graphic entity=Entityname ... >

      または 

         <p gentity=Entityname ... >
      注 -

      ファイル名にはパスを入れないでください。ヘルプタグ・ソフトウェアを実行するときにファイルが現在のディレクトリにない場合は、適切な検索パスを helptag.opt ファイルに追加してください (詳細は、「実行時のヘルプ・ボリュームを作成するには」を参照してください)。

例: テキスト・ファイル・エンティティ

file1、file2、および file3 という名前の 3 つのファイルと <metainfo> ...</metainfo> セクションがある 4 番目のファイルに、ヘルプ・ボリュームのテキストを記述したとします。次のようにして 4 つのファイルを volume.htg ファイルに取り込むことができます。

<!entity MetaInformation   FILE  "metainfo">
<!entity MyFirstFile       FILE  "file1">
<!entity MySecondFile      FILE  "file2">
<!entity MyThirdFile       FILE  "file3">

&MetaInformation;

<hometopic>  My Home Title

Welcome to my application's help volume.

&MyFirstFile;
&MySecondFile;
&MyThirdFile;

例: グラフィック・ファイル・エンティティ

単一のヘルプ・ボリュームのホーム・トピックに図があり、図のグラフィック・イメージが picture.tif という名前のファイルに格納されているとします。次の例は、そのイメージが図でどのように使用されるかを示しています。

<!entity MetaInformation  FILE  "metainfo">
<!entity MyPicture        FILE  "picture.tif">

 &MetaInformation;

 <hometopic> A Sample Graphic

 Welcome to my application's help volume

 <figure nonumber entity=MyPicture>
 A Picture
 <¥figure>

テキスト「A Picture」は、図のタイトルです。

マークアップの出力は次のとおりです。

Graphic

関連項目