STEP 4: Annotation

$Id: step4e.html 1.5 2000/02/29 12:02:55 murata Exp $

text by MURATA Makoto

html by NAMBA Ryosuke

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 atributes, browsers which parse RELAX modules can show annotations in an user-friendly manner.

1. The annotation element

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

• at most once before the interface element
• as children of the interface element
• at most once in an export element
• as siblings of elementRule, hedgeRule, tag, attList
• 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 attList
• at most once as the eldest child of each attribute
• at most once directly below each include
• at most once as the eldest child of each element

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

1.1 The documentation element

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

If a documentation element has the source attribute, the attribute value is an 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.

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.

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

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

2. Summary

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