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

パート II 設計者が行う作業

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

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

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

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

ホーム・トピック

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

トピックとサブトピック

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

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

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

エンティティ

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

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

テキストの共通の文字列を参照する

テキストが変更されたり、繰り返し入力したくないような場合に便利です。テキストを挿入したい場所では、エンティティ名を参照してください。
外部ファイルを参照する

グラフィック・ファイルにアクセスするにはエンティティが必要です。<figure> 要素と <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 ファイル・マネージャによるヘルプ・ファイル表示

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

build サブディレクトリに、helptag.opt という名前のファイルを作成し、次のテキストをそのファイルに格納します。この情報はヘルプタグのオプションを選択し、FILE エンティティの宣言で定義されたファイルをどこから検索すべきかを示します。
```
   onerror=go
memo
search=./
search=../
```
onerror=go オプションは、エラーが発生した場合でもヘルプタグ・ソフトウェアが入力ファイルを処理し続けるように指示します。パーサ・オプションの説明については、「パーサ・オプション」を参照してください。パーサ・オプションの一覧と詳細は、dthelptag(1) のマニュアル・ページを参照してください。

端末エミュレータで次のコマンドを入力し、/usr/dt/bin ディレクトリが検索パスにあるか確認します。
```
   echo $PATH
```
そのディレクトリがパスにない場合は、PATH 環境変数に追加します。追加方法がよくわからない場合は、システムのドキュメントを参照するかシステム管理者に問い合わせてください。

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

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

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

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.

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

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

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

または、サブトピック (階層内でさらに 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 番目の使用法は、通常のトピック階層の一部ではないヘルプ・トピックを入力することです。これらの非階層トピックは、簡易ヘルプ・ダイアログ・ボックスにあるトピックをポップアップするカスタム定義のリンクを作成するのに有用です。

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

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

<title> Volume Title Here

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

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

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

終了タグ <¥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> 要素は、設計者が入力した改行を維持するために使用されます。© は著作権のシンボルを挿入します。

非階層トピックの追加

<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 文字列は、英字 (A から Z と a から z)、数字 (0 から 9)、マイナス (-) 記号から成り、必ず英字で始まります。
設計者定義 ID は _ (下線文字) を使用できません。ヘルプタグ要素のいくつかに組み込まれている ID のために予約されています。
大文字でも小文字でも意味は変わりませんが、読みやすいように使い分けてください。
ID 文字列の長さは、64 文字以内です。
単一のヘルプ・ボリューム内の各 ID は、固有のものでなければなりません。

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

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

<element id=id>  ...

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

<chapter id=id>
<otherfront id=id>
<rsect id=id>
<s1 id=id>
<s2 id=id> . . .<s9 id=id>

組み込み ID

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

<abstract>: (_abstract)
<copyright>: (_copyright)
<glossary>: (_glossary)
<hometopic>: (_hometopic)
<title>: (_title)

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

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

   <element id=id>  ...

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

<figure id=id>
<graphic id=id>
<image id=id>
<location 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 コマンドでヘルプ・ボリュームを処理すると文字列やファイルの内容に置き換えられます。

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

テキストの共通の文字列を参照する。

テキストを変更したり、繰り返し入力したくないような場合に便利です。テキストを挿入したい場所では、エンティティ名を参照してください。
外部ファイルを参照する。

グラフィック・ファイルにアクセスするにはエンティティが必要です。<figure> 要素と <graphic> 要素にエンティティ名の指定に使用する必須パラメータが入っており、このエンティティ名によりグラフィック・イメージ・ファイルを参照します。

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

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

エンティティ名は、英字 (A から Z と a から z)、数字 (0 から 9)、マイナス (-) 記号から成り、必ず英字で始まります。
エンティティ名は大文字でも小文字でも意味は変わりませんが、読みやすいように使い分けてください。
エンティティ名の長さは、64 文字以内です。
各エンティティ名は、単一のボリューム内では固有のものでなければなりません。

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

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

text 文字列を挿入する各位置に、次のようにエンティティの参照を入力します。
```
   &Entityname;
```
& (アンド記号) と ; (セミコロン) の文字は、ヘルプタグ・ソフトウェアがエンティティの参照を適切に認識するために必要です。

例

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

<!entity Assoc "Society of Agricultural Engineers">

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

Welcome to the &Assoc;.

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

Welcome to the Society of Agricultural Engineers.

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

次のようにエンティティを宣言します。
```
 <!entity Entityname FILE "filename"> 
```
Entityname はエンティティ名で、filename はファイル名です。キーワード FILE は必須です。

次のようにエンティティを参照します。
- ファイルがテキスト・ファイルの場合、ファイルの内容を挿入する各位置に次のようにエンティティの参照を入力します。
```
 &Entityname;
```
 & (アンド記号) と ; (セミコロン) の文字は、ヘルプタグ・ソフトウェアがエンティティの参照を適切に認識するために必要です。
- ファイルがグラフィック・ファイルの場合、次のマークアップ行のうちの 1 つにパラメータとしてエンティティ名を入れます。
```
 <figure entity=Entityname ... > 
```
 または
```
 <graphic entity=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」は、図のタイトルです。

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

第 3 章ヘルプ・トピックの記述

この章では、テキストをフォーマットするのに使用する要素を説明します。また、グラフィックの取り込み方と、他のヘルプ・トピックへのハイパーリンクの作成方法も説明します。この章で示す例は簡易マークアップを使用しています。

ヘルプ・トピックの作成

ヘルプ・トピックは、固有の ID で識別できる情報の単位です。ヘルプ・トピックは、オンライン・ヘルプを記述しているプロダクトを最適に言い表す論理的な枠組みにグループ化されます。

記述する各トピックには、トピックの開始をマークする要素 (または、タグ) が付いていなければなりません。

<element id=id>  Help Topic's Title
 The body of the topic

element は chapter, s1, s2, ..., s9 のいずれかです。トピックの本文は、タイトルの後ならどの行からも始められます。

あるトピックのトピック階層内での位置は、そのトピックの開始に使われる element と、直前のトピックの開始に使われる element によって決まります。たとえば、あるトピックが <s2> で始まっていて、<s1> で始まるトピックの直後にある場合は、<s2> トピックは <s1> トピックのサブトピックになります。

アプリケーション (アプリケーション・ヘルプを記述している場合) かハイパーリンクのどちらかからアクセスするトピックには id が必要です。

ヘルプ・トピックのタイトルにはどんな文字列でも使用できます。タイトル文字列がソース・ファイルで 1 行を超える場合は、最後の行以外の行は & (アンド記号) で終わります。タイトル内の特定の位置で強制的に改行するには、¥ (バックスラッシュ) 文字を使用してください。

例

次の行は、<s1> タグを使用してトピックの開始をマークします。

<s1 id=welcome>Welcome to My Application

タイトルを強制的に 2 行に表示するには、次のように ¥ (バックスラッシュ) を使用してください。

<s1 id=welcome> Welcome to ¥ My Application

トピック内に構造を作成する

ヘルプ・トピックの本文には、情報を構成して提示するために選択する次のような要素があります。

段落は、テキストの本文に使用します。
リストは、箇条書きにして示す情報に使用します。リストの種類には、行頭文字が付いたもの、順番を付けたもの (番号の付いたもの)、何も付かないものがあります。
サブヘッダは、トピック内を部分に分けるのに使用します。
グラフィックは、インライン・グラフィックとしてテキスト内に入れたり、独立した図として段落の間に表示できます。
ハイパーリンクで、関連トピックを参照できます。ハイパーリンクは、その階層内のより深層のサブトピックに続いたり、まったく異なる部分のトピックに分岐したり、他のヘルプ・ボリュームに続いたりします。
コンピュータ・リテラルは、ファイル名や変数名などの、コンピュータが認識するテキストです。コンピュータ・リテラルは、それだけを分けて表示することも、インライン要素として表示することもできます。
注、注意、警告は、重要な情報へ読者の注意を促します。
強調表示は、パラグラフのテキスト内の重要な語句を強調表示するのに使用します。

パラグラフを開始するには

前の段落または他の要素の後に空白行を 1 行挿入します。

または、そのパラグラフをインデントする場合には  要素とパラメータを使用します。

または、ソース・ファイルでの段落の行の切れ目をそのまま維持したい場合は、<image> 要素を使用します。

 に対する終了タグは必須ではありません。しかし、<image> 要素には終了タグ <¥image> は必須です。

例

次の例は、空白行 1 行で区切られた 2 つのパラグラフです。どちらの段落にも特別なパラメータがないので、 タグを入力する必要はありません (これは 1 行以上の空白行を入力した時点で想定されます）。

The Application Builder provides an interactive, graphical 
environment that facilitates the development of desktop 
applications.

The Application Builder is designed to make it easier for developers 
to construct applications that integrate well into the desktop. It 
provides two basic services: assembles Motif objects into the 
desired application user interface, and generates appropriate calls 
to the routines that support desktop integration services.

段落を左端からインデントしたい場合は、オプションの indent パラメータを指定します。

<p indent> An indented paragraph can be used to draw the reader's attention to an idea.

次の段落は、ヘルプ・ウィンドウでの自動ワード・ラップを無効にし、ソース・ファイルに入力されたとおりの行の切れ目を維持します。<image> 要素は住所を入力する際、特に便利です。

<image>
Brown and Reed Financial Investors
100 Baltic Place  Suite 40 New York, New York
<¥image>

リストを作成するには

<list> 要素は次のように使用します。

   <list type spacing>  
   * item 
   * item
    .
    .
    .
   * item
   <¥list>

type はリストの種類で、bullet (デフォルト)、order、plain から選択できます。spacing は loose (デフォルト) か tight です。リスト内の各 item は * (アスタリスク)でマークします。

例

次の例は、簡単なリストです。type が指定されていないので、デフォルトの行頭に黒い丸を付けたリストになります。spacing も指定されていないので、デフォルトで各項目の間に空白行が 1 行ずつ入ります。

<list>
* Creating a Mail Message
* Sending a Message
* Reading Your Mail
<¥list>

上記のマークアップのオンライン書式は次のとおりです。

同じリストに番号を付けて行間を詰めるには、次のようにします。

<list order tight>
* Creating a Mail Message
* Sending a Message
* Reading Your Mail
<¥list>

出力は次のとおりです。

ラベル付きリストを作成するには

lablist は、オプションでカラム・ヘッダが付く 2 段組みのリストです。

ヘッダなしでラベル付きリストを作成するには、次のように <lablist> 要素を使用します。

   <lablist spacing>
     ¥ label 1¥ item 1  text
     ¥ label 2¥ item 2  text
       .
       .
       .
     ¥ label N¥ item N  text<¥lablist>

spacing は loose (デフォルト) か tight です。

例

次の例は、ラベル付きの章の説明のリストです。オプションのラベル・ヘッダは付いていません。

<lablist tight>
¥Chapter 1¥ An Overview of the System
¥Chapter 2¥ Installing the Operating System
¥Chapter 3¥ Configuring the Desktop
¥Appendix A¥ System Commands Quick Reference
<¥lablist>

出力は次のとおりです。

ラベル付きリストにヘッダを付けるには

次のように、<lablist> 要素と <labheads> 要素を使用します。

   <lablist spacing>
     <labheads>  ¥ heading for labels ¥ heading for items
     ¥ label 1¥  item 1 text
     ¥ label 2¥  item 2 text
      .
      .
      .

     ¥ label N¥ item N text
   <¥lablist>

例

<lablist>
<labheads>¥Key ¥Action
¥Previous¥ Scroll to previous page
¥Next¥ Scroll to next page
¥First¥ Go to first page in document
¥Last¥ Go to last page in document
<¥lablist>

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

トピックにサブヘッダを付けるには

中ヘッダ (トピック・タイトルより少し小さい) を付けるには、次のマークアップを使用します。

   
<otherhead>  Heading

小ヘッダを付けるには、次のマークアップを使用します。

   
<procedure>  Heading

サブヘッダはトピックの中に構造を作りますが、トピック・ツリーのトピックのリストには表示されません。

例

<procedure> 要素を使用して各リストの前に小ヘッダを付けます。

<procedure>Keyboard
<list order>
* Use the Tab and direction keys to move the highlight to the icon
  you want to select.
* Press Return or Spacebar.
<¥list>
<procedure>Mouse
<list bullet>
* Click the icon.
<¥list>

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

コンピュータ・リストを表示するには

ヘルプタグ・マークアップとして解釈される特殊文字シーケンスを含まないコンピュータ・リストを表示するには、次のように <ex> (例) 要素を使用します。

<ex size>
Computer text here.
<¥ex>

ヘルプタグが用いる特殊文字シーケンスを含むコンピュータ・リストを表示するには、次のように <vex> (逐語例) 要素を使用します。

<vex size>
Computer text here.
<¥vex>

例文の表示に用いるフォントのサイズを決定するオプションの size 属性は、smaller または smallest に指定できます。

例

次の例は、端末エミュレータにディレクトリ・リストを表示するのに <ex> 要素を使用しています。

In this tutorial, you will edit these graphics files:
<ex>
H_ActionIcons.xwd     H_HelpWindows.xwd
H_AppHelp.xwd         H_Hyperlinks.xwd
H_Canonical.xwd       H_Icons.xwd
H_FrontPanel.xwd      H_InlineGraphic.xwd
<¥ex>

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

改行は、ソース・ファイルに入力したとおりに表示されます。例文の幅がヘルプ・ウィンドウに対して広すぎる場合は、水平方向のスクロール・バーが表示されるので、ユーザは例文のテキストをスクロールできます。

注、注意、警告を追加するには

<note>、<caution>、<warning> の各要素は、次のように指定します。

   <note>
   Body of note here.
   <¥note> 

   <caution>
   Body of caution here.
   <¥caution> 

   <warning> 
   Body of warning here.
   <¥warning>

注、注意、警告の各要素にアイコンを関連付けるには、そのアイコンを格納するグラフィック・ファイルが識別するファイル・エンティティを定義します。定義済みのエンティティ名を使用してください。

<!ENTITY NoteElementDefaultIconFile FILE "filename ">
<!ENTITY CautionElementDefaultIconFile FILE "filename">
<!ENTITY WarningElementDefaultIconFile FILE "filename">

注、注意、警告にアイコンを付けたくない場合は、該当するエンティティを宣言しないでください。(すべてのエンティティ宣言は、ヘルプ・ボリュームの最初にあるその他のマークアップのどれよりも前に来なければならないことを忘れないでください。) そのようなエンティティの参照を指定する場合は、グラフィック・ファイルがヘルプタグ検索パス (helptag.opt) 上にあることを確認してください。

ヘルプ・システムが注、注意、警告の要素に使用するデフォルト・アイコン名は、次のエンティティで指定されます。

<!ENTITY NoteElementDefaultIconFile FILE "noteicon.pm">
<!ENTITY CautionElementDefaultIconFile FILE "cauticon.pm">
<!ENTITY WarningElementDefaultIconFile FILE "warnicon.pm">

これらのデフォルト・アイコンは /usr/dt/dthelp/dthelptag/icons ディレクトリにあります。

注、注意、警告の独自のアイコン・イメージを作成する場合は、イメージが割り当てられた領域に入るように小さくしておいてください。また、グラフィック・イメージは、helptag.opt ファイルに指定されたヘルプタグ検索パス上に存在しなければなりません。

例

次の注、警告、注意のマークアップの出力は図 3-1 のとおりです。

<note>
Before installing your application, complete the options checklist 
to determine the amount of disk space required.
 <¥note>

<warning>
This product is highly acidic and can cause skin irritation. Wearing 
protective gloves is mandatory when applying this product.
 <¥warning>

<caution>
     Do not place your fingers near the parrot cage!
 <¥caution>

図 3-1 注、警告、注意のヘルプ・アイコン

インライン要素の入力

インライン要素は、テキストの段落の中で語句をマークするのに使用します。これらの要素は、特定の項目を書式化するのに使用するフォントに影響します。

語句を強調表示するには

<emph> (強調表示) 要素を次のように使用します。

   
<emph> text <¥emph>

簡易形式では次のようになります。

   
!! text !!

イタリックで強調表示されたテキストが表示されます。日本語では、イタリック書体のフォントが提供されていない場合、それに代わる書体、たとえばボールドで表示されます。

例

重要な語を強調表示するには、次のようにします。

A thousand times <emph>no<¥emph>

簡易形式では、

A thousand times !!no!!

どちらの場合も、「no」がイタリックで表示されます。

本のタイトルを入力するには

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

   
<book>  title <¥book>

簡易形式では、

   
book| title |

本のタイトルがイタリックで表示されます。日本語では、イタリック書体のフォントが提供されていない場合、それに代わる書体、たとえばボールドで表示されます。

例

このマニュアルのタイトルを入力するには、次のようにします。

<book|The Help System Author's and Programmer's Guide|

Bold フォントで強調表示するには

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

   
<term nogloss> bold text <¥term>

簡易形式では、

   
<term nogloss |bold text |

<term> 要素は用語集のエントリを作成するのに使用されます。しかし、nogloss パラメータを追加すれば、テキストは Bold フォントで表示されますが用語集には追加されません。

コンピュータ・リテラルを表示するには

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

   
<computer>  text  <¥computer>

簡易形式では、

   

`` text ''

例

コンピュータ・テキストはファイル名を識別するのに便利です。次の例では、helptag.opt というファイル名が簡易マークアップでタグ付けされています。ファイル名がコンピュータ・テキストで表示されます。

Add the search path to your "helptag.opt" file.

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

Add the search path to your helptag.opt file.

変数を表示するには

<var> (変数) 要素を次のように使用します。

   
<var> text <¥var>

略式では、

   
<var |text |

簡易形式では、

   

%% text %%

変数がイタリックで表示されます。

例

次のコマンド行形式には、ユーザがファイル名を指定することを示す変数があります。

dtpad %%filename%%

出力は次のとおりです。

dtpad filename

変数は、コンピュータ・テキストまたはコンピュータの例表示に現れます。次の例は volume をファイル名の変数部分として指定します。

The HelpTag software takes your "%%volume%%.htg" file as input.

出力は次のとおりです。

The HelpTag software takes your volume.htg file as input.

上記のどちらの例も、%% の対の部分は正規マークアップ (<var>...<¥var>) でも略式マークアップ (<var| ...|) でも入力できます。

ハイパーリンクの作成

ハイパーリンクは、ヘルプ・ボリュームの特定のトピックや位置を参照します。このためには、参照したい要素に固有の ID が指定されていなければなりません。これらのヘルプタグ要素は、<chapter>、<s1...s9>、<location>、、<image>、<figure>、<graphic> などの割り当て済み ID のこともあります。

ヘルプは、5 種類のハイパーリンクをサポートしています。

ハイパーテキスト・リンクは、他のヘルプ・トピックへ「ジャンプ」します。デフォルトでは、新しいトピックは同じウィンドウに表示されますが、新規ウィンドウに表示するよう要求することもできます。
定義リンクは、簡単なポップアップのヘルプ・ウィンドウにトピックを表示します。ほとんどの場合、定義リンクは文中の新しい語句の定義を見るために使用されます。
マニュアル・ページへのリンクは、システムにインストールされているマニュアル・ページを表示します。
実行リンクは、シェル・コマンドまたはプログラムを実行します。これにより、ユーザがハイパーリンクを起動すると発生する動作は、非常に広範囲なものになります。
アプリケーション定義リンクは、アプリケーションが解釈するカスタム・リンクを作成します。これにより、ヘルプ・システムとアプリケーション間の通信機能が提供されます。

ある要素へのハイパーリンクを作成するには、ハイパーリンク・コマンドにその要素の ID を指定します。ヘルプタグは、ID へのハイパーリンク作成に使用できる <xref> と <link> の 2 つの要素が提供しています。また、、<image>、<figure> の各要素は、グラフィック・イメージを使ったハイパーリンクの作成に使用できます。

<xref> 要素の使い方

章や節などのタイトルの要素にリンクする場合、最も簡単な方法は <xref> 要素を使うことです。<xref> を使ってリンクを作成するには、リンク先のトピックの ID を指定します。そのトピックのタイトルが <xref> 要素に代入され、アクティブなハイパーリンクになります。

<xref> で作成されるハイパーテキスト・リンクは、新しいトピックを同じウィンドウに表示します。他のリンク型を使って異なる動作にする場合は、<link> 要素を使用しなければなりません。

また、組み込み ID を持つトピック (<hometopic>、<glossary> など) へジャンプするために <link> を使用できません。それらの要素へのハイパーリンクを作成するには、<xref> 要素を使用しなければなりません。

<xref> を使ってリンクを作成するには

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

   
<xref id>

id は、リンクを作成したい章またはセクションの ID です。ID の大文字と小文字の区別は関係ありません。

次の例は、セクションのタイトルへのリンクを作成します。

<s1 id=colorpalettes>Desktop Color Palettes
.
.
.
To learn how to change the colors used on your desktop,
refer to <xref colorpalettes>.

<xref> 要素がセクションのタイトルに置換されます。このタイトルはハイパーリンクであり、下線によって示されています。この文はヘルプ・ボリュームでは、次のように表示されます。

リンク要素の使い方

標準ハイパーテキスト・リンクを作成するには、<xref> と <link> のどちらの要素も使用できます。しかし、「ハイパーリンクの作成」にあるその他のリンク型を使用するには、<link> 要素を使用しなければなりません。

<link> を使ってリンクを作成するには

同じボリューム内のトピックへジャンプするには、<link> 要素を次のように使用します。

   
<link id>text<¥link>

id は、ヘルプ・ボリュームのどこかで宣言されている ID です。text は、下線によってアクティブなハイパーリンクだと示しているヘルプ・テキストの部分です。

例

次の例は、前の例の <xref> 要素の代わりに <link> 要素を使用しています。

<s1 id=colorpalettes>Desktop Color Palettes
 .
 .
 .
 To learn how to change the colors used on your desktop,
 refer to <link colorpalettes>Desktop Color Palettes<¥link>.

定義済み ID へのリンクを作成するには

定義済みの ID を持つトピック (同じボリューム内) へジャンプするには、<link> 要素を次のように使用します。

   
<link hyperlink="id">text<¥link>

定義済みの ID はすべて _ (下線) 文字で始まります。したがって、hyperlink= "id"の形式を使用する必要があります。

例

次のリンクは、現在のボリュームのホーム・トピックへジャンプします。

Return to <link hyperlink="_hometopic">Introduction<¥link>.

他のボリュームにあるトピックへのリンクを作成するには

他のヘルプ・ボリュームにあるトピックへジャンプするには、次のようにします。

   
<link hyperlink="volume id" JumpNewView>text<¥link>

他のボリューム (ジャンプ先) が登録されている場合は、volume パラメータはボリューム・ファイルのベース名だけです。登録されていない場合は、そのボリュームへの完全パス名を指定しなければなりません。

他のボリュームへのリンクには、JumpNewView パラメータを使うようにします。このパラメータを使うと、ユーザは他のボリュームへジャンプしたことがわかります。前の画面表示が残るので、どこからジャンプしてきたかがわかります。

例

次のリンクは、GeoMap というヘルプ・ボリュームのホーム・トピックへジャンプします。

To view a map of the United States, see <link hyperlink="GeoMap 
_hometopic"> Geography Maps <¥link>.

次の例は同じリンクですが、新規ウィンドウにトピックを表示します。

To view a map of the United States, see <link hyperlink="GeoMap 
_hometopic" type=JumpNewView> Geography Maps <¥link>.

次のリンクは、Intromgr というヘルプ・ボリュームの DesktopKeyboardNav というトピックへジャンプします。

For more information, see <link hyperlink="Intromgr 
DesktopKeyboardNav">Keyboard Shortcuts for the Desktop<¥link>.

目的としているヘルプ・ボリュームがデスクトップに登録されていない場合は、必ずそのボリュームへの絶対パス名を指定するか、helptag.opt ファイルに適切な検索パスを指定してください。

定義リンクを作成するには

用語集にある用語へリンクする場合は、<term> 要素を次のように使用します。

   
<term>text<¥term>

簡易形式では、

   

++text++

<term> 要素を使う場合は、対応する定義が用語集に含まれていることを確認する必要があります。

同じヘルプ・ボリューム内のトピックへリンクする場合は、<link> 要素を次のように使用します。

   
<link id Definition>text<¥link>

id はトピック ID (またはトピック内の要素の ID) で、text はアクティブなハイパーリンクにしたいヘルプ・テキストの部分です。Definition というキーワードは、そのリンクが簡易ヘルプ・ダイアログ・ボックスをポップ・アップで表示するよう指定します。

または、他のヘルプ・ボリューム内のトピックへリンクする場合は、<link> 要素を次のように使用します。

   
<link hyperlink="volume id" Definition>text<¥link>

他のボリューム (リンク先) が登録されている場合は、volume パラメータはボリューム・ファイルのベース名だけです。登録されていない場合は、必ずそのボリュームへの絶対パス名を指定しなければなりません。

例

次のリンクは、著作権のトピックをメタ情報で表示する定義リンクを作成します。

<link hyperlink="_copyright" type=Definition>Version Information<¥link>

「Version Information」の句がハイパーリンク・テキスト (破線の下線) になります。

マニュアル・ページへのリンクを作成するには

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

   
<link manpage Man>text<¥link>

特定のセクションからマニュアル・ページを要求するには、hyperlink パラメータを次のように使用します。

   
<link hyperlink="section manpage" Man>text<¥link>

マニュアル・ページへのリンクの場合、hyperlink パラメータは、端末エミュレータ・ウィンドウで man コマンドを実行するときに入力するのと同じ文字列です。

注 -

アプリケーション用のヘルプを記述していて、マニュアル・ページへのリンクを指定する場合、そのアプリケーションはマニュアル・ページに対する特別なサポートを指定していなければなりません。詳細は、「マニュアル・ページを表示するには」を参照してください。(デスクトップのヘルプ・ビューアでは、マニュアル・ページへのリンクがサポートされています。)

例

次の例は、grep コマンドのマニュアル・ページを表示するリンクです。

Refer to the <link grep Man> grep(1)<¥link> command.

「Man」は <link> 要素へのキーワードです。ですから、man コマンドのマニュアル・ページを表示するリンクを作成する場合は、必ず hyperlink パラメータを使用してください。

Refer to the <link hyperlink="man" Man>man(1)<¥link> command.

特定のセクションにマニュアル・ページを表示するには、マニュアル・ページ名の前にセクション番号を付けます。次のリンクは、セクション 2 から「mkdir」マニュアル・ページを表示します (セクション 1 の同じ名前のマニュアル・ページとは異なります)。

Refer to the <link hyperlink= "2 mkdir" Man>mkdir(2)<¥link> command.

アプリケーション定義リンクを作成するには

<link> 要素を次のように AppDefined パラメータと共に使用します。

   
<link hyperlink="data" AppDefined>text<¥link>

data は、このリンクが起動されるときにアプリケーションに渡されるテキスト文字列で、text はハイパーリンクです。

例

3 種類のレポートを出力するアプリケーションのためのヘルプを記述していると想定します。次のように 3 つのハイパーリンクを作成します。

Choose a report type:
<list plain tight>
* <link hyperlink="Report-Daily" AppDefined>Daily Report<¥link>
* <link hyperlink="Report-Month-To-Date" AppDefined>MTD Report<¥link>
* <link hyperlink="Report-Year-To-Date" AppDefined>YTD Report<¥link>
<¥list>

アプリケーションが、これらの特別なリンクを処理し、ハイパーリンク文字列を解釈するよう設定されている場合は、アプリケーションはユーザが選択するハイパーリンクに基づいて適切なレポートを生成します。

完全な例については、/usr/dt/share/examples/dthelp ディレクトリにあるアプリケーション例のコードを参照してください。

メタ情報トピックへリンクするには

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

   
<link hyperlink="_id">text<¥link>

id は、リンクしたい先の要素に関連付けられた定義済み ID です。text は、アクティブなハイパーリンクにしたい語句です。

メタ情報のセクション内のトピックのほとんどは定義済み ID を持っているので、設計者定義 ID は受け付けません。定義済み ID は、要素名の前に下線文字が付いた形式です。たとえば、<copyright> トピックの ID は _copyright です (大文字と小文字の区別は関係ありません)。

メタ情報の定義済み ID は次のとおりです。

<abstract>: (_abstract)
<copyright>: (_copyright)
<title>: (_title)

<otherfront> 要素で入力されたトピックは、トピック階層にある通常のどのトピックとも同じようにリンクできます。

実行リンクの制御

ほとんどのハイパーリンクは関連するヘルプ・トピックを表示しますが、ハイパーリンクはシェル・コマンドおよびスクリプトを実行することもできます。このリンクを実行リンクと呼びます。実行リンクはユーザのシステムと対話するので、ヘルプ・システムは実行リンクの処理方法をコントロールするための実行ポリシーを提供します。

ヘルプ・システムは、実行リンクの動作を定義するためにリソースを使用します。DtNexecutionPolicy リソースは、ヘルプ・システムによる実行リンクの処理方法を変更するために、アプリケーションのアプリケーション・デフォルト・ファイルに設定されます。そのほかに、ヘルプ・システムは実行別名と呼ばれるリソースを使用します。実行別名は、実行リンクが実行するコマンド文字列またはスクリプトに名前 (またはラベル) を割り当てるリソースです。

実行ポリシーのデフォルト動作

実行リンクが選択され、そのリンクが実行別名を持つ場合、ヘルプ・システムは別名の値を検索してコマンドを実行します。実行別名が定義されていない場合、ヘルプ・システムは、実行されることになるコマンドを示す確認ダイアログ・ボックスを表示して、そのコマンドを実行するか操作を取り消すかをユーザに尋ねます。

実行別名

ヘルプ・ボリュームで実行リンクを使用するときには、実行別名を作成するようにします。これはつまり、アプリケーションのアプリケーション・デフォルト・ファイルに、実際に実行されるコマンドを表す別名 (名前) を定義することです。この方法の 1 つの利点は、実際のコマンドをヘルプ・ボリュームのソース・ファイルから切り離すことです。これにより、ヘルプ・ボリュームのハイパーリンクを変更せずに、アプリケーション・デフォルト・ファイルのコマンドを編集できるようになります。各ハイパーリンクは 1 つの別名を参照します。別名は、内容が編集されても名前が変わることはありません。たとえば、スクリプトを使用するチュートリアル・ヘルプ・ボリュームは、アプリケーション・デフォルト・ファイルでシェル・スクリプト・コマンドを変更することで、特定のシェル環境を簡単にカスタマイズできます。

実行別名を作成するには

実行別名をアプリケーションのアプリケーション・デフォルト・ファイルに作成するには、次のリソース指定構文を使用します。

application_name.executionAlias.alias_name: command

application_name: ヘルプ・ボリュームを所有するアプリケーション名またはクラス名
executionAlias: リソースが別名であると識別するキーワード
alias_name: コマンドに割り当てられた名前
command: このリンクで実行されるシェル・コマンドまたはスクリプト

command 文字列の長さに制限はありません。複数の行に渡るコマンドを入力するには、(最終行を除く) 各行の終わりに ¥ (バックスラッシュ) を付けてください。

例

次のリソース・エントリは、端末エミュレータを起動する StartDtterm という実行別名を作成します。& (アンド記号) は、コマンドをバックグラウンドで実行します。

Dtterm.executionAlias.StartDtterm: dtterm &

次のエントリは、NightAlert というアプリケーションで xclock アプリケーションを実行する xclockAlias という別名を作成します。

NightAlert.executionAlias.xclockAlias: xclock &

ハイパーリンクでの実行別名の使用

実行別名は、<link> 要素を使って参照したり、 や <figure> など、ハイパーリンク・パラメータを持つ要素と共に使用できます。

実行別名を使用して実行リンクを作成するには

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

   
<link "DtHelpExecAlias alias_name [default_command]" Execute >text<¥link>

DtHelpExecAlias: リンクが実行別名であると識別するキーワード
alias_name: 実行別名のリソース指定に別名として定義された名前
default_command オプション: オプションで、これを指定すると、実行別名がアプリケーションのアプリケーション・デフォルト・ファイルからまだ読み込まれていない場合に、このコマンドが実行されます。たとえば、ヘルプ・ビューアなどのインフォメーション・ビューアでヘルプ・ボリュームを表示しているときには、アプリケーションのリソースは読み込まれていません。
text: ハイパーリンク・テキスト (下線が付けられる) として指定したいヘルプ・テキストの部分です。

注 -

実行しているコマンドがすぐに終了しない場合は、そのコマンドに & (アンド記号) を追加してバックグラウンドで実行してください。そうしないと、ヘルプ・ウィンドウはコマンドが終了するまで動作しません。

例

次のハイパーリンクは、xclockAlias という実行別名を参照します。別名のリソース定義は、「実行別名」に示します。

このリンクは、xclock プログラムをバックグラウンドで起動します。「Start the Clock」の句がハイパーリンクになります。そのハイパーリンクをクリックすると、別のウィンドウで xclock プログラムが実行されます。プログラムを終了するには、ウィンドウを閉じてください。

<link "DtHelpExecAlias xclockAlias" Execute>Start the Clock<¥link>

次の例は、同じハイパーリンクにオプションのデフォルト・コマンドを指定しています。

<link "DtHelpExecAlias xclockAlias xclock &" Execute>Start the Clock<¥link>

DtNexecutionPolicy リソース

DtNexecutionPolicy リソースは、システム管理者またはユーザが、指定したアプリケーションに対して適切なセキュリティのレベルを選択できるようにします。

設定できるリソースの値は次のとおりです。

help_execute_query_all: すべての実行リンクを照会します。
help_execute_query_unaliased: 実行別名が定義されていないリンク・コマンドだけを照会します。
help_execute_none: どんな実行リンクも実行しません。
help_execute_all: すべての実行リンクを実行します。

デフォルト値は help_execute_query_unaliased です。実行別名として定義された実行リンクは自動的に実行されますが、その他の実行リンクに関しては、ヘルプ・システムが確認ダイアログ・ボックスを表示します。

アプリケーション開発者が DtNexecutionPolicy を設定することは避けた方がよいでしょう。システム管理者やユーザがこの値を変更できなくなってしまうからです。

グラフィックの表示

ヘルプでは 4 種類のグラフィック形式をサポートしています。

TIFF (Tagged Image File Format)

多くの標準の描画したりスキャンしたりするアプリケーションによって作成されるカラー、グレースケール、白黒イメージ (filename.tif)
X ウィンドウ・ダンプ

xwd ユーティリティで作成される X Window System からの画面ダンプ (filename.xwd)
X ピックスマップ

カラーのアイコン・イメージ (filename.pm)
X ビットマップ

2 色のアイコン・イメージ (filename.bm)

各グラフィックは別のファイルに保存されます。ファイル形式は、上記のファイル名拡張子を使って決定されます。

図を作成するには

図中に取り込むイメージ・ファイルを識別するために、ファイル・エンティティを宣言します。
```
 
<!entity graphic-entity FILE "filename.ext"> 
```
エンティティ宣言はすべて、ヘルプ・ボリュームの最初にある、その他のマークアップよりも前にある必要があることを忘れないようにして下さい。

<figure> 要素を次のように使用します。
```
 <figure entity=graphic-entity> 
caption string
<¥figure> 
```
graphic-entity は、表示したいグラフィック・ファイルのエンティティ名です。caption string はオプションの文字列です。タイトルのテキストはグラフィックの上に表示されます。

デフォルトでは図に番号が付きます。その番号は、タイトルの前につきます。番号を付けない図を作成するには、nonumber パラメータを指定してください (下記の「例」を参照してください)。

図をハイパーリンクにしたい場合は、ghyperlink (グラフィック・ハイパーリンク) と glinktype (グラフィック・リンク型) パラメータを次のように使用します。

<figure entity=graphic-entity ghyperlink="id" glinktype=type>
 caption string
 <¥figure>

ghyperlink パラメータと glinktype パラメータは、<link> 要素の hyperlink パラメータと type パラメータと同じように動作します。

例

以下の例では、ヘルプ・ボリュームの最初で次の 2 つのファイル・エンティティを宣言したと想定します。

<!entity FirstPicture  FILE "first.tif">
<!entity SecondPicture FILE "second.pm">

次の図は first.tif ファイルのグラフィックを表示し、番号 (デフォルト) とタイトルを表示します。
```
 <figure entity=FirstPicture>
Here's the First Picture
<¥figure> 
```
次の例は、番号とタイトルを付けずに second.pm ファイルを表示します。
```
 <figure nonumber entity=SecondPicture>
<¥figure> 
```
図に ID を付けるには、タイトルがなければなりません。タイトルは、<xref> が図の ID を使用する場合に必要です。その場合、タイトルは <xref> の位置に挿入され、その図のハイパーリンクになります。

次の図は、xclock プログラムを実行する実行ハイパーリンクです。

   <figure entity=SecondPicture ghyperlink="xclock &" glinktype=execute>
Choose This Figure to Start the Clock
<¥figure>

インライン・グラフィックを表示するには

図中に取り込むイメージ・ファイルを識別するために、ファイル・エンティティを宣言します。
```
 <!entity graphic-entity FILE "filename.ext"> 
```
エンティティ宣言はすべて、ヘルプ・ボリュームの最初にあるその他のマークアップよりも前にある必要があります。

<graphic> 要素を次のように使用します。
```
 ... text <graphic entity=graphic-entity> text ...
```
graphic-entity は、表示したいグラフィック・ファイルのエンティティ名です。

グラフィックをハイパーリンクとして使用するには、<link> 要素の中に入れます。

<link parameters><graphic entity=graphic-entity><¥link>

注 -

<graphic> 要素は、大きめのイメージの使用も可能ですが、基本的に小さいグラフィック用です。グラフィックの縦の長さが入るように、空白スペースが追加されます。

例

次の例は、文の途中で小さな X ビットマップ・イメージを使用します。まずボリュームの最初で、ビットマップ・ファイルをファイル・エンティティとして宣言しなければなりません。

<!entity StopWatch FILE  "stopwatch.bm">

ヘルプ・テキストの中に、イメージは <graphic> 要素を使って挿入されます。

Whenever you see the <graphic entity=StopWatch> symbol, stop and 
answer the quiz questions.

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

グラフィックのまわりをテキストで囲むには

パラグラフ中に入れるイメージ・ファイルを識別するために、ファイル・エンティティを宣言します。
```
 <!entity graphic-entity FILE "filename.ext"> 
```

 (段落) 要素を gentity パラメータと共に次のように使用します。
```
 Paragraph text here ...
```
graphic-entity は、挿入したいグラフィック・ファイルを参照するエンティティ名です。

例

sample.pm という名前のアイコンを表示して、そのアイコンのまわりをテキストで囲みたい場合は、まずファイル・エンティティを宣言します。

<!entity HelpKeyIcon FILE  "helpkey.xwd">

次に段落を入力します。

<p gentity=HelpKeyIcon gposition=left> The F1 key is a Help key. When 
you press F1, the application you are using displays the help topic 
most closely related to your current activity.

グラフィックを右揃えにするには、次のように gposition パラメータを追加します。

<p gentity=HelpKeyIcon gposition=right>Many desktop components 
support multicolor icons, in addition to two-color images.

次の例は、アイコンのまわりを囲む段落のマークアップです。このアイコンは、新規ウィンドウに icon-editor という ID のトピックを表示するハイパーリンクです。

<p gentity=my-icon ghyperlink="icon-editor" glinktype=JumpNewView> 
Many desktop components support multicolor icons, in addition to the two-color images.

特殊文字の表示

ヘルプタグでは、多くの特殊文字と記号を使用できます。適切なエンティティの参照を入力することで、特定の文字を表示できます。

特殊文字エンティティの一部は helpchar.ent ファイルで宣言されています。helpchar.ent ファイルは /usr/dt/dthelp/dthelptag ディレクトリにあります。これらの文字にアクセスするには、特定のエンティティ宣言を自分のボリュームにコピーするか、helpchar.ent ファイル全体を取り込んでください。不要なエンティティ宣言は無視されます。

使用できる文字のリストについては、第 6 章「特殊文字エンティティの概要」を参照してください。

特殊文字を表示するには

表示したい文字のエンティティ名を定義するには、第 6 章「特殊文字エンティティの概要」を参照してください。また、組み込み特殊文字かどうかに注意してください。

組み込み特殊文字でない場合は、次の 2 行をその他のエンティティ宣言に追加します (entity-name は表示したい文字のエンティティ名です)。
```
 <!entity entity-name FILE "helpchar.ent"> &entity-name;
&entity-name;
```
また、次の行を helptag.opt ファイルに追加します。
```
 search=/usr/dt/dthelp/dthelptag
```
ヘルプタグに組み込まれている文字の場合は、手順 2 を省略できます。

特殊文字を表示したい場所には、エンティティ参照を入力します。
```
   &entity-name;
```

例

著作権の記号 ((c)) のエンティティは組み込み特殊文字なので、次のエンティティを使用するだけで表示できます。

&copy;

大文字のギリシャ文字シグマ (Σ) を表示するには、まず次のように (ヘルプ・ボリュームの最初に他のエンティティ宣言と共に) helpchar.ent ファイルを取り込まなければなりません。

<!entity  SpecialCharacterEntities  FILE   "helpchar.ent">  
&SpecialCharacterEntities;

次に、シグマ文字を表示する場所に次のエンティティ参照を入れます。

&Usigma;

他のエンティティと同じく、特殊文字のエンティティ名において大文字と小文字の区別は関係ありません。

コメントと作成者のメモの取り込み

ソース・ファイルの中に、ヘルプ・テキストの一部にはならないコメントを入れておくと、とても便利です。コメント要素でマークされたテキストは、ヘルプタグ・ソフトウェアには常に無視されます。コメントは、自分自身や他の設計者への注意書きを付けたり、あるマークアップをファイルから取り出さずに除外するのに使用できます。

標準のコメントに加えて、作成者のメモを入力するためにヘルプタグは <memo> 要素を提供しています。メモは、レビューの間はヘルプ・トピックに表示されますが、最終的なヘルプ・ファイルの作成時には表示されません。通例、設計者はレビュー担当者に対して質問や注意書きを記述するのに <memo> 要素を使用します。

コメントを挿入するには

コメントの開始マーク () を次のように使用します。

   
<!-- text here is completely ignored -->

ヘルプタグ・ソフトウェアは、 の間のすべてのマークアップを無視します。コメントは、別のコメントの中に入れることはできません。

例

次の例には 2 つのコメントがあります。1 つは段落の前の行で、もう 1 つはパラグラフ中の語です。

<!-- Here is my rough draft of the introduction: --> 

Welcome to my application. This software
is <!-- perhaps --> the fastest and most
efficient software you'll ever own.

作成者のメモを挿入するには

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

<memo>   
text <¥memo>

デフォルトでは、<memo> 要素内のテキストはヘルプタグ・ソフトウェアには無視されます (コメントと同じ)。しかし、helptag.opt ファイルに memo オプションを追加すると (または dthelptag コマンドで memo オプションを指定すると)、ヘルプ・ボリューム内のすべてのメモがボールド・フォント表示されます。

例

アプリケーションについて記述をしているとき、プロジェクト・チームに対して質問があるとします。<memo> 要素を次のように使用してテキスト内に質問を入れることができます。

<memo>Team: Will the product also
support 32-bit characters?<¥memo>

次のコマンドでヘルプ・ボリュームを処理すると (または helptag.opt ファイルに memo を指定すると)、メモはヘルプ・テキストにボールド・フォントで表示されます。

dthelptag  volume  memo

メモ・オプションを使用しない場合 (または nomemo オプションを使用する場合)、メモ内のテキストは無視され、ヘルプ・テキストには表示されません。

索引の作成

ヘルプ・ボリュームの索引は本の索引と似ています。設計者にとって、トピックの索引エントリを作成することは大切です。それによって、ユーザがキーワードや概念で検索できます。詳細な索引が作成されていると、ユーザはすばやく正確にトピックを見つけられます。

索引エントリをマークするには

索引に入れたいトピックの中で、<idx> 要素を次のように使用します。

   <idx>keyword<¥idx>

略式では、

   <idx|keyword|

エントリをソートするには、<sort> 副要素を次のように使用します。

   <idx>keyword<sort>sortkey<¥idx>

keyword は索引に表示したいテキストで、sortkey はソート時に使用されるテキストです。

<idx> 要素はトピック内のどこでも使用できます。keyword とオプションの sortkey のどちらもトピックには表示されません。

例

次の例は、2 つのキーワード索引エントリを持つトピックの最初の部分です。

<s1 id=getting-started>Getting Started with Helpview
<idx>starting Helpview<¥idx>
<idx> Helpview, starting<¥idx>

Welcome ...
.
.
.

次の例は、キーワード索引の「プラス」という語が入るべき位置に + (プラス文字) を挿入します。

<idx>+<sort>plus<¥idx>

用語集の作成

本の用語集のように、重要な用語を定義する用語集をヘルプ・ボリュームに入れることができます。用語集は <glossary> 要素でマークされ、ヘルプ・ボリュームの最後のトピックになります。

ヘルプ・ボリューム全体を通じて、<term> 要素と共に入力したキーワードとなる語句は、自動的に用語集にあるその用語の定義への定義ハイパーリンクになります。

用語集の用語をマークするには

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

   <term>word or phrase<¥term>

略式では、

   <term|word or phrase|

簡易形式では、

   
++word or phrase++

ヘルプ・テキスト内の用語のスペルが用語集の定義のスペルと完全に同じではない場合は、その用語の「glossary form」(用語集形式) を次のように指定できます。

<term "glossary form">word or phrase<¥term>

glossary form は、その用語が用語集に表示されるとおりの形式です。その用語が (コンテキストにより) ヘルプ・トピックでは複数形でなければならず、用語集では単数形でなければならない場合に便利です。

用語はボールド・フォントで表示され、自動的に定義ハイパーリンクになります。用語が選択されると、用語集の定義が簡易ヘルプ・ダイアログに表示されます。

注 -

故意に用語集に定義しない用語をマークする場合は、<term> 要素に nogloss 属性を追加してください。これにより、その用語は用語用のボールド・フォントで表示されますが、用語集へのリンクは作成されません。

例

用語集に「widget」の定義がある場合は、次のように入力できます。

A ++widget++ is the fundamental building block of OSF/Motif user interfaces.

用語集のエントリは「widget」だが、文中では複数形を使用する必要がある場合、次のように用語を入力できます。

<term  "widget">Widgets<¥term> are the fundamental building blocks 
of OSF/Motif user interfaces.

同じ用語を入力したいが、用語集に入れたくないか、またはハイパーリンクにしたくない場合は、次のように nogloss パラメータを使用します。

<term nogloss> Widgets<¥term>are the fundamental building blocks 
of OSF/Motif user interfaces.

略式では次のとおりです。

<term nogloss|Widgets| are the fundamental building blocks 
of OSF/Motif user interfaces.

用語集に用語を定義するには

<dterm> 要素を用語集に次のように入力します。

   <glossary>      
 .
 .
 .
 <dterm>word or phrase
 Definition of the term
 .
 .
 .

<dterm> の語句は用語集の中で必ずソートしてください。

例

次の例は、用語集の SGML という用語の定義の部分です。

<glossary>
 .
 .
 .
 <dterm>SGML
 Standard Generalized Markup Language. An
 international standard [ISO 8859: 1986] that
 establishes a method for information interchange.
 SGML describes constructs for marking the
 structure of information separate from its
 intended presentation or format.

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

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

概要

ヘルプ・ボリュームを表示するには、ヘルプタグ・ソフトウェアでファイルを処理し、実行時のヘルプ・ファイルを作成しなければなりません。実行時のファイルは、セマンティック・デリバリ言語 (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 コマンドを次のように実行します。

   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 の参照

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

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

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

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

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

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

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

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

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

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

手動で 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 ヘルプ・ファミリを表示するブラウザ・ヘルプ・ボリューム

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

ブラウザ・ボリューム

デスクトップ・ユーティリティはブラウザ・ボリュームを作成および更新します。ユーザが初めてフロントパネルの [ヘルプ・ビューア] をクリックすると、このユーティリティが自動的に実行されます。このユーティリティは、ヘルプ検索パス・ディレクトリにあるヘルプ・ボリュームとヘルプ・ファミリ・ファイルを識別します。このユーティリティは、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

ヘルプ・トピックの印刷

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

図 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 つも発生しないことを確認してください。

第 5 章ヘルプタグ・マークアップのリファレンス

この章では、ヘルプタグのマークアップ要素 (およびそれに指定するタグ) のすべてをアルファベット順に説明します。

マークアップ要素の解説

タグ名は使い方に応じて付けますが、それを決めるときに役立つよう、要素は次のように使い方でグループ化されています (1 つ以上のグループに表示される要素もあります)。

メタ情報 (ボリュームに関する情報)

<metainfo>
<title>
<copyright>
<abstract>
<otherfront> (非階層トピック)

ヘルプ・ボリュームの構造

<!entity>
<helpvolume>
<hometopic>
<chapter>
<s1>...<s9> (ヘッダ)
<rsect>(参照セクション)
<otherhead>
<procedure>
 (段落)

インライン要素

<book>
<computer>  (簡易: "text")       
<emph>  (強調表示) (簡易: !!text!!)      
 <ex>  (例) and <vex>  (逐語例)       
<image>       
<keycap> (簡易: [[ text ]])       
<lineno> (行番号)       
<newline>       
<p>  (段落)       
<quote> (引用)       
<sub> (サブスクリプト) (簡易: _ _ text _ _)       
<super> (スーパースクリプト) (簡易: ^^text^^)       
<term>  (簡易:  ++text++)       
<user>  (ユーザ入力)       
<var>  (変数) (簡易: %%text%%)       
&...; ( <!entity> 参照)

重要情報

<note>       
<caution>       
<warning>       
<emph>  (強調表示) (簡易: !!text!!)

リスト

<list>       
<lablist>  (ラベル付きリスト)       
<item>  (簡易: *)

グラフィック

<figure>       
<graphic>

用語集と索引

<glossary>       
<dterm>  (用語定義)      
<term>  (簡易: ++text++)       
<idx>  (索引)

相互参照とハイパーリンク

<xref>  (相互参照)       
<link>       
<location>       
<term>

隠しテキスト

<!-- ... --> (コメント)       
<memo>

タイトルとヘッダ

<abbrev>      
<head>       
<otherhead>       
<procedure>       
<title>  (ヘルプ・ボリュームのタイトル)

ヘルプタグ・マークアップの無視

<vex>  (逐語例)

コメントヘルプタグ・ソフトウェアが無視するテキストです。コメントはネストされません。

形式

<!-- comment text here -->

コメント・テキストには 2 つの破線 (--) 以外の任意のテキストを指定できます。

例

次のマークアップは、コメントと図の両方を非表示にします。

<!-- Let's leave out this figure for now:
<figure entity=ProcessFlowChart>
Before and After Processing
<¥figure>
-->

<abbrev>

省略タイトル

タイトルが長いトピックの代替ヘッダで、通常は短くした形式のタイトルです。省略タイトルを指定すると、[索引] ダイアログ・ボックスと [ヒストリ] ダイアログ・ボックスで完全なタイトルの代わりに使用されます。

ヘッダにグラフィック要素が入っている場合は、ヘッダのテキストだけが入った <abbrev> を指定してください。グラフィック・イメージはトピック・ツリーに表示されますが、[索引] ダイアログ・ボックスと [ヒストリ] ダイアログ・ボックスはグラフィック要素を表示できません。

<abbrev> にはマークアップ機能がありません。

形式

<topic-element> title
<abbrev> short title

topic-element は <hometopic>、<chapter>、<s1>、または新しいトピックとなる任意の要素です。

<abbrev> タグは、ヘッダの直後の行に表示してください。

終了タグは必須ではありません。

例

簡単な例を示します。

<chapter> Ways of Treating Headings that are Too Long
<abbrev> Long Headings

トピックのタイトルをヘルプ・トピック表示領域には表示したくないが、トピック・ツリーにはタイトルを表示したいとします。この場合、次のようにマークしてください。

<chapter> &empty;
<abbrev> chapter title

<abstract>

概要

ヘルプ・ボリュームの簡単な説明です。

形式

<metainfo>
   .
   .
   .
   <abstract>
   abstract text here ...
   <¥abstract>
   .
   .
   .
<¥metainfo>

概要はマークアップを認識しないアプリケーションが読んだり表示したりするため、概要のテキストにはヘルプタグ・マークアップを入れません。

<abstract> 要素は自動的に ID 文字列 _abstract に割り当てられます。設計者が定義した ID は割り当てられません。_abstractID は <link> 要素と共に使用できますが、<xref> 要素とは使用できません。

概要のテキストにはオプションの <head> があります。

例

次のマークアップは、ヘルプ・ボリュームの内容を簡単に記述しています。

<abstract>
Online help for the Application Manager Version 1.0.
<¥abstract>

注

要素を <metainfo> 要素内でリンクさせるときは、必ず type=Definition リンクにしてください。

次の例は概要をリンクさせる方法を示します。

<link hyperlink= "_abstract" type=Definition>
Choose this link for an abstract.<¥link>

<<`annotation text`>>

注釈

例 (<ex> タグ) の中で説明補足やコメントを提供します。

形式

<ex [side | stack]>
text of the example ...<<annotation text >>
<¥ex>

side: デフォルトです。例の 1 行目のテキストの右側に注釈を入れます。
stack: テキストの下に注釈を入れます。

注釈のテキストは、<< this is the annotation text>> のように二重三角括弧で囲んでください。<ex> タグでのみ注釈が使用できます。<ex> タグの side パラメータおよび stack パラメータは、テキストに関連する注釈の位置を指定できます。

注釈に空白行を入れるには、スペースの後に空の注釈、つまり空白 <<>> を入れてください。

例

次のマークアップは注釈のデフォルト side の配置方法を使用します。

<ex>
Login: <<Enter your name>>
<¥ex>

出力は次のとおりです。

次のマークアップは stack の配置方法を使用して長い注釈を入れます。

<ex stack>
 Quarterly Sales Reports

<<Q1: January, February, March Q2: April, May, June Q3: July, August, 
September Q4: October, November, December>>
 <¥ex>

出力は次のとおりです。

<book>

本のタイトル

本のタイトルを指定します。

形式

<book>book title<¥book>

または

<book|book title|

ヘルプタグ・フォーマットではイタリックで本のタイトルを示します。日本語では、イタリック書体のフォントが提供されていない場合、それに代わる書体、たとえばボールドで表示されます。

例

次の 2 種類があります。

Refer to <book>The Elements of Style<¥book>
for further details.

または

Refer to <book|The Elements of Style|
for further details.

出力は次のとおりです。

Refer to The Elements of Style for further details.

<caution>

注意の通知

ユーザにデータの損失か破損の可能性があることを警告します。

形式

<caution>
text of caution<¥caution>

デフォルト・ヘッダは「Caution」(日本語ロケールでは「注意」) です。別のヘッダを指定するには、次のように <head> タグを使用します。

<caution><head>alternate heading
text of caution
<¥caution>

<¥caution> 終了タグが必須です。

アイコンを、注意と共に表示されるように指定するには、ファイル・エンティティを次のようにヘルプ・ボリュームの最上部に定義します。

<!entity CautionElementDefaultIconFile FILE  "filename">

filename はアイコン・グラフィック名です。cautions.pm という例の注意アイコンは /usr/dt/dthelp/dthelptag/icons ディレクトリにあります。

例

次の例は注意メッセージです。

<caution>
There is no Undo for this selection. Before performing this task, 
save any changes to your document.
<¥caution>

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

<chapter>

章

新しいタイトルの新しいトピックの最初を示します。

形式

<chapter id=id>title
topic text ...

終了タグは必須ではありません。

トピックのタイトルが長い場合、代わりに <abbrev> で省略タイトルを指定できます。短いタイトルは [索引] ダイアログ・ボックスと [ヒストリ] ダイアログ・ボックスで使用されます。タイトルにグラフィック要素があれば、テキストだけのタイトルで <abbrev> を作成してください。

例

次の 2 つは新しいトピックの開始を示すマークアップ例です。

<chapter>A Manual of Style
<chapter id=DesktopTools>Desktop Tools

<computer>

コンピュータ・リテラル

コンピュータの入出力を示すテキストを表示します。

形式

<computer>text<¥computer>

または

"text"

簡易形式では 2 つの左アポストロフィ (") と 2 つの右アポストロフィ (") を使用します。

例

マークアップは次のとおりです。
```
 <computer>Enter the correct numerical value.<¥computer> 
```
出力は次のとおりです。

Enter the correct numerical value.
次のマークアップは簡易形式を使用しています。
```
   Everything in "computer" comes out looking "like this."
```
出力は次のとおりです。

Everything in computer comes out looking like this.
変数はコンピュータ・テキストで使用できます。例を示します。
```
   ``void DisplayTopic (%%topic%%);'' 
```
出力は次のとおりです。

void DisplayTopic (topic);

<copyright>

著作権の告知

著作権を告知します。

形式

<metainfo>
  <title>Title (always before copyright)
  <copyright>
  &copy; Copyright notice here ...

この要素は <metainfo> セクションでのオプションです。使用する場合は、<title> 要素の後に入力してください。

終了タグは必須ではありません。

あらかじめ定義されたエンティティ © は、著作権記号 ((c)) を生成します。

例

次のマークアップはヘルプ・ボリュームにタイトルを付けて、著作権情報を提供します。

<metainfo>
<title>XYZ World Almanac
<copyright>
&copy; Copyright 1995 XYZ Company. All rights reserved.

出力は次のとおりです。

<dterm>

用語の定義

用語集にある用語および用語の定義を識別します。

形式

<glossary>
  <dterm>first term
  definition of first term
   .
   .
   .
  <dterm>Nth term
  definition of Nth term

この要素は <glossary> セクションで使用されます。

<dterm> タグの後に用語名が続く形で、1 行で表示されます。用語の定義は <dterm> タグに続く行から始まります。

終了タグは必須ではありません。

例

次のマークアップは、用語集で最初の 2 語を定義します。

<glossary>

<dterm>algorithm
A mathematical rule or procedure for solving a problem.

<dterm>click
To press and release a mouse button.

<emph>

テキストの強調表示

テキストを、注意を促すフォントにします。

形式

<emph>text<¥emph>

または

!!text!!

<emph> 要素の簡易形式は、テキストの前後に二重の感嘆符 (!!)を付けます。

開始タグ <emph> を使用した場合は、終了タグ <¥emph> が必須です。

例

次の 2 つのマークアップのうちいずれかを使用します。

A thousand times <emph>no<¥emph>.
A thousand times !!no!!.

出力は次のとおりです。

A thousand times no.

<!entity>

エンティティの宣言

エンティティ名を文字列または外部ファイルに指定します。

形式

<!entity entityname "string">

または

<!entity entityname FILE "filename">

エンティティ名は 64 字以下の英字、数字、ハイフンで指定できます。大文字小文字の区別はエンティティ名については重要ではありませんが、設計者が読みやすいように使い分けることが多いです。先頭の文字は英字で始めなければなりません。<!entity> 宣言の中の < (左三角括弧)、! (感嘆符)、entity の間には、スペースを入れないでください。

エンティティの宣言は、常に他のマークアップまたはヘルプ・ボリュームのテキストより前に入れなければなりません。

定義したエンティティを表示させるときは、次の形式を使用するエンティティの参照を挿入します。

&entityname;

エンティティの参照は & (アンド記号) の後にエンティティ名 (エンティティの宣言で定義) が続き、最後に ; (セミコロン) が付きます。

エンティティの目的

エンティティは、次の 4 つの理由により定義します。

エンティティ名で指定されたテキストは一度しか表れないため、テキストを変更するときは 1 箇所変更するだけで済みます。ヘルプタグがファイルを再処理するとき、エンティティの参照はすべて自動的に変更されます。
テキストが何度も表示される場合でも、略式のエンティティの参照を入力すればよいので、長く複雑なテキスト文字列を繰り返し入力するという無駄な労力 (あるいは入力ミス) を省くことができます。完全なテキスト文字列を入力するのは一度だけで済みます。
<figure> 要素および <graphic> 要素にファイル名は適用できません。図を含むファイル名は、エンティティの宣言で指定してください。
ヘルプ・テキストを複数のファイルに入れると便利ですが、ヘルプタグは 1 つのソース・ファイルしか受け入れません。実際のヘルプ・テキストを含むファイルを参照するエンティティの宣言とエンティティの参照を含むファイルを 1 つ作成することによってこの矛盾を是正できます。

例

volume.htg ソース・ファイルには次のようなエンティティの宣言およびエンティティの参照が含まれているので、実際のテキストが指定したファイルに挿入されます。
```
 <!entity topic1 FILE "topic1">
 <!entity topic2 FILE "topic2">
 <!entity topic3 FILE "topic3">

 &topic1;
 &topic2;
 &topic3;
```
次のエンティティの宣言にある「Architectural Analysis of Aircraft Precision Components」という語は、マークアップ・ファイルのエンティティの参照では &apc; と表示されます。
```
 <!entity apc "Architectural Analysis of Aircraft Precision Components"> 
```
次のような図に対するエンティティの宣言は、ソース・ファイルの先頭に置かれます。
```
 <!entity CloseUpFig FILE "figname.tif"> 
```
図は次のマークアップの場所に挿入されます。
```
 <figure entity=CloseUpFig>
Close Up View
<¥figure> 
```

<esc>

エスケープ

テキストがヘルプタグで解釈されずに、実行時のヘルプ・ファイルへ直接渡されます。たとえばカスタマイズされたアプリケーションでは、設計者がヘルプ・ソース・ファイルに SDL (セマンティック・デリバリ言語) マークアップを埋め込むことができます。<esc> 要素があると、ヘルプタグ・パーサは SDL マークアップを読みません。ヘルプ・ボリュームがヘルプ・ビューアで表示されると、設計者が入れた SDL マークアップが処理されます。

個々のヘルプタグ記号やマークアップ例をエスケープするときは <esc> タグを使用しないでください。< (左三角括弧) や ¥ (バックスラッシュ)、& (アンド記号) などのヘルプタグ記号を表示するには、各記号の前にアンパサンドを付けます。<vex> 要素を入れると、ヘルプ・ボリュームにヘルプタグ・マークアップ例が入れることができます。

形式

<esc>text<¥esc>

または

<esc|text|

注 -

正規の形式を使用する場合、テキストには <¥x という 3 文字の文字列 (記号、バックスラッシュ、文字の順) は入りません。略式を使用する場合はテキストには | (縦線) は入りません。

前者の形式を使用するときは <¥esc> 終了タグが必須です。

<ex>

コンピュータの例

スペースまたは行の切れ目を変更せずにテキストを表示します。

形式

<ex [nonumber | number] [smaller | smallest] [side | stack]>
example text here ...<¥ex>

nonumber: (デフォルト) 各行頭に入る行番号を省略します。
number: 各行頭に行番号を付けます。
smaller: より小さいフォントを使用して例を表示します。
smallest: 最も小さいフォントを使用して例を表示します。長い行のものを狭い幅の中に表示します。
side: 例に注釈を入れるときだけ適用します。テキストに関連する注釈の位置を指定します。デフォルト位置は side で、テキストの 1 行目の右側に注釈が表示されます。
stack: テキストの下に注釈が表示されます。

例は、固定幅の文字で左揃えで表示されます。

number 属性を入れると、行番号が付けられます。特定の行を参照するときに便利です。

次に示す例は、他のコンテキストでは特殊な意味を持つ文字ですが、<ex> では通常のテキストとして扱われます。

!!	二重感嘆符
--	二重マイナス記号
++	二重プラス記号
"	二重引用符

<¥ex> 終了タグが必須です。

例

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

<ex>
Examples are printed in computer
font. Line breaks are preserved.
<¥ex>

出力は次のとおりです。

<figure>

図

グラフィック・イメージを挿入します。

形式

<figure entity=entity [id=id [nonumber | number=n]
[left |center | right] [cappos=[capleft | capcenter | capright]]
[ghyperlink=id [glinktype=type] [gdescription=text ]]] >
caption string<¥figure>

entity=name: 挿入するグラフィック・イメージを含むファイルを識別するファイル・エンティティを指定します。
id=name: オプションで、図の相互参照に使用する ID 名を定義します。
nonumber: オプションで、「Figure」(日本語ロケールでは「図」) という語と図番号は自動的に生成されません。
number=n: オプションで、自動的に生成された図番号を無効にし、指定された番号を使用します。
left、center、right: 現在のページ幅の範囲内で、イメージの水平位置を揃えるよう指定します。
cappos=position: capleft、capcenter、capright の値で、タイトルの水平位置を揃えるよう指定します。タイトルはオプションです。
ghyperlink="id": オプションで、ハイパーリンクにしたい図のグラフィカルな部分を指定します。<link> 要素の hyperlink 属性と同じように使用します。指定した idによって位置を参照します。
glinktype=type: オプションで、ハイパーリンクの種類を指定します。デフォルトは Jump です。他には JumpNewView、Definition、Man、Execute、 AppDefined があります。このパラメータを使用するときは ghyperlink パラメータと id 値が必要です。<link> 要素の type 属性と同じように使用します。
gdescription="text": オプションで、ハイパーリンクの記述を提供します。このパラメータを使用するときは ghyperlink パラメータと id 値が必要です。

<¥figure> 終了タグが必須です。

外部グラフィック・ファイルをヘルプ・トピックに統合するには、そのグラフィックのファイル名をエンティティ名に対応付けるようエンティティを宣言してください (<!entity entityname FILE "filename ">)。

例

次のマークアップは、指定したタイトルの付いたグラフィックを挿入し、自動的に図番号を付けます。
```
 <!entity MapFigure FILE "worldmap.xwd">
 .
 .
 .
 <figure entity=MapFigure>
 Caption for Figure
 <¥figure> 
```

次のマークアップは、タイトルなしで図番号の付いた図を挿入します。

   <!entity StateMap FILE  "oregon.xwd">
   .
   .
   .
<figure entity=StateMap>
<¥figure>
   .
   .
   .

次のマークアップは、指定した図番号とタイトルの付いた図を挿入します。タイトルは ¥ (バックスラッシュ) のところで 2 行に分かれます。
```
 <figure number=99 entity=SchemDiag>
Schematic that Illustrates¥the Overall System Design
<¥figure> 
```

<glossary>

用語集

要素でマークされたすべての用語の定義を含む用語集セクションを開始します。

形式

<glossary>
<dterm>first term
 definition of first term can continue over multiple lines or paragraphs

 <dterm>second term
 definition of second term ...
    .
    .
    .

「Glossary」(日本語ロケールでは「用語集」) は、用語集セクションのヘッダとして自動的に使用されます。

<dterm> 要素は各用語とその定義を識別します。

nogloss パラメータなしで <term> でマークした用語はすべて用語集に入れなければなりません。その語が用語集にない場合、入っていない用語はヘルプタグを実行するときに作成される volume.err ファイルにリストされます。

終了タグは必須ではありません。

例

次の例は、2 つの定義を持つ簡単な用語集です。

<glossary>
 <dterm>oxymoron
 A combination of contradictory words.
<dterm>veritable
 Being in fact the thing named. Authentic.

<graphic>

インライン・グラフィック

テキストの行にグラフィカル要素を挿入します。

形式

<graphic entity=name [id=id]>

name: エンティティの宣言で定義されているエンティティ名。この宣言により、挿入するグラフィックを含むファイル名にエンティティ名が対応付けられます。
id=name: オプションで指定します。図の相互参照に使用する ID 名を定義します。

<graphic> 要素は <figure> に似ていますが、<figure> が段落間に図を挿入するのに比べて、<graphic> ではテキスト間に小さな図を埋め込む点が異なります。

例

次のマークアップは、最初にグラフィック・ファイル (mini.pm) の内容に対応するエンティティ (mini-icon) を定義します。次に、グラフィックを入れる位置をテキスト行で指定します。
```
 <!entity mini-icon FILE "mini.pm">
 .
 .
 .
The <graphic entity=mini-icon> icon is used to represent very
small images.
```

次のマークアップは、最初に mini-icon-topic という ID を持つトピックを定義します。ハイパーリンクとしてのインライン・グラフィックの使い方を次に示します。
```
<s1 id=mini-icon-topic>When you click on the inline graphic, it 
will bring you to this topic.
.
.
.
The <link mini-icon-topic> <graphic entity=mini-icon> <¥link> 
icon is to represent very small things.
```

<head>

ヘッダの挿入

通常はタイトルを付けない要素 (<abstract>、<paragraph>、<list>、<otherfront> など) や、デフォルトのタイトルが付いている要素 (<note>、<caution>、<warning> など) にタイトルを付けます。

形式

<element><head>title text

ヘッダは、<head> タグとタグの後の空白以外の文字とで始まります。<head> タグはヘッダを追加する行かそれ以下の行に表示します。

<head> 要素はタイトルと見なされる要素と共に使用できますが、この場合は <head> を付ける必要はありません。

ヘッダ領域より長いヘッダは、自動的に次の行に表示されます。強制的に行の切れ目を入れるには、該当する場所に ¥ (バックスラッシュ) を入れてください。

& (アンド記号) で終了させない限り、ヘッダはソース・ファイルの行末で終了します。ヘッダがソース・ファイルの中で複数行にわたる場合は、最終行以外の各行の最後にアンド記号を入れてください。

終了タグは必須ではありません。

例

次のマークアップは、タイトルをリストに追加し、¥ (バックスラッシュ) の表示された場所で新しい行が開始するよう指定します。
```
<list><head>Printing Options¥for the QRZ Hardware
```
出力は次のとおりです。
次のマークアップは、デフォルトの「Note」(日本語ロケールでは「注」) のヘッダを無効にし、指定されたヘッダに置き換えます。
```
 <note><head>Tips and Shortcuts
Keyboard menu accelerators provide quick access to menu commands.
<¥note> 
```
出力は次のとおりです。

<helpvolume>

アプリケーション・ヘルプ・ボリューム

「ルート」構造要素で、全ヘルプ・ボリュームのマークアップすべてが含まれています。

形式

all entity declarations
    .
    .
    .
 <helpvolume>
    .
    .
    .
    all of your help is included here, either
    literally or using file entity references
    .
    .
    .
 <¥helpvolume>

このタグを入力しない場合は、ヘルプタグ・ソフトウェアが自動的にタグがあるものと見なして処理します。

エンティティの宣言はすべて、<helpvolume> 開始タグの前になければなりません。

<hometopic>

「ホーム」ヘルプ・トピックまたは最上位のヘルプ・トピック

最上位ヘルプ・トピックの始まりを示します。

形式

<hometopic>heading
 topic text begins here ...

ヘルプ・ボリュームのホーム・トピックは 1 つだけです。これは、メタ情報 (<metainfo>) の後で、最初の <chapter> または <s1> の前に付きます。

<hometopic> 要素は設計者が定義した ID をサポートしません。ヘルプタグ・ソフトウェアが定義済み ID の _hometopic を割り当てます。

ハイパーリンクをホーム・トピックに作成する形式は次のとおりです。

<link hyperlink= "_hometopic">...<¥link>.

例

 <hometopic>Welcome to Online Help
 This is the home topic for the online help ...
 
 <chapter>First Subtopic
 This is the first subtopic ...

 <chapter>Second Subtopic
 This is the second subtopic ...
    .
    .
    .

<idx>

索引エントリ

ヘルプ・ボリューム索引に表示するエントリを定義します。

形式

<idx>text<¥idx>

または

<idx|text|

または

<idx>text<sort>sort key<¥idx>

text: キーワード索引に表示されるテキスト文字列です。
sort key: 索引をソートするときに使用する任意のテキスト文字列です。キーワード索引の text が表示される場所に影響を与えます。sort key 文字列はキーワード索引には表示されません。

一般的なヘルプ・ダイアログ・ボックスの [索引] ボタンを選択すると、[索引検索] ダイアログ・ボックスが表示されます。索引エントリをヘルプ・トピックに追加すると、ユーザが索引の語句を検索して目的のヘルプを見つけるのに役立ちます。

開始タグと終了タグ <idx>、</idx>、または略式マークアップ <idx|...|> が使用できます。

<sort> 要素は索引エントリをソートする順序を変更します。特に、<idx> 要素で使用すると、sort key 文字列で示された場所にキーワードが表示されます。終了タグは必須ではありません。

例

次のマークアップは、一部の索引エントリの定義を略式で記述してます。索引エントリはソース・テキストを読みやすくするためにインデントしています。

A portable personal computer has a full-sized keyboard, built-in 
disk drives and a detachable LCD screen.
		<idx|keyboard|
 		<idx|disk drive|
 		<idx|screen, LCD|
 		<idx|personal computer, portable|
 		<idx|portable, personal computer|

次の例では索引に「+」が表示されますが、エントリのアルファベット順リストで「plus」が表示される場所に表示されます。
```
<idx>+<sort>plus<¥idx> 
```

<image>

イメージ表示

ソース・テキストと同じように改行が入ったテキストを表示します。

形式

<image [indent][id=id][gentity=graphic-ent [gposition=pos] [ghyperlink=gid
   [glinktype=type]]]>text <¥image>

indent: オプションで、パラグラフを現在の左マージンからスペース 6 つ分だけインデントするよう指定します。
id=id: オプションで、この位置を相互参照するのに使用する ID 名を定義します。
gentity=graphic-ent: オプションで、テキストに囲まれるグラフィックのエンティティ名です。gposition、ghyperlink、qlinktype パラメータのいずれかを使用する場合は、gentity パラメータと graphic-ent 値は必須です。
gposition=pos: オプションで、left または right は、任意のグラフィックをそれぞれ左揃えまたは右揃えにします。
ghyperlink=gid: オプションで、グラフィックをハイパーリンクとして指定し、ハイパーリンクの宛先を指定します。glinktype パラメータを使用する場合は、ghyperlink パラメータと gid 値は必須です。<link> 要素の hyperlink 属性と同じように使用します。(イメージ・テキストの位置を参照するときは gid 値ではなく id 値を使用します。)
glinktype=type: オプションで、ハイパーリンクの種類を指定します。デフォルトは Jump です。他には、 JumpNewView、Definition、Man、Execute、 AppDefined があります。<link> 要素の type 属性と同じように使用します。
text: グラフィックのまわりを囲むパラグラフのテキストです。

<image> タグと <¥image> タグとの間のテキストは、実際のテキストと同じスペース、同じインデント、同じ改行で表示されます。均等割付、ワード・ラップ、空白行の削除は行われません。ただしプロポーショナル・フォントを使用すると、画面上ではきちんと並んでいたテキストのカラムがヘルプ情報ではそのとおりにならない場合もあります。表示されたテキストの幅が大きすぎて表示領域に収まらないときは自動的に水平スクロール・バーが表示されます。

すべてのインライン・テキスト要素と特殊文字が認識されます。

任意の <head> を <image> で使用できます。<xref> を使用する要素を相互参照する場合は <head> タグが必須です。

indent パラメータを使用すると、表示されたテキストが左マージンからインデントされます。

開始タグと終了タグ (<image> と <¥image>)、または簡易形式マークアップ (<image|...|) を使用できます。

<item>

リスト項目

リストの項目を示します。

形式

<list [id=id]>
  * List item
  * List item
<¥list>

または

<list order>
   <item id=name1>List item
   <item id=name2>List item
   <item id=name3>List item
    .
    .
    .
 <¥list>

通常 * (アスタリスク) を付けた簡易形式で使用されます。

正規の形式では、リストの項目を相互参照できます。これができるのは順序が付いた (番号が付けられた) リストの項目についてのみです。自動的に割り当てられた項目番号が、相互参照テキスト (ヘルプタグが <xref> 要素と置き換える) で使用されます。番号とは違い、黒い丸の行頭文字は相互参照テキストで置き換えても意味がありません。

<keycap>

キーボード・キー

キーボードのキーを示します。

形式

<keycap>keycap characters<¥keycap>

または

[[keycap characters]]

略式では、[[ (二重左角括弧) と ]] (二重右角括弧) をキーの文字の前後に付けます。

矢印など、特殊記号文字に対するエンティティの参照を使用できます。行をまたがってキーの文字を使用することはできません。

例

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

Press [[Control]] + [[Home]] to go to the beginning of your document.

出力は次のとおりです。

<lablist>

ラベル付きリスト

左カラムにラベルが表示され、右カラムに (ラベルが指定する) 項目が表示される形式のラベル付きリストを表示します。

形式

<lablist [loose | tight][wrap | nowrap]>
[ <labheads>  ¥Heading 1 ¥  Heading 2 ]
 ¥label¥ text for the first item
 ¥label¥ text for the second item
    .
    .
    .
 <¥lablist>

loose: デフォルトで、リストの項目間で行送りをします。
tight: リストの項目間で行送りをしません。
wrap: デフォルトで、長いラベルを複数行に改行させます。
nowrap: ラベルを複数行に分割されないようにします。

バックスラッシュ (¥) はラベルの最初と最後を示します。先頭と末尾のスペースは無視されます。長いラベルは nowrap を使用しない限り複数行に分割されます。あらかじめ定義された文字エンティティ (&sigspace;) は、ラベルに非分割スペースを挿入するのに使用できます。

ラベル付けされた項目のテキストは 2 番目のバックスラッシュの後で、その行かそれ以下の行に入ります。項目の最後は次のいずれかで示されます。

空白行
他のラベル付き項目の最初
<¥lablist> 終了タグ

ラベル付き項目が 1 つ以上のパラグラフから構成されている場合、パラグラフ間に空白行を入れてください。ラベル付きリストの最後は、必須の <¥lablist> 終了タグで示されます。

カラムごとに 1 つ付いている任意のカラム・ヘッダは、<labheads> タグの直後に (同じ行に) 入ります。カラム・ヘッダは ¥ (バックスラッシュ) で分割されます。終了タグ <¥labheads> は必須ではありません。ただし、<lablist> の終了タグは必須です。

例

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

<lablist tight>
 <labheads>  ¥ Unit ¥ Meaning
 	¥in¥ inches
 	¥mm¥ millimeters
 	¥cm¥ centimeters
 <¥lablist>

出力は次のとおりです。

Unit: Meaning
in: inches
mm: millimeters
cm: centimeters

次のマークアップは、長いラベルを複数行に分割します。

<lablist>
 ¥Creating Your System Password:¥
 To log into your computer, you must enter a password.

 ¥Viewing the Message of the Day:¥
 To view the message of the day when you log into your computer, edit 
your startup configuration file.

 ¥Setting the System Time and Date:¥
 To set the date enter the day, month, and year in the format dd-mm-
yy. To set the time, use the format hh-mm-ss.
 <¥lablist>

出力は次のとおりです。

同じマークアップに nowrap パラメータを追加すると、次のように出力されます。

<lineno>

行番号

例の中の指定された行へ相互参照します。

形式

<ex number>
 example text <lineno id=name>
 .
 .
 .
<¥ex>

この要素は、番号が付けられた例でのみ使用されます。参照したい行の最後に <lineno> タグを入力します。id パラメータは、相互参照の作成に使用できる ID を行番号に割り当てます。

例

このマークアップは番号が付けられた例で、3 行目への相互参照が記述されています。

<ex number>
 Enter Daily Account Total
 Run Invoice Summary Report
 Go to Monthly Ledger <lineno id=ledger>
 Run Daily Update
 <¥ex>
 .
 .
 .
 To run closing reports, return to <xref ledger> and run the Past Due Accounts Report.

<xref ledger> 相互参照は ID が入っている行番号に置き換えられます。次の行が出力されます。

To run closing reports, return to 3 and run the Past Due Accounts Report.

<lineno> の終了タグは必須ではありません。

<link>

ハイパーリンク

テキストまたはインライン <graphic> をハイパーリンクとして使用されるように指定します。

形式

<link hyperlink [type] ["description"]>text<¥link>

または:

<link hyperlink= "hyperlink" [type=type] [description= "description"]>

hyperlink 属性は必須で、宛先やリンクの動作を識別する値です。標準の「jump」リンクの場合、hyperlink はジャンプしたい要素の ID です。

type パラメータは次の値を取ることができます。

Jump: デフォルトで、ID hyperlink があるトピックへジャンプします。
JumpNewView: ID hyperlink があるトピックへジャンプしますが、アプリケーションが新規ウィンドウでトピックを表示するように要求します。
Definition: 一時ポップアップ・ウィンドウに、ID hyperlink があるトピックを表示します。
Execute: hyperlink 文字列をコマンドとして実行します。
Man: man コマンドへのパラメータとして hyperlink 文字列を使用してマニュアル・ページを表示します。
AppDefined: 特殊な処理のために hyperlink 文字列をアプリケーションへ送信します。

開始タグと終了タグの間の text は、リンクを起動するためにユーザが選択する「ホット・スポット」になります。ハイパーリンクとして使用される語句には、表示のとき下線が引かれます。大文字と小文字の区別は、hyperlink や type の値では意味はありません。

コマンドを実行するハイパーリンクは、実行リンクと呼ばれます。実行されるコマンドは <link> コマンドに取り込んだり、実行別名として定義したりでき、一種のリソースです。実行リンクの使用については、「実行リンクの制御」を参照してください。

注

hyperlink に対する値として type キーワード (上記のリスト参照) を使用しないでください。使用しなければならない場合は、形式の 2 行目にあるようにパラメータを明示的に指定してください。
<xref> 要素が使用されているところではハイパーリンクは自動的に作成されるので、<link> 要素は <xref> 要素を使用する相互参照では必須ではありません。

例

次のマークアップは、ID Intro が付いたトピックへの単一ハイパーリンクを定義します。ID の大文字と小文字の区別には意味がありません。
```
 <s1 id=Intro>Introducing the Desktop
 .
 .
 .
 Refer to the <link intro>Introduction<¥link>.
```
次のマークアップは、前の例にあるのと同じハイパーリンク・ジャンプを定義しますが、相互参照 (<xref...>) は自動的にハイパーリンクになるので <link> 要素は使用されません。この場合、Intro トピックのタイトルはヘルプタグによって自動的に指定されます。
```
 Refer to <xref intro>.
```
このマークアップの出力は、次のとおりです。
```
 Refer to Introducing the Desktop.
```
次のマークアップは、インライン・グラフィックが選択されたときに起動されるハイパーリンクを定義します。新規ウィンドウが開かれ、「clockfeatures」トピックを表示します。
```
 Whenever you see the <link clockfeatures JumpNewView>
 <graphic entity=StopWatchIcon><¥link> symbol, stop and answer the quiz questions.
```
出力は次のとおりです。
次のマークアップは、grep コマンドに関するマニュアル・ページを表示するリンクを作成します。
```
For more details, refer to the <link grep Man>grep man 
page<¥link>.
```
次のマークアップは、startDtterm という名前の実行別名を使用して実行リンクを作成します。別名とそれが実行するコマンドは、アプリケーションのデフォルトのリソース・ファイルで定義されます。
```
To open a terminal window, click <link hyperlink="DtHelpExecAlias 
startDtterm" Execute>Start Terminal Emulator.<¥link>
```
実行別名とその定義方法の詳細は、「実行別名」を参照してください。

<list>

形式

<list [bullet | order | plain] [loose | tight][continue]
[lalpha |ualpha | lroman | uroman | arabic] >

   * first item
   * second item
    .
    .
    .
<¥list>

bullet: デフォルトで、各項目の前に黒い丸の行頭文字を表示します。
order: 各項目の前に番号を表示します。番号は自動的に生成され、番号は 1 から始まります。デフォルトはアラビア数字です。順番が付けらるリストは、アルファベットやローマ数字を使用することもできます。
plain: 各項目の前に行頭文字、数字、文字を入れません。
continue: 項目の番号付けを引き続き前のリストから続けます。
loose: デフォルトで、項目間に縦の空間を作ります。
tight: 項目間に余分な縦の空間を作りません。
lalpha: 小文字のアルファベット
ualpha: 大文字のアルファベット
lroman: 小文字のローマ数字
uroman: 大文字のローマ数字
arabic: order リスト・タイプの場合のデフォルト

各項目は復帰改行され、アスタリスク (*) または <item> タグから始まります。アスタリスクは、<item> タグの簡易形式です。アスタリスクの両側にスペースとタブを入力できます。項目は複数行にわたって続く場合もあります。項目は複数のパラグラフから成ることもあり、その場合空白行によりパラグラフが区切られます。リストのネスト化が許可されているため、リストをリスト内に表示することもできます。

<¥list> 終了タグは必須です。

例

次は、マークアップの例です。

<list>
 * chocolate
 * raspberry
 * vanilla
 <¥list> 
 <list plain tight>
 * Word Processing
 * Graphics
 * Printing
 <¥list> 
 <list order lalpha>
 * Word Processing
 * Graphics
 * Printing
<¥list>

出力は次のとおりです。

<location>

位置

<location> 要素の位置を参照する際に ID を定義します。<location> 要素により、トピックの一部を <link> または <xref> の要素を使用してハイパーリンクの宛先として使用できます。

形式

<location id=id>text<¥location>

または

<location id=id|text|

id: 現在の位置の識別子で、ハイパーリンクの宛先として使用できます。
text: ID を割り当てたいテキストのブロックです。

<location> 要素は、組み込み ID か設計者定義 id パラメータを持っている要素(<hometopic> や <figure> など) がすでにある位置では必須ではありません。

<xref> 要素で作成された相互参照は、<xref> 要素を <location> の開始タグと終了タグの間のテキストに置き換えます。

例

次のマークアップ名は位置に名前を付け、その他の場所ではその位置へのハイパーリンクを作成します。

<s1 id=ConfigTopic> Configuration
 	...
 <location id=ConfigTopicBody>some text<¥location>
     ...
 <s1 id=UseTopic> Usage
     ...
 See <link ConfigTopicBody>Configuration<¥link>
 for additional information.

<location> 要素の ID へリンクすると、<location> タグが入力されているポイントへ、ヘルプ・ウィンドウが自動的にスクロールするという利点があります。対照的に、トピックの ID (この場合は「ConfigTopic」) へリンクすると、必ずトピックの先頭に行きます。

<location> 要素は、プレースホルダとして定義済みエンティティ (∅) を使用してファイル内の位置を参照することもできます。

ファイル内のキーの位置にこのマークアップを追加すると、その特定位置へのリンクを作成できます。

paragraph text
 .
 .
 .
 <location id=pointA>&empty;<¥location>
 .
 .
 .

<memo>

メモ

記述者のコメントや質問を識別しますが、最終的なヘルプ・ボリュームには表示されません。

形式

<memo>
 memo text<¥memo>

または

<memo|memo text|

helptag.opt ファイルに memo を指定すると、メモ・テキストはヘルプ・ボリュームのドラフトに出力されます。指定しなければ、特にヘルプ・ボリュームの最終版を作成したときは、メモ・テキストは出力されません。メモ・テキストは、表示のときは別のフォントで出力されます。メモ・テキスト内ではマークアップを使用しないでください。

例

次はメモの例です。

<memo>
 Patti: We need a drawing to illustrate this.
 <¥memo>

次のマークアップは、<memo> 要素の略式を使用しています。

<memo|Mike: Please explain how the following
 command is supposed to work|

<metainfo>

メタ情報

メタ情報セクションを開始しますが、ヘルプ・ボリュームにある情報に関する情報も入っています。メタ情報にはボリュームのタイトルと著作権に関する記述があります。

形式

<helpvolume>
   	<metainfo>
     		<title>volume title
				<copyright>      &copy; Copyright XYZ Company 1995...  
				<abstract>      brief description of help volume  
   		.
     	.
     	.
      <¥metainfo>
  <hometopic> ...
     .
     .
     .

メタ情報セクションはオプションですが、通常はヘルプ・ボリュームの中に記述されています。オプションではあっても、タイトル、著作権、および概要のサブセクションは、ヘルプ・ボリュームに関する有益な情報ですのでなるべく使用してください。

これらのサブセクションのどれかを入れる場合、メタ情報セクションは必須です。

<otherfront> 要素は、あらかじめ定義されているタイトル、著作権、および概要のサブセクション以外のサブセクションを定義するのに使用されます。

<¥metainfo> 終了タグは必須です。

例

<metainfo>
 <title>Inventory Tracking Software

 <copyright>
 &copy; Copyright 1995 XYZ Company.
 All rights reserved.

 <abstract>
 Explains how to use the Inventory Tracking Software

 <¥metainfo>

<newline>

復帰改行

段落や注釈内で復帰改行します。

形式

text<newline>text on next line

<newline> 要素に続くテキストが復帰改行してから始まります。

例

次のマークアップにより、パス名は必ず復帰改行してから始まります。

Put your files for the manual in the special directory
 <newline>/projects/userguide/draftdoc.

<note>

注

重要なポイントとなるテキストに注目させるような特殊形式を作成します。

形式

<note>
 text of note
 <¥note>

注のデフォルトのヘッダは、「Note」(日本語ロケールでは「注」) です。別のヘッダを指定するには、<head> 要素を使用してください。

注にアイコンを表示したい場合は、<!entity ...> 宣言で NoteElementDefaultIconFile を定義してください。

icon.pm という名前のデフォルトの注アイコンは、/usr/dt/dthelp/dthelptag/icons ディレクトリにあります。

<¥note> 終了タグは必須です。

例

次のマークアップはデフォルトのヘッダを使用しています。
```
<note>
 Warranty information is in your installation manual.
<¥note> 
```

次のマークアップは別のヘッダを指定しています。

   <note><head>Read This First
Warranty information is in your installation manual.
<¥note>

<otherfront>

他のメタ情報 (前付)

タイトル、著作権、および概要などの定義済みカテゴリのうちの一つで一致しないメタ情報 (前付) のために使用されます。<otherfront> 要素は非階層トピックを作成するためにも使用できます。非階層トピックはトピック・ツリーには表示されないので、トピックが表示されるようにするにはハイパーリンクを追加しなければなりません。<link> や<xref> の要素を使用して、<otherfront> 要素へのハイパーリンクを作成できます。

形式

<metainfo>
    .
    .
    .
<otherfront [id=id]><head>title of section
   text

ヘッダが必要な場合は、<head> 要素を使用してください。

<otherfront> は、<metainfo> の他のサブセクションすべての後に続きます。

<otherhead>

他のヘッダ

トピック内にサブヘッダを作成します。

形式

<otherhead>heading

ヘッダは、トピックのテキスト内のどこにでも入れることができます。<otherhead> 要素は、トピック・ツリーに表示されたヘルプ・トピックのリストには表示されません。

<¥otherhead> 終了タグは必須ではありません。

例

次の例は、<otherhead> 要素が <s1> トピック内の 2 つのサブセクションを識別する場合の例です。

<s1>Integration Tasks
There are two main tasks required to integrate your application.

 <otherhead> Editing Configuration Files
 Configuration files identify the colors, icons, and actions used by an application.
  <otherhead> Archiving Configuration Files
 .
 .
 .

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

新しい段落

インデントしたり、グラフィックを囲む段落を開始したりします。

形式

<p [indent] [gentity=graphic-ent [gposition=pos]
 [ghyperlink=gid [glinktype=type]]] [id=id] >text...

indent: オプションで、段落を現在の左マージンからスペース 6 つ分だけインデントするよう指定します。
gentity=graphic-ent: オプションで、段落がそのまわりを囲むグラフィックのエンティティ名です。gposition、ghyperlink、glinktype パラメータのいずれかを使用するときは、gentity パラメータと graphic-ent 値は必須です。
gposition=pos: オプションで、left または right は、オプションのグラフィックをそれぞれ左揃えまたは右揃えにします。
ghyperlink=gid: オプションで、グラフィックをハイパーリンクとして指定し、ハイパーリンクの宛先を指定します。glinktype パラメータを使用する場合、ghyperlink パラメータと gid 値は必須です。<link> 要素の hyperlink 属性と同じように使用します。(このパラグラフの位置を参照するときは、gid 値ではなく id 値を使用します。)
glinktype=type: オプションで、ハイパーリンクの種類を指定します。デフォルトは Jump です。他には、 JumpNewView、Definition、Man、Execute、 AppDefined があります。<link> 要素の type 属性と同じように使用します。
id=id: オプションで、この位置を相互参照するのに使用する ID 名を定義します。
text: グラフィックのまわりを囲む段落のテキストです。

段落をインデントしたり、段落でグラフィックのまわりを囲んだり、または追い込みヘッダ・スタイルの段落を使用したりする必要がある場合は  要素を使用してください。

オプションの <head> は  と共に使用できます。<xref> を使用して要素への相互参照を作成する場合は、<head> タグが必須です。<head> タグと <¥head> タグを使用してヘッダのテキストを区切ってください。

<¥p> 終了タグは必須ではありません。

例

次の例では 2 つの段落がありますが、2 番目の段落がインデントされます。
```
 Some people do not like to read instruction manuals.
This is not always a good idea.
```
出力は次のとおりです。

Some people do not like to read instruction manuals. This is not always a good idea.

次のマークアップは、追い込みヘッダで段落を作成します。

   <p><head>Examples and Illustrations <¥head>
Examples, perhaps the most common pattern of organization, are
appropriate whenever the reader might be tempted to ask <quote>
For example?<¥quote>

出力は次のとおりです。

<procedure>

プロシージャ

トピック内でセクションを開始します。

形式

<procedure>heading
procedure text...

プロシージャはトピックのテキスト内のどこにでも表示できます。トピック・ツリーに表示されるトピックのリストには含まれません。

終了タグは必須ではありません。

例

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

<procedure> Entering Special Characters
To enter Greek or mathematical characters in your document, use the Symbols font.

出力は次のとおりです。

<quote>

引用符

テキストの前後を引用符を使用して二重引用符でくくります。

形式

<quote>text<¥quote>

または

"text"

テキストを区切るには、開始と終了のタグ (<quote>...<¥quote>) か一組の二重引用符 ("...") を使用します。

例

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

... referred to in this manual as "the Standard" ...

出力は次のとおりです。

...referred to in this manual as "the Standard"...

<rsect>

参照セクション

参照セクション内のエントリを識別します。

形式

<rsect [id=id]>reference section heading
   .
   .
   .
<rsub>reference subsection heading

<rsect> 要素は、参照セクションを識別するために使用できます。一連の同じようなセクションにある参照文献を識別するのに便利です。たとえば、各参照セクションでは 1 つのソフトウェア・コマンドについて説明しておくことができます。

<rsect> は、次の部分から構成されています。

必須のヘッダ
オプションの導入部分のテキスト
オプションの参照サブセクション (<rsub>)

各 <rsect> セクションには、複数の <rsub> セクションがあります。各 <rsub> 要素にはヘッダが必要です。参照サブセクションへの相互参照は行えません。

トピック・ツリーには、<rsect> ヘッダは入りますが、<rsub> ヘッダは入りません。

(<rsect> や <rsub> の) 終了タグは必須ではありません。

例

次のマークアップは、この要素の使用方法を示しています。

<rsect>purge
    .
    .
    .
 <rsub>Syntax
 purge filename

 <rsub>Example
 purge file01
 <rsub>Related Commands
 delete

<s1>...<s9>

サブセクション (`<s1>`, `<s2>`, ... , `<s9>`)

階層内でトピックを開始します。

形式

<sn [id=name]>heading
topic text...

n は、レベル番号 (1、2、...、9 のいずれか) です。

<chapter> トピックは <s1> サブトピックを持つことができ、<s1> トピックは <s2> サブトピックを持つことができ、というように続いていきます。レベルはスキップできません。

セクションのヘッダは、<sn > タグと同じ行か次の行に置くことができます。したがって、ヘッダは必須です。セクション内のテキストはオプションです。

終了タグは通常省略されますが、いくつかの例では終了タグが必要です。たとえば、同じレベルにある <rsect> 要素がセクションの後に続く場合、セクションの終了タグは必須です。終了タグがないと、<rsect> 要素は直前のセクションのサブセクションと見なされます。

例

次の例では、トピック内に 3 つのレベルの階層があります。

<chapter>Running the Processor
 topic text...
 
 <s1>Getting Started
 To run the program, type in the usercode and your password.
 
 <s1>Customizing
 You may now set up this conversion program to change your computer from beige to red.
 
 <s2>Configuration
 Use either the disk drive or the tape drive to archive your files.
 
 <s3>Disk Drive Advantages
 See data sheet for specifications.
 
 <s3>Tape Drive Advantages
 See data sheet for specifications.
 
 <s2>Support
 If you really need help, call technical support.

次のマークアップでは、<rsect> セクションが階層内で同じレベルになるようにセクション終了タグ (<¥s1>) が使用されています。
```
<s1>first-level heading
text
<s1>first-level heading
text<¥s1>
<rsect>first-level heading
text
```
反対に、終了タグを使用しないと、<rsect> セクションは 2 番目の <s1> セクションのサブトピックになります。
```
<s1>first-level heading
text
<s1>first-level heading
text
<rsect>second- level heading
text
```

サブスクリプト

サブスクリプト文字を作成します。

形式

<sub>character to subscript<¥sub>

または

__text__

簡易形式では、サブスクリプトにする文字の前後に 2 つの _ _ (下線) 文字を使用します。

例

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

<p>The chemical element H<sub>2<¥sub>O contains
two hydrogen molecules.

出力は次のとおりです。

The chemical element H₂O contains two hydrogen molecules.

<super>

スーパースクリプト

スーパースクリプト文字を作成します。

形式

<super>character to superscript<¥super>

または

^^text^^

速記形式では、スーパースクリプトにする文字の前後に 2 つの ^^ (脱字記号) 文字を使用します。

例

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

<p>The answer to the problem is 2<super>8<¥super>.

出力は次のとおりです。

The answer to the problem is 2⁸.

<term>

用語集の用語

新たに紹介する用語を特殊フォントで記述し、用語集にある定義へのハイパーリンクを作成します。

形式

<term baseform [gloss | nogloss]>text<¥term>

または

<term baseform [gloss | nogloss]|text|

または

++text++

baseform: 用語の形式がテキストで使用されているものと同じでない場合に、用語集に表示される用語の形式。たとえば、テキストでは複数形式が使用されているのに、用語集では単数形式が使用されているような場合です。用語にスペースや特殊文字が入っている場合、引用符の中に baseform 文字列を入れてください。
gloss: デフォルトで、用語が用語集に入っていることを確認するようにヘルプタグに要求します。
nogloss: 用語集には用語を入れませんが、用語はボールド・フォントで表示されます。

簡易形式では、用語集の用語の前後に 2 つの ++ (プラス記号) を使用します。

注 -

ヘルプ・ボリュームに用語集が入っていない場合は、nogloss パラメータを使用してください。

nogloss パラメータが使用されず、用語集に対応する定義がない場合にヘルプタグがヘルプ・ボリュームを処理すると、警告メッセージが出力されます。

<term> 要素で用語にタグを付けると、用語集へのハイパーリンクが自動的に作成されます。用語集がない場合、リンクは動作しません。

正規マークアップが使用されている場合、<¥term> 終了タグは必須です。

例

次のマークアップは、その用語が用語集にある用語であることを示すため特殊フォント (破線の下線が付いたボールド・フォント) で「structural element」を記述し、用語集へのハイパーリンクを作成します。用語集のエントリにはスペースが入っているので、テキストには引用符が付けられます。テキスト内では複数形式で表示されます。ヘルプタグは単数形式で用語集内をチェックし、見つからない場合はエラーを出力します。

SGML views a document as a hierarchy
of <term "structural element"|structural elements|.

<title>

ヘルプ・ボリューム・タイトル

ヘルプ・ボリュームのタイトルを指定します。

形式

<metainfo>
<title>help volume title

<title> 要素は、<metainfo> (メタ情報) セクション内のオプションの要素です。しかし、タイトルにはヘルプ・ダイアログ・ボックスに表示されるボリューム名が表示されるので、この要素を使用するようにしてください。

<title> は、<metainfo> タグのすぐ後に続きます。ボリュームのタイトルは、タイトルをフォーマットできない可能性がある他のアプリケーション (インフォメーション・ビューアなど) によって表示される場合もあるので、タイトル内ではプレーン・テキストだけを使用するようにしてください。

<¥title> 終了タグは必須ではありません。

例

次の例は、サンプルのボリューム・タイトルです。

<metainfo>
<title>The Super Hyperlink User's Guide

<user>

ユーザの応答

コンピュータのプロンプトに対するユーザの応答を表示します。

形式

<user>response<¥user>

または

<user|response|

この要素は、コンピュータ・ダイアログでユーザ入力とコンピュータ出力とを区別するのに使用されます。通常は <ex> 要素内で使用されますが、この場合 <user> 開始タグと <¥user> 終了タグの間のスペースと改行は維持されます。

段落内で使用される場合、<user> テキストがソース・ファイル内で行の途中で切れないようにしなければなりません。

正規マークアップが使用されている場合、<user> 終了タグは必須です。

例

次のマークアップは、2 種類のフォントを生成します。1 つはコンピュータの表示内容を示し、もう 1 つはユーザの入力を示します。

<ex>
 Do you wish to continue? (Yes or No) <user>Yes<¥user>
 <¥ex>

出力は次のとおりです。

Do you wish to continue? (Yes or No) Yes

<var>

変数

コマンド内のユーザ指定変数を表示します。

形式

<var>
text
<¥var>

または

%%text%%

正規マークアップが使用されている場合、<¥var> 終了タグは必須です。

簡易形式では、テキストの前後に 2 つの %% (パーセント記号) を使用します。

例

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

INPUT <var>filename<¥var>

または

INPUT %%filename%%

出力は次のとおりです。

INPUT filename

<vex>

逐語例

その中ではヘルプタグ要素が要素として解釈されない逐語例を表示します。

形式

<vex [number | nonumber][smaller | smallest]> text<¥vex>

nonumber: デフォルトで、行番号を省略します。
number: 各行の先頭に行番号を付けます。
smaller または smallest: より小さいフォントを使用して例を表示します。長い行をより狭い幅の中に表示します。

逐語例の中では、ヘルプタグは認識されませんが、<¥ だけは終了タグと見なされます。

マークアップとして別に解釈される可能性のあるマークアップ・タグやその他の文字を表示する必要がある場合はこの要素を使用します。改行やスペースは、ソース・ファイル内で表示されたのと同じ状態のままです。

smaller フォントと smallest フォントを使用すると、幅の広い例をマージン内に収めることができます。

例

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

<vex>
<!ELEMENT copyright    - O (text)
          -memo | location | idx) >
<¥vex>

出力は次のとおりです。

<warning>

警告

ユーザにとって危険性の高い状況に対して注意するようにユーザに警告します。

形式

<warning>
text
<¥warning>

警告メッセージのテキストはボールドで出力されます。

警告のデフォルトのヘッダは、「Warning」(日本語ロケールでは「警告」) です。別のヘッダを指定するには、<head> 要素を使用してください。

警告と共にグラフィックを表示するには、<!entity> 宣言で WarningElementDefaultIconFile を定義してください。warnicon.pm という名前のデフォルトの警告アイコンは、/usr/dt/dthelp/dthelptag/icons ディレクトリにあります。

<¥warning> 終了タグは必須です。

例

次のマークアップは、警告メッセージを作成します。

   <warning>
Failure to follow these guidelines could result
in serious consequences.
<¥warning>

次のマークアップは、警告メッセージの別のヘッダを指定します。
```
 <warning><head>Danger!
Do not open the high-voltage compartment.
<¥warning> 
```

<xref>

相互参照

ヘルプ・ボリューム内で別の位置を指定し、その位置へのハイパーリンクを作成するテキストを挿入します。

形式

<xref id>

id は相互参照されているトピックまたは位置の識別子です。

相互参照は、章またはセクションのタイトル、ヘッダ、図のタイトル、リスト項目、または行番号に変換されます。相互参照テキストは、ハイパーリンクになり、ユーザが選択すると相互参照された位置へジャンプします。

相互参照を作成するには、参照予定の要素に id を定義しなければなりません。宛先要素の id を <xref> タグにある id パラメータとして使用します。これにより、<xref> 要素から宛先要素へのハイパーリンクが作成されます。id はそのまま正確にスペルアウトされなければなりません。しかし、大文字と小文字の区別はありません。

id パラメータは、次の要素につけることができます。

<chapter>
<s1>, <s2>,...<s9>
 <otherfront>
 <p>
 <image>
 <item>
 <figure>
 <location>
 <rsect>

下線が入っている id (「_abstract」や「_hometopic」など) への相互参照はできません。<link> 要素を使用してください。

例

ユーザが詳細な章を参照できるようにするには、章の id を使用して参照を作成してください。たとえば、id が windowmgr である「Window Management」というタイトルの章を参照するには、「Refer to <xref windowmgr> for details.」と記述します。

オンライン・ヘルプ・ボリュームでは、結果は「Refer to Window Management for details.」となります。id は章のタイトル「Window Management」に置き換えられ、ハイパーリンクになります。

次のマークアップは「analyzer」という名前の id をセクションの要素に代入します。

<s1 id=analyzer>Logic Analyzers

次の例は、このトピックへの相互参照が記述されているマークアップです。

The DX16500A logic analysis system, described in
 <xref analyzer>, can be configured to a user's needs.

処理後、 <xref> 要素は次のように「Logic Analyzers」に置き換えられます。

テキスト「Logic Analyzers」はハイパーリンクで、ユーザが選択すると相互参照ヘルプ・トピックへジャンプします。

第 6 章特殊文字エンティティの概要

この章では、ヘルプ・トピックの記述に使用する特殊文字のリストを示します。

特殊文字

この特殊文字は、関連するエンティティ名を、特殊文字を表示する場所へ指定することにより、テキストに入力できます。

記述に * (アスタリスク) のマークが付いているエンティティを使用するには、helpchar.ent ファイルを使用してください (詳細は、「特殊文字の表示」を参照してください)。

表 6-1 印刷上の記号


記号	エンティティ名	説明
(c)	`©`	著作権記号
(R)	`®`	登録商標
(TM)	`&tm;`	商標
-	`&endash;`	エヌ・ダッシュ (短いダッシュ)
-	`&emdash;`	エム・ダッシュ (長いダッシュ)
o	`&bullet;`	* 行頭文字
	`&cr;`	復帰改行
`...`	`&ellipsis;`	省略記号 (水平型)
`....`	`&pellipsis;`	省略記号 (文の終わり)
	`&vellipsis;`	垂直型省略記号
`'`	`&squote;`	一重引用符
`"`	`&dquote;`	二重引用符
	`&vblank;`	垂直空白
`( )`	`∅`	空 (テキストなし)
( )	`&sigspace;`	有意のスペース
-	`&sigdash;`	行の切れ目ではないハイフン
`則`	`&S;`	* セクション
`其`	`&P;`	* 段落

表 6-2 ギリシャ文字


記号	エンティティ名	説明
小文字
N/A	`α`	* アルファ
N/A	`β`	* ベータ
N/A	`χ`	* カイ
N/A	`δ`	* デルタ
N/A	`ϵ`	* エプシロン
N/A	`φ`	* ファイ
N/A	`ϕ`	* オープン・ファイ
N/A	`γ`	* ガンマ
N/A	`η`	* イータ
N/A	`ι`	* イオタ
N/A	`κ`	* カッパ
N/A	`λ`	* ラムダ
N/A	`μ`	* ミュー
N/A	`ν`	* ニュー
N/A	`π`	* パイ
N/A	`ϖ`	* パイの代替文字 (またはオメガ)
N/A	`θ`	* シータ
N/A	`ϑ`	* オープン・シータ
N/A	`ρ`	* ロー
N/A	`N/A`	* シグマ
N/A	`&tsigma;`	* シグマ 1
N/A	`τ`	* タウ
N/A	`υ`	* イプシロン
N/A	`ω`	* オメガ
N/A	`ξ`	* クシー
N/A	`ψ`	* プシー
N/A	`ζ`	* ゼータ
大文字
N/A	`&Udelta;`	* デルタ
N/A	`&Uphi;`	* ファイ
N/A	`&Ugamma;`	* ガンマ
N/A	`&Ulambda;`	* ラムダ
N/A	`&Upi;`	* パイ
N/A	`&Utheta;`	* シータ
N/A	`&Usigma;`	* シグマ
N/A	`&Uupsilon;`	* イプシロン
N/A	`&Uomega;`	* オメガ
N/A	`&Uxi;`	* クシー
N/A	`&Upsi;`	* プシー

表 6-3 数学記号


記号	エンティティ名	説明
基本数学記号
-	`−`	減算
+-	`&pm;`	プラス・マイナス
/	`&div;`	除算
*	`×`	乗算
<=	`&leq;`	以下
>=	`&geq;`	以上
!=	`&neq;`	不等号
拡張数学記号
²	`&squared;`	* 二乗
³	`&cubed;`	* 三乗
1/4	`&one-fourth;`	* 四分の一
1/2	`&one-half;`	* 二分の一
3/4	`&three-fourths;`	* 四分の三
[infin ]	`&infty;`	* 無限大
N/A	`&equiv;`	* 恒等的に等しい
!=	`&not-eq;`	* 不等号
[ap ]	`≈`	* 近似
耽	`&neg;`	* 否定
束	`∩`	* キャップ (共通部分)
損	`∪`	* カップ (和集合)
v	`&vee;`	* ヴィー (論理和)
^	`&wedge;`	* ウェッジ (論理積)
N/A	`&in;`	* 属する
N/A	`&subset;`	* 真部分集合
N/A	`&subseteq;`	* 部分集合
N/A	`&supset;`	* 真超集合
N/A	`&supseteq;`	* 超集
[forall]	`∀`	* 全称記号
[exist ]	`&exists;`	* 存在記号
N/A	`&not-in;`	非要素
N/A	`&function;`	* 関数記号 (フロリン記号)
N/A	`&angle;`	* 角度
	`&cong;`	* 合同
N/A	`&propto;`	* 比例
N/A	`&perp;`	* 垂直
揃	`&cdot;`	* 中心点
N/A	`&oplus;`	* 直和
N/A	`&otimes;`	* 直積
淡	`ø`	* 空集合
N/A	`&partial;`	* 微分デルタ
N/A	`∑`	* 総和 (ギリシャ文字の大文字のシグマ)
*	`∏`	* 積 (ギリシャ文字の大文字のパイ)

表 6-4 矢印記号


記号	エンティティ名	説明
<-	`&leftarrow;`	* 左矢印
N/A	`&rightarrow;`	* 右矢印
N/A	`&uparrow;`	* 上矢印
N/A	`&downarrow;`	* 下矢印
N/A	`&leftrightarrow;`	* 両方向矢印
<=	`&bigleftarrow;`	* 左大矢印
=>	`&bigrightarrow;`	* 右大矢印
N/A	`&biguparrow;`	* 上大矢印
N/A	`&bigdownarrow;`	* 下大矢印
N/A	`&bigleftrightarrow;`	* 両大矢印

表 6-5 その他の記号


記号	エンティティ名	説明
現在の日付と時間
`//`	`&date;`	今日の日付 (ヘルプタグ実行時)
`09:50`	`&time;`	現在の時間 (ヘルプタグ実行時)
通貨記号
蔵	`&cents;`	セント
贈	`&sterling;`	ポンド
促	`¥`	円
単位
o	`°`	度
N/A	`&minutes;`	分、プライム、フィート
"	`&seconds;`	秒、ダブル・プライム、インチ
`AM`	`&a.m.;`	午前
`PM`	`&p.m.;`	午後
トランプ組札
[loz ]	`&diamondsuit;`	* ダイヤ
N/A	`&heartsuit;`	* ハート
N/A	`&spadesuit;`	* スペード
N/A	`&clubsuit;`	* クローバー
その他の記号
[loz ]	`&diamond;`	* ダイヤ
多	`&invert-question;`	逆クエスチョン・マーク
臓	`&invert exclamation;`	逆エクスクラメーション・マーク
造	`&currency;`	通貨
N/A	`&therefore;`	ゆえに
束	`&openanglequote;`	左三角引用符
損	`&closeanglequote;`	右三角引用符
N/A	`&aleph;`	* ヘブライ語のアレフ
[nabla ]	`∇`	* ナブラ (ギリシャ文字の逆大文字デルタ)
N/A	`&surd;`	平方根、正方向列
N/A	`&wp;`	* ワイエルシュトラス記号
N/A	`&Re;`	* ドイツ文字の R
N/A	`&im;`	* ドイツ文字の I

第 7 章コマンドの要約

この章では、ヘルプ・コマンドが端末ウィンドウで手動で実行されるときに使用可能なコマンド行オプションを要約します。

ヘルプ・システム・コマンド

ヘルプ・システムが提供するデスクトップのアクションとデータ型により、ヘルプ・ファイルのアイコンをクリックするかメニュー項目を選択すると、実行時のヘルプ・ファイルをコンパイルしたり表示したりできます。しかし、特定のコマンド・オプションを選択する場合、端末エミュレータでコマンドを入力するか、新しいアクションを作成しなければなりません。

ヘルプのアクションとデータ型は、/usr/dt/appconfig/types/lang ディレクトリにある 2 つのファイル dthelp.dt と dthelptag.dt に定義されています。

ここで要約されているコマンドは、次のとおりです。

dthelptag: ヘルプタグのソース・ファイルを実行ファイルにコンパイルします。
dthelpview: ヘルプ・ボリューム、ヘルプ・トピック、テキスト・ファイルまたはマニュアル・ページを表示します。
dthelpgen: 各ファミリ・ファイルのエントリが入っている新しいヘルプ・ボリューム browser.hv にヘルプ・ファミリ・ファイルを格納します。

ヘルプタグ・ファイルの処理 (dthelptag)

ヘルプタグ・ソフトウェアは dthelptag コマンドで起動され、ヘルプタグのソース・ファイルを実行時のヘルプ・ファイルにコンパイルします。volume.htg ファイルがあるディレクトリで dthelptag を実行してください。

コマンド形式

dthelptag  [command-options]  volume  [parser-options]

command-options は、volume 名の前に入力されるオプションで、parser-options は volume 名の後に入力されるオプションです。

コマンド・オプション

-clean: 指定の volume のためにヘルプタグを以前に実行したときに作成されたすべてのファイルを削除します。
-shortnames: 作成されたすべてのファイル名を、ベース名は 8 文字まで、拡張子は 3 文字までにそれぞれ制限します。これにより、実行時のヘルプ・ファイルを長い名前がサポートされていないシステムに移植できます。
-verbose: dthelptag コマンドの経過状況を表示し、発生したパーサ・エラーをすべて表示します。パーサ・エラーは volume.err という名前のファイルに保存されます。
-formal: 正規パーサを使用して、SGML 準拠マークアップでタグが付けられたヘルプ・ファイルを解釈します。このオプションを指定しない場合、dthelptag は入力ファイルに簡易マークアップが記述されているものと判断します。

2 種類のマークアップ (簡易マークアップと正規マークアップ) があるため、ファイル拡張子を使用してその種類を識別するようにしてください。簡易マークアップには .htg を、正規マークアップには .ctg を使用してください。

パーサ・オプション

パーサ・オプションは volume 名の後に入力され、parser に直接渡されます。この parser は、マークアップ・ファイルを実行時のファイルに変換するヘルプタグ・ソフトウェアの一部です。

これらのオプションは次の方法で使用できます。

volume 名の後にコマンド行で入力する
現在のディレクトリにある helptag.opt という名前のファイルにリストする
現在のディレクトリにある volume.opt という名前のファイルにリストする
DTTAGOPT 環境変数を使用して設定する

コマンド行に入力されたオプションは、別の方法を使用して設定されたオプションを無効にします。

onerror

パーサ・エラーが発生した場合に、dthelptag コマンドを続行すべきかどうかを指定します。デフォルトは onerror=stop で、これによりパーサ・エラーが 1 つでも発生するとコマンドは停止します。onerror=go を指定すると、処理は続行されますが、作成された実行時のヘルプ・ファイルが正しく動作しない可能性があります。

charset

テキストファイルを記述するのに使用された文字セットを指定します。ヘルプ・トピックが適切なフォントで表示されるようにするには文字セット名が正しくなければなりません。デフォルトは charset=ISO-8859-1 です。

LanguageElementDefaultCharset という名前のエンティティを宣言してヘルプ・ボリューム内の文字セットを指定することもできます。

/usr/dt/dthelp/dthelptag/helplang.ent ファイルには、このエンティティの宣言が記述されています。サポートされている文字セットのリストについては、第 14 章「母国語のサポート」を参照してください。

search

参照されたファイル・エンティティを探すために検索されるディレクトリのリストに別のディレクトリを追加します。複数のディレクトリを指定するには、複数の search=directory オプションを使用してください。検索オプションが使用されていない場合は、現在のディレクトリだけが検索されます。

clearsearch

検索ディレクトリのリストを無視します。このオプションは、helptag.opt ファイルに指定された検索オプションを無効にする場合にコマンド行で有効です。

memo

設計者のメモ (<memo> 要素を使用して入力される) を取り込みます。デフォルトは nomemo で、これはヘルプタグがメモを無視するようにします。

nomemo

ヘルプタグが設計者のメモ (<memo> 要素で入力される) を無視するようにします。これがデフォルトです。

ヘルプ・トピックの表示 (dthelpview)

dthelpview コマンドは、ヘルプ・ボリューム、個々のヘルプ・トピック、テキスト・ファイル、またはマニュアル・ページを表示するために使用できます。

コマンド形式

ヘルプ・ビューアを起動するには、次のいくつかの方法があります。

dthelpview -helpVolume volume [ -locationId id ]
dthelpview -man
dthelpview -manPage man
dthelpview -file filename

-helpVolume volume

表示したい volume.sdl ファイル名を指定します。ボリュームが現在のディレクトリになく、ボリュームが登録されていない場合はパス名が必要です。

-locationId id

ID を指定します。dthelpview は、id が入っているトピックを表示します。ID を指定しない場合、ヘルプ・ビューアはデフォルトとして _hometopic を使用します。

-man

表示するマニュアル・ページを要求するダイアログを表示してから、要求されたマニュアル・ページを表示します。

-manPage man

特定のマニュアル・ページが表示されるように指定します。

-file filename

特定のテキスト・ファイルが表示されるように指定します。

デフォルトの volume と id は dthelpview の app-defaults ファイルである /usr/dt/app-defaults/lang/Dthelpview に設定できます。lang にはロケール名が入ります。

ブラウザ・ヘルプ・ボリュームの作成 (dthelpgen)

dthelpgen ユーティリティは、フロントパネルの [ヘルプ・ビューア] を使用してシステムに登録されたヘルプ・ボリュームを表示できるようにする特殊なヘルプ・ボリュームを作成します。フロントパネルの [ヘルプ・ビューア] コントロールを最初にクリックすると、dthelpgen は自動的に実行されます。ヘルプ検索パス・ディレクトリ (ローカルな、またはネットワーク化されたディレクトリ) を検索してヘルプ・ファミリ・ファイルを位置付け、次にユーザの HomeDirectory/.dt/help/$DTUSERSESSION ディレクトリにブラウザ・ボリューム (browser.hv) を作成します。いったん作成されると、ボリュームは次のアクションのどれかに応じて更新されます。

ファミリ・ファイルまたはヘルプ・ボリュームを追加、削除、または変更する
LANG 環境変数を変更する
ReloadApps アクションを起動する
dthelpgen を端末エミュレータで手動で実行する

ブラウザ・ボリュームは、フロントパネルの [ヘルプ・ビューア] コントロールをクリックすると表示されます。または、dthelpview を手動で実行し、次のコマンド行で示されているようにブラウザ・ボリューム名を指定できます。
```
dthelpview -h browser.hv
```

コマンド形式

dthelpgen -dir [options]

-dir: ブラウザ・ボリュームと中間ファイルを格納するディレクトリを指定します。これは、必須のパラメータです。

オプション

-generate: システム上のファミリ・ファイルとヘルプ・ボリュームが変更されていない場合でも、新しいブラウザ・ヘルプ・ボリュームが作成されるように指定します。
-file basename: dthelpgen が作成したヘルプ・ボリュームと中間ファイルの名前を指定します。デフォルトは、browser.hv です。
-lang: どの言語ディレクトリのヘルプ・ファミリとヘルプ・ボリュームを検索するかを指定します。-lang オプションを設定すると、LANG 環境変数の現在値よりも優先されます。

注 -

ブラウザ・ボリュームがヘルプ・ウィンドウに表示されている間に dthelpgen を実行する場合、ウィンドウを閉じてからブラウザ・ボリュームをもう一度開いてください。

第 8 章ヘルプタグ文書型定義の読み方

この章では、ヘルプタグ 1.3 文書型定義 (DTD) の読み方と、完全に準拠した Standard Generalized Markup Language (SGML) ヘルプ・ファイルを作成するための DTD の使用方法を説明します。

文書型定義

文書型定義 (DTD) は、構造化された (または階層のある) ドキュメントを作成するために要素のセットを定義します。DTD は各要素の形式を指定し、ドキュメント内での要素の使用方法を決定します。

ヘルプタグ 1.3 DTD

ヘルプタグ 1.3 DTD タグ・セットとその関連規則は、正規マークアップとして参照されます。DTD は Standard Generalized Markup Language (SGML) ISO 指定 8879: 1986 に準拠しています。つまり、SGML 準拠のヘルプ・ファイルを作成するのに正規マークアップを使用できます。

付録 A には完全な DTD 仕様が載っています。DTD は開発者用ツールキットでも使用できます。DTD は /usr/dt/dthelp/dthelptag/dtd ディレクトリにあり、名前は helptag.dtd です。

DTD コンポーネント

DTD は、これまでの章で説明したヘルプタグの各要素を定義します。この節では、いくつかの重要な用語を紹介し、要素記述の構文の読み方を説明します。DTD の各セクションを完全に説明するものではありません。

要素宣言

DTD は各要素を要素宣言で定義します。宣言には、要素を説明する詳細な記述、それに必要なコンポーネント、指定できる要素またはできない要素を使用します。要素には属性宣言で定義された特性もあります。特性の詳細は、「属性リスト宣言」のセクションで説明します。

要素宣言の形式は次のとおりです。

<ELEMENT element_type minimization (content model) >

element_type: 要素名を指定します。これはタグ名としても使用されます。たとえば、要素型 head のタグは <head> です。
minimization: 開始タグまたは終了タグが必要かどうかを示す 2 文字のエントリです。1 番目の文字は開始タグを表します。2 番目の文字は終了タグを表します。その 2 文字の間に 1 つ空白が入ります。文字 o はそのタグがオプションであることを意味します。- (マイナス記号) はタグが必要であることを意味します。たとえば、- - というエントリは、その要素には開始タグと終了タグの両方が必要であるという意味です。ヘルプタグ 1.3 用 DTD ではすべての要素に開始タグと終了タグが必要です。
content model: 要素型に含められる必要な要素およびオプションの要素のリストを指定します。要素のシーケンスと、適用可能であれば、要素を指定できる回数を定義します。

コンテント・モデルは次の記述を使用します。

|: 「or」という意味です。
+: 要素を最低 1 回は指定しなければなりません。繰り返し可能です。
*: 要素を 0 回以上指定しなければなりません。
?: 要素を 0 回または 1 回指定しなければなりません。
,: カンマはシーケンスを説明します。つまり、要素型の後には、カンマの後に指定された要素が続かなければなりません。
+ (element_ type(s)): + (プラス記号) は、リストされた 1 つまたは複数の要素が、この要素内か、それを含む要素どの中でも使用できることを示します。これを取り込みと呼びます。 1 つ以上の要素を囲むのに括弧を使用します。
- (element_ type(s)): - (マイナス記号) は、リストされた 1 つまたは複数の要素が、この要素内か、それを含む要素のいずれかの中では使用できないことを示します。これを排他と呼びます。 1 つ以上の要素を囲むには括弧を使用します。

例

各例には、提供されている要素宣言に対する語の説明があります。必要な開始タグと終了タグが使用されます。

章は、テキストが後に続く <chaphead> を必要とします。1 つの章には 0 個以上の s1 要素と、それに続く 0 個以上の rsect 要素を指定できます。
```
<!ELEMENT chapter - - (chaphead, text, (s1*, rsect*)) >
```
chaphead は、オプションの abbrev が後に続くヘッダを必要とします。chaphead には memo、location、idx の要素は指定できません。
```
<!ELEMENT chaphead - - (head, abbrev?)
 -(memo | location | idx) >
```
段落要素は、開始タグ (-) と終了タグ (-) を必要とします。段落要素には、partext 要素が後に続くオプションのヘッダ (?) を指定できます。newline 要素は、段落要素に含まれる p 要素かその他の要素の中で使用できます。
```
<!ELEMENT p - - (head?, partext) +(newline) >
```
note にはテキストが含まれます。オプションのヘッダを指定できます。note には、note、caution、warning の要素は指定できません。
```
<!ELEMENT note - - (head?, text)
 -(note | caution | warning) >
```
list にはオプションのヘッダを指定できます。list には 1 つ以上の項目 (繰り返し可能) が必要です。
```
<!ELEMENT list - - (head?, item+) >
```
book 要素宣言は、別の book 要素を含むことができないように指定するため排他処理を使用します。
```
<!ELEMENT book - - (partext) -(book) >
```

要素宣言のキーワード

要素の中には、要素宣言の中に、要素のデータ内容を説明するキーワードを含むものがあります。DTD には、EMPTY、CDATA、#PCDATA の 3 つのキーワードがあります。

EMPTY: 要素が、オンライン情報で表示されるデータ内容を持たないことを指定します。newline 要素と xref 要素がこの例です。
CDATA: 「文字データ」を表します。つまり、その要素のデータ内容はマークアップとして認識されません。
#PCDATA: 「構文解析された文字データ」を表します。つまり、そのデータ内容にはヘルプ・システムのパーサが解釈するテキストとマークアップ文字の両方が含まれます。

属性リスト宣言

属性リストは、要素をより詳しく説明する追加の属性を宣言します。属性リスト宣言の形式は次のとおりです。

<!ATTLIST element_type attribute_values default_value>

たとえば list 要素には、type、ordertype、spacing、continue の 4 つの属性があります。それぞれの型の値が宣言されます。最後のカラムはデフォルト値を示しています。continue 属性には値が 1 つしか存在しないので、デフォルト値は省きます。

<!ATTLIST list type      ( order 
                           bullet
                            plain
                            check )       bullet
               ordertype ( ualpha
                            lalpha
                            arabic
                            uroman
                            lroman )      arabic
                spacing   ( tight
                             loose )      tight
                continue  (continue)    #IMPLIED >

上記のマークアップは、リスト項目の間に空白行が入り、番号 (大文字のアルファベット) の付いたリストを作成します。

<list order ualpha loose>
   <item>
      <text>
        <p>
          <partext>Introducing the Front Panel></partext>
        </p>
      </text>
     </item>

正規マークアップ

正規マークアップの作成には、構造化エディタを使用するのが最良の方法です。基本的な要素のセットを覚えれば、設計者は作業を始められます。作業の開始は、メニューから要素を選択することです。それに応じて、構造化エディタが各要素に必要なすべてのタグを生成します。さらにアプリケーションが、作成中の構造フレームワークが文書型定義に準拠するかを確認します。

簡易マークアップ、正規マークアップ、構造化エディタについては、「ヘルプタグによるヘルプ・トピックの記述」を参照してください。

正規マークアップの注意点

簡易マークアップと正規マークアップは共通の要素のセット (章、セクション、ヘッダ、リスト、段落など) を共用しています。しかし、正規マークアップは次のような重要な点で簡易マークアップとは異なります。

どの要素にも開始タグと終了タグが必要です。
要素の各サブコンポーネントのタグを入力しなければなりません。
正規マークアップでは / (スラッシュ) が終了タグ区切り文字です。終了タグは </tagname> の形式です。

エンティティ宣言には、簡易宣言で使用する FILE パラメータの代わりに、SYSTEM パラメータを使用します。

明示的な開始タグおよび終了タグ

各要素、そのコンポーネント部分、各要素内の要素は明示的にタグ付けされなければなりません。たとえば、次の例は章のヘッダの正規マークアップです。この例やその他のマークアップ例では、読みやすいようにタグをインデントしてあります。実際のマークアップではインデントは必要ありません。

<chaphead>
      <head>
              <partext>Front Panel Help</partext>
       </head>
 </chaphead>

追加のタグ <head> と <partext> に注意してください。これらは <chaphead> 要素のサブコンポーネントです。これらの要素の 1 つ 1 つに対して、明示的な開始タグおよび終了タグが必要です。

要素の明確な階層

各要素宣言は、要素をどこでどのように使用するかを管理する規則のセットの元になります。要素の中には別の要素が指定でき、その中にまた別の要素を指定できるので、ドキュメントは要素の階層になります。トップレベルでは <helpvolume> がその他のすべての要素のコンテナになっています。

ヘルプ・トピックを作成するのにどのマークアップが必要かを判別するために、規則に慣れる必要があります。たとえば、章を作成したいとします。まず、次にリストされている chapter の宣言を見てください。chaphead が必要であると指定されています。次に、chaphead の規則を見てください。今度は head が必要であると指定されています。したがって、head の宣言を見てください。そしてネストにされた最後の要素 (この場合は partext) まで見てください。一般的に使用する要素に慣れるまで、マークアップを正しく入力するにはこの方法が役立ちます。

<!ELEMENT chapter - - (chaphead, text?, (s1*, rsect*)) >
<!ELEMENT chaphead - - (head, abbrev?)
                        -(memo | location | idx | footnote) >
<!ELEMENT head - - (partext)
                    -(memo | location | idx)>
<!ELEMENT partext - - ((#PCDATA . . . ))>

構造化エディタを使用すると、設計者に必要な DTD の知識を最小限にできます。エディタ・アプリケーションは DTD を「読み」、各要素に必要なタグを作成します。作成されるタグの多くは中間構造タグです。

例

次の正規マークアップ例は、デスクトップのテキスト・エディタのヘルプ・ボリュームからの抜粋です。関連するオンライン情報を表示するには、[フロントパネル] で [ヘルプ・ビューア] を選択します。[デスクトップの紹介] を選択し、リストされたボリュームの中から [テキスト・エディタのヘルプ] を選択します。テキスト・エディタ・ボリュームで [テキスト・エディタの使い方] を選択し、次に [既存のドキュメントを開くには] を選択します。

テキストと、対応するタグが読みやすいように、この例ではインデントを使用しています。

<s2 id="TOOPENANEXISTINGDOCUMENT">
<chaphead><head>
<partext>To Open an Existing Document</partext>
     </head></chaphead>
<text>
<p>
<partext>You can use Text Editor or File Manager to open an existing 
document.
 </partext></p>
<idx><indexprimary>
<partext>document</partext></indexprimary>
     <indexsub>
<partext>opening</partext></indexsub></idx>
<idx><indexprimary>
<partext>opening</partext></indexprimary>
     <indexsub>
<partext>existing document</partext></indexsub></idx>
<procedure>
<chaphead><head>
<partext>From Text Editor</partext>
     </head></chaphead>
<text>
<list type="ORDER">
<item><text><p>
<partext>Choose Open from the File menu.</partext></p>
<p>
<partext>The Open a File dialog box lists files and folders on your 
system.You can browse the documents listed, or change to a new folder 
to locate other files on your system.</partext>
     </p></text></item>
<item><text><p>
<partext>Select the document you want to open in the Files list or 
type the file name in the Open a File field.</partext></p>
<p>
<partext><emph><partext>Or,</partext></emph> if the document is not 
in the current folder, first change to the folder that contains your 
document. Then choose a name in the Folders list or type the path 
name of the folder you wish to change to in the Enter path or folder 
name field.</partext></p></text></item>
<item><text><p>
<partext>Press Return or click OK.
 </partext></p></text></item></list>
<figure tonumber="NONUMBER" entity="TEXTEDITOROPENFILE">
</figure></text></procedure>

<procedure><chaphead><head>
<partext>From File Manager</partext>
     </head></chaphead>
<idx><indexprimary>
<partext>opening</partext></indexprimary>
     <indexsub>
<partext>document from File Manager</partext></indexsub></idx>
<idx><indexprimary>
<partext>document</partext></indexprimary>
     <indexsub>
<partext>opening from File Manager</partext></indexsub></idx>
<idx><indexprimary>
<partext>File Manager</partext></indexprimary>
     <indexsub>
<partext>opening document</partext></indexsub></idx>
<text>
<list type="BULLET">
<item><text><p>
<partext>Display the document's file icon in a File Manager 
window.</partext>
     </p></text></item>
<item><text><p>
<partext>Do <emph><partext>one</partext></emph> of the 
following:</partext></p>
<list type="BULLET">
<item><text><p>
<partext>Double-click the document's file icon.</partext>
     </p></text></item>
<item><text><p>
<partext>Select the document, then choose Open from the Selected 
menu.</partext>
     </p></text></item>
<item><text><p>
<partext>Drag the document to Text Editor's control in the Front 
Panel.</partext>
     </p></text></item></list></text>
     </item></list><text> </procedure>
<procedure><chaphead><head>
<partext>See Also</partext>
     </head></chaphead>
<text>
<list type="BULLET" spacing="TIGHT">
<item><text><p>
<partext><xref id="ENTERINGANDEDITINGTEXT"></partext>
     </p></text></item>
<item><text><p>
<partext><xref id="TOSAVEADOCUMENTTOTHECURRENTFILE"></partext>
     </p></text></item>
<item><text><p>
<partext><xref id="TABLEOFCONTENTS"></partext>
     </p></text></item></list></text>
     </procedure></text></s2>

ファイル・エンティティ宣言

正規マークアップでファイル・エンティティを宣言するには、次の形式を使用します。

<!entity entityname SYSTEM "filename">

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

注 -

以前に簡易マークアップで作成されたエンティティ宣言を使用する場合は、FILE パラメータを SYSTEM に置き換えなければなりません。

例

次の例は、3 つのテキストから成りグラフィック・イメージを 1 つ含むヘルプ・ボリュームのエンティティ宣言です。

<!entity MetaInformation SYSTEM "metainfo>"
<!entity BasicTasks SYSTEM "basics">
 <!entity AdvancedFeatures SYSTEM "advanced">
 <!entity process_diagram SYSTEM "process.tif">

エンティティは、簡易マークアップの場合とまったく同様に正規マークアップでも参照されます。

正規マークアップの処理

dthelptag を使用して正規マークアップを処理する場合、コマンド行オプションの -formal を使用しなければなりません。たとえば、Icons.ctg という名前の正規マークアップ・ファイルを詳細モードで処理するには、次のコマンドを入力します。

dthelptag -verbose -formal Icons.ctg

注 -

コマンド・オプションは、入力ファイルのマークアップの型を指定します。dthelptag を実行することによって作成される実行時のファイルは常に volume.sdl です。オンラインでは、簡易マークアップと正規マークアップのどちらを使用しても同じです。

パート II 設計者が行う作業

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

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

ホーム・トピック

トピックとサブトピック

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

エンティティ

メタ情報

用語集

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

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

簡易マークアップ

正規マークアップ

ヘルプタグ記号の表示

ヘルプ・ボリュームの例

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

volume.htg ファイルの作成

複数のソース・ファイル

例

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

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

関連項目

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

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

ビルド・ディレクトリの作成

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

helptag.opt ファイルの作成

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

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

関連項目

トピック階層の作成

例

関連項目

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

例

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

例

メタ情報トピックの作成

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

例

関連項目

非階層トピックの追加

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

例

関連項目

トピックへのアクセス

ID 名に関する規則

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

組み込み ID

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

例

エンティティの使い方

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

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

例

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

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

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

関連項目

第 3 章 ヘルプ・トピックの記述

ヘルプ・トピックの作成

例

関連項目

トピック内に構造を作成する

パラグラフを開始するには

例

リストを作成するには

例

ラベル付きリストを作成するには

例

ラベル付きリストにヘッダを付けるには

例

関連項目

トピックにサブヘッダを付けるには

例

コンピュータ・リストを表示するには

例

関連項目

注、注意、警告を追加するには

例

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

第 3 章ヘルプ・トピックの記述