ENGLISHJAPANESE
<< リラックスのしかた/第一部: RELAX Core/STEP 4: 注釈 >>

STEP 4: 注釈

$Id: step4.sdoc 1.12 2000/11/01 13:43:29 murata Exp $
DTDを説明する資料を作るのは大変重要な作業です．DTDは単に構文を定義するだけですから，自然言語による大量の注釈によって意味を説明することが必要になります．XMLにあるコメントは使えますが，RELAXモジュールを構文解析してから表示するブラウザはコメントを無視してしまいます．
STEP 4は，モジュールに注釈を入れるための機構について説明します．これらは要素と属性を用いていますから，RELAXモジュールを構文解析するブラウザも，ユーザに分かりやすい形で注釈を表示することが出来ます．

annotation要素

注釈を挿入するためのトップレベルの要素が，annotation要素です．annotation要素が入れられるのは，次の箇所です．
elementRule要素の最初の子として，注釈を使用した例を以下に示します．注釈の内容は省略しています．

<elementRule role="para">
  <annotation> ... </annotation>
  <mixed>
    <ref label="fnote" occurs="*"/>
  </mixed>
</elementRule>

annotation要素は，子要素としてdocumentationとappinfoをいくつでも持つことができます．

documentation要素

自然言語による説明を表現するための要素がdocumentation要素です．RELAX Namespaceが制定されていない現時点は，テキストデータしか入れられません．
さきに示した例にdocumentationを付加したものを次に示します．

<elementRule role="para">
  <annotation>
    <documentation>This is a paragraph.</documentation>
  </annotation>
  <mixed>
    <ref label="fnote" occurs="*"/>
  </mixed>
</elementRule>

documentation要素がsource属性を持つ場合は，説明を参照するURIが属性値です．この場合は，documentation要素の内容は使われません．モジュールを表示するツールは，リンクを利用した表示を提供します．

<elementRule role="para">
  <annotation>
    <documentation source="http://www.xml.gr.jp/relax/"/>
  </annotation>
  <mixed>
    <ref label="fnote" occurs="*"/>
  </mixed>
</elementRule>

documentation要素にxml:lang属性が指定されたときは，documentation要素の内容が，どの自然言語で書かれているかを示します．
つぎの例では，xml:langの値として"en"が指定されています．

<elementRule role="para">
  <annotation>
    <documentation xml:lang="en">This is a paragraph.</documentation>
  </annotation>
  <mixed>
    <ref label="fnote" occurs="*"/>
  </mixed>
</elementRule>

appinfo要素

文書とRELAXモジュールを照合する検証プログラム以外にも，RELAXモジュールを操作するプログラムはいくらでも存在し得ます．たとえば，モジュールからデータベースのスキーマを生成するプログラムです．そのようなプログラムが利用するための隠し情報を表現するのがappinfo要素です．RELAX Namespaceが制定されていない現時点は，テキストデータしか入れられません．

<elementRule role="foo" type="integer">
  <annotation><appinfo>default:1</appinfo></annotation>
</elementRule>

appinfo要素がsource属性を持つ場合は，隠し情報を参照するURLが属性値です．この場合は，appinfo要素の内容は使われません．

div要素

複数のelementRule, hedgeRule, tag, attPoolを一つにまとめて注釈をつけたいことがあります．そのために用意されているのがdiv要素です．
div要素は，module要素の中に，elementRule, hedgeRule, tag, attPoolと同レベルに置きます．div要素の中にさらにdiv要素を置くこともできます．div要素の中には，elementRule, hedgeRule, tag, attPool, divを置くことができます．
STEP 1に示したモジュールにdivを使用して注釈を加えたものを下に示します．

<module
      moduleVersion="1.2"
      relaxCoreVersion="1.0"
      targetNamespace=""
      xmlns="http://www.xml.gr.jp/xmlns/relaxCore">

  <interface>
    <export label="doc"/>
  </interface>

  <div>
    <annotation>
      <documentation>The root node</documentation>
    </annotation>

    <elementRule role="doc">
      <sequence>
        <ref label="title"/>
        <ref label="para" occurs="*"/>
      </sequence>
    </elementRule>

    <tag name="doc"/>

  </div>

  <div>
    <annotation>
      <documentation>Paragraphs</documentation>
    </annotation>

    <elementRule role="para">
      <mixed>
        <ref label="em" occurs="*"/>
      </mixed>
    </elementRule>

    <tag name="para">
      <attribute name="class" type="NMTOKEN"/>
    </tag>

  </div>

  <elementRule role="title">
    <mixed>
      <ref label="em" occurs="*"/>
    </mixed>
  </elementRule>

  <tag name="title">
    <attribute name="class" type="NMTOKEN"/>
    <attribute name="number" required="true" type="integer"/>
  </tag>

  <elementRule role="em" type="string"/>
  <tag name="em"/>

</module>

まとめ

STEP 4で，モジュールの説明を書くのが容易になりました．RELAX!
<< リラックスのしかた/第一部: RELAX Core/STEP 4: 注釈 >>