RELAX NG

Documentation

After this long introduction to annotation syntax, it is time to explore applications of annotations. The first application of annotations is for documentation. The issue of generating documentation from schemas, much like the problem of generating documentation from code, is a long-running problem with three different schools of thought:

• The documentation and the schema are stored separately. In this case, there is nothing specific to documenting RELAX NG schemas, and this technique is beyond the scope of this book.

• The schema can be embedded in the documentation: proponents of “Literate Programming” are fans of this approach. It will be presented in Chapter 14.

• The documentation can be embedded within the schema: I’ll cover this approach in this section.

You’ve seen the technical basis of how these annotations can be included in RELAX NG schemas. Generating documentation from these annotations is mainly a matter of writing an XSLT transformation to extract them and then formatting the annotations according to your needs. I won’t be going through the details of XSLT transformations, but the following examples are good candidates for these kinds of transformation.

Comments

This example uses simple comments:

   <define name="author-element">
     <!-- Definition of the author element -->
     <element name="author">
       <attribute name="id"/>
       <ref name="name-element"/>
       <ref name="born-element"/>
       <optional>
         <ref name="died-element"/>
       </optional>
     </element>
   </define>

which is equivalent to: ...