test

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

正規マークアップ

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

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

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

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

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

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

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

エンティティは、簡易マークアップの場合とまったく同様に正規マークアップでも参照されます。