この章では、ヘルプタグ 1.3 文書型定義 (DTD) の読み方と、完全に準拠した Standard Generalized Markup Language (SGML) ヘルプ・ファイルを作成するための DTD の使用方法を説明します。
文書型定義 (DTD) は、構造化された (または階層のある) ドキュメントを作成するために要素のセットを定義します。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 です。
dthelptagdtd(4) のマニュアル・ページ
DTD は、これまでの章で説明したヘルプタグの各要素を定義します。この節では、いくつかの重要な用語を紹介し、要素記述の構文の読み方を説明します。DTD の各セクションを完全に説明するものではありません。
DTD は各要素を要素宣言で定義します。宣言には、要素を説明する詳細な記述、それに必要なコンポーネント、指定できる要素またはできない要素を使用します。要素には属性宣言で定義された特性もあります。特性の詳細は、「属性リスト宣言」のセクションで説明します。
要素宣言の形式は次のとおりです。
<ELEMENT element_type minimization (content model) >
要素名を指定します。これはタグ名としても使用されます。たとえば、要素型 head のタグは <head> です。
開始タグまたは終了タグが必要かどうかを示す 2 文字のエントリです。1 番目の文字は開始タグを表します。2 番目の文字は終了タグを表します。その 2 文字の間に 1 つ空白が入ります。文字 o はそのタグがオプションであることを意味します。- (マイナス記号) はタグが必要であることを意味します。たとえば、- - というエントリは、その要素には開始タグと終了タグの両方が必要であるという意味です。ヘルプタグ 1.3 用 DTD ではすべての要素に開始タグと終了タグが必要です。
要素型に含められる必要な要素およびオプションの要素のリストを指定します。要素のシーケンスと、適用可能であれば、要素を指定できる回数を定義します。
コンテント・モデルは次の記述を使用します。
「or」という意味です。
要素を最低 1 回は指定しなければなりません。繰り返し可能です。
要素を 0 回以上指定しなければなりません。
要素を 0 回または 1 回指定しなければなりません。
カンマはシーケンスを説明します。つまり、要素型の後には、カンマの後に指定された要素が続かなければなりません。
+ (プラス記号) は、リストされた 1 つまたは複数の要素が、この要素内か、それを含む要素どの中でも使用できることを示します。これを取り込みと呼びます。 1 つ以上の要素を囲むのに括弧を使用します。
- (マイナス記号) は、リストされた 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 つのキーワードがあります。
要素が、オンライン情報で表示されるデータ内容を持たないことを指定します。newline 要素と xref 要素がこの例です。
「文字データ」を表します。つまり、その要素のデータ内容はマークアップとして認識されません。
「構文解析された文字データ」を表します。つまり、そのデータ内容にはヘルプ・システムのパーサが解釈するテキストとマークアップ文字の両方が含まれます。
属性リストは、要素をより詳しく説明する追加の属性を宣言します。属性リスト宣言の形式は次のとおりです。
<!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 です。オンラインでは、簡易マークアップと正規マークアップのどちらを使用しても同じです。