第 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

関連項目

• 第 2 章「ヘルプ・ボリュームの構成および記述」では、トピック階層の作成方法を含めたヘルプ・ボリュームの一般的な構造を説明しています。

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

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

• 段落は、テキストの本文に使用します。

• リストは、箇条書きにして示す情報に使用します。リストの種類には、行頭文字が付いたもの、順番を付けたもの (番号の付いたもの)、何も付かないものがあります。

• サブヘッダは、トピック内を部分に分けるのに使用します。

• グラフィックは、インライン・グラフィックとしてテキスト内に入れたり、独立した図として段落の間に表示できます。

• ハイパーリンクで、関連トピックを参照できます。ハイパーリンクは、その階層内のより深層のサブトピックに続いたり、まったく異なる部分のトピックに分岐したり、他のヘルプ・ボリュームに続いたりします。

• コンピュータ・リテラルは、ファイル名や変数名などの、コンピュータが認識するテキストです。コンピュータ・リテラルは、それだけを分けて表示することも、インライン要素として表示することもできます。

• 注、注意、警告は、重要な情報へ読者の注意を促します。

• 強調表示は、パラグラフのテキスト内の重要な語句を強調表示するのに使用します。

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

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

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

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

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

例

次の例は、空白行 1 行で区切られた 2 つのパラグラフです。どちらの段落にも特別なパラメータがないので、<p> タグを入力する必要はありません (これは 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>

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

関連項目

• 「<list> 」では、<list> 要素の使い方をまとめています。

• 「<lablist> 」では、<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>

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

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

関連項目

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

• 「<ex> 」

• 「<vex> 」

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

<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 注、警告、注意のヘルプ・アイコン

関連項目

• 「実行時のヘルプ・ボリュームを作成するには」では、helptag.opt ファイルの使い方を説明しています。

• 「エンティティの使い方」

インライン要素の入力

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

語句を強調表示するには

<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>、<p>、<image>、<figure>、<graphic> などの割り当て済み ID のこともあります。

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

• ハイパーテキスト・リンクは、他のヘルプ・トピックへ「ジャンプ」します。デフォルトでは、新しいトピックは同じウィンドウに表示されますが、新規ウィンドウに表示するよう要求することもできます。

• 定義リンクは、簡単なポップアップのヘルプ・ウィンドウにトピックを表示します。ほとんどの場合、定義リンクは文中の新しい語句の定義を見るために使用されます。

• マニュアル・ページへのリンクは、システムにインストールされているマニュアル・ページを表示します。

• 実行リンクは、シェル・コマンドまたはプログラムを実行します。これにより、ユーザがハイパーリンクを起動すると発生する動作は、非常に広範囲なものになります。

• アプリケーション定義リンクは、アプリケーションが解釈するカスタム・リンクを作成します。これにより、ヘルプ・システムとアプリケーション間の通信機能が提供されます。

ある要素へのハイパーリンクを作成するには、ハイパーリンク・コマンドにその要素の ID を指定します。ヘルプタグは、ID へのハイパーリンク作成に使用できる <xref> と <link> の 2 つの要素が提供しています。また、<p>、<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 ファイルに適切な検索パスを指定してください。

関連項目

• 「アプリケーションとそのヘルプの登録」

• 「<figure> 」

• 「<image> 」

• 「<link> 」

• 「<p> 」

• 「<xref> 」

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

用語集にある用語へリンクする場合は、<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」の句がハイパーリンク・テキスト (破線の下線) になります。

関連項目

• 「用語集の作成」

• 「<term> 」

• 「<link> 」

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

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

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

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

関連項目

• 「組み込み ID」に、ヘルプ・システムの定義済み ID をリストしています。

実行リンクの制御

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

ヘルプ・システムは、実行リンクの動作を定義するためにリソースを使用します。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> 要素を使って参照したり、<p> や <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 を設定することは避けた方がよいでしょう。システム管理者やユーザがこの値を変更できなくなってしまうからです。

関連項目

• 「<link> 」

• 「<figure> 」

• 「<p> 」

• DtHelpDialog(3)

• DtHelpQuickDialog(3)

グラフィックの表示

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

• TIFF (Tagged Image File Format)

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

• X ウィンドウ・ダンプ

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

• X ピックスマップ

  カラーのアイコン・イメージ (filename.pm)

• X ビットマップ

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

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

図を作成するには

1. 図中に取り込むイメージ・ファイルを識別するために、ファイル・エンティティを宣言します。

      
   <!entity graphic-entity FILE "filename.ext">  

   エンティティ宣言はすべて、ヘルプ・ボリュームの最初にある、その他のマークアップよりも前にある必要があることを忘れないようにして下さい。

2. <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> 

関連項目

• 「<figure> 」

• 「<link> 」

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

1. 図中に取り込むイメージ・ファイルを識別するために、ファイル・エンティティを宣言します。

      <!entity graphic-entity FILE "filename.ext">  

   エンティティ宣言はすべて、ヘルプ・ボリュームの最初にあるその他のマークアップよりも前にある必要があります。

2. <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.

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

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

1. パラグラフ中に入れるイメージ・ファイルを識別するために、ファイル・エンティティを宣言します。

      <!entity graphic-entity  FILE  "filename.ext"> 

2. <p> (段落) 要素を gentity パラメータと共に次のように使用します。

      <p gentity=graphic-entity> 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.

関連項目

• 「<p> 」

特殊文字の表示

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

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

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

特殊文字を表示するには

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

2. 組み込み特殊文字でない場合は、次の 2 行をその他のエンティティ宣言に追加します (entity-name は表示したい文字のエンティティ名です)。

      <!entity entity-name FILE  "helpchar.ent">  &entity-name;
   &entity-name;
   

   また、次の行を helptag.opt ファイルに追加します。

      search=/usr/dt/dthelp/dthelptag

   ヘルプタグに組み込まれている文字の場合は、手順 2 を省略できます。

3. 特殊文字を表示したい場所には、エンティティ参照を入力します。

      &entity-name;

例

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

©

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

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

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

&Usigma;

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

関連項目

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

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

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

標準のコメントに加えて、作成者のメモを入力するためにヘルプタグは <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.

関連事項

• 「<dterm>」

• 「<glossary> 」

• 「<term> 」