STEP 4: Annotation

$Id: step4.sdoc 1.12 2000/11/01 13:43:29 murata Exp $

DTD documentation is highly important. Since DTDs merely define syntactical constructs, plenty of annotations in natural languages are required so as to explain the intended semantics of these constructs. Although XML comments are always available, such comments will be ignored by browsers which parse and then display RELAX modules.

STEP 4 provides features for annotating RELAX modules. Since they are represented by elements and attributes, browsers which parse RELAX modules can show annotations in a user-friendly manner.

The annotation element

The top-level element for annotations is the annotation element. annotation may occur in the following places.

• at most once before the interface element
• at most once in an export element
• at most once as the eldest child of each elementRule
• at most once as the eldest child of each hedgeRule
• at most once as the eldest child of each tag
• at most once as the eldest child of each attPool
• at most once as the eldest child of each attribute
• at most once as the child of each include
• at most once as the eldest child of each element
• at most once as the eldest child of each div

The elementRule element shown below has an annotation as its eldest child. The content of this annotation is omitted.

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

Child elements of an annotation element are documentation elements and appinfo elements.

The documentation element

documentationis an element for representing explanations in natural languages. Since RELAX Namespace is not available yet, documentation may contain text data only.

The following shows a documentation element added to the above example.

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

If a documentation element has the source attribute, the attribute value is a URI that references to an explanation. In this case, the content of documentation is not used. Browsers for modules typically use this URI to provide a link.

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

If a documentation element has the xml:lang attribute, the attribute value announces the natural language in which the content of the documentation is written.

In the next example, "en" is specified as the value of xml:lang.

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

The appinfo element

Other than verifiers, which examine documents against RELAX modules, many programs might handle RELAX modules. For example, some programs may create a database schema from a module. appinfo provides hidden information for such programs. Since RELAX Namespace is not available yet, appinfo may contain text data only.

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

If an appinfo element has the source attribute, the attribute value is a URI that references to hidden information. In this case, the content of appinfo is not used.

The div element

We often would like to annotate a collection of elementRules, hedgeRules, tags, and attPools. The div element allows such an annotated group.

divelements may occur in module elements as siblings of elementRules, hedgeRules, tags, and attPools. div elements may further contain div elements. A div element may contain elementRules, hedgeRules, tags, attPools, and divs.

The following is a module shown in STEP 1. It is annotated after introducing div elements.

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

Summary

STEP 4 makes it easy to document your module. Enjoy and RELAX!