ENGLISH | JAPANESE |
$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.
annotation
elementThe top-level element for annotations is the annotation
element. annotation
may occur in the following places.
interface
element
export
element
elementRule
hedgeRule
tag
attPool
attribute
include
element
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.
documentation
elementdocumentation
is 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>
appinfo
elementOther 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.
div
elementWe often would like to annotate a collection of elementRule
s, hedgeRule
s, tag
s, and attPool
s. The div
element allows such an annotated group.
div
elements may occur in module
elements as siblings of elementRule
s, hedgeRule
s, tag
s, and attPool
s. div
elements may further contain div
elements. A div
element may contain elementRule
s, hedgeRule
s, tag
s, attPool
s, and div
s.
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>
STEP 4 makes it easy to document your module. Enjoy and RELAX!