test

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

第 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 つ以上の要素を囲むには括弧を使用します。

例

各例には、提供されている要素宣言に対する語の説明があります。必要な開始タグと終了タグが使用されます。

要素宣言のキーワード

要素の中には、要素宣言の中に、要素のデータ内容を説明するキーワードを含むものがあります。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>

正規マークアップ

正規マークアップの作成には、構造化エディタを使用するのが最良の方法です。基本的な要素のセットを覚えれば、設計者は作業を始められます。作業の開始は、メニューから要素を選択することです。それに応じて、構造化エディタが各要素に必要なすべてのタグを生成します。さらにアプリケーションが、作成中の構造フレームワークが文書型定義に準拠するかを確認します。

簡易マークアップ、正規マークアップ、構造化エディタについては、「ヘルプタグによるヘルプ・トピックの記述」を参照してください。

正規マークアップの注意点

簡易マークアップと正規マークアップは共通の要素のセット (章、セクション、ヘッダ、リスト、段落など) を共用しています。しかし、正規マークアップは次のような重要な点で簡易マークアップとは異なります。

明示的な開始タグおよび終了タグ

各要素、そのコンポーネント部分、各要素内の要素は明示的にタグ付けされなければなりません。たとえば、次の例は章のヘッダの正規マークアップです。この例やその他のマークアップ例では、読みやすいようにタグをインデントしてあります。実際のマークアップではインデントは必要ありません。

<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 です。オンラインでは、簡易マークアップと正規マークアップのどちらを使用しても同じです。