One of the cool things about Relax NG is that it permits schema editors to insert annotations using markup from other XML languages at certain points in schemas for the purpose of integrating documentation with the schemas. See e.g. the Annotations section from the Relax NG tutorial. It was one of the original goals of CNXML 0.6 to be able to derive the specification from docs integrated with the schemas. We didn't get to it, of course. With CNXML 0.7 and CollXML 1.0, however, we are making a down-payment on that goal by using CNXML to integrate documentation with the schemas.

Here are the basic constructs (using XPath notation, with 'cnxml' as the prefix for the CNXML namespace, and 'rng' as the prefix for the Relax NG namespace):

• cnxml:para[@class="description"] appearing as the first child of a define, or of a div that contains several related defines, will contain prose descriptive text about the element or attribute being defined.
• cnxml:para[@class="content"] appearing as a child of a define, or of a div that contains several related defines, will contain a prose description of the content model of the element or attribute being defined.
• cnxml:para[@class="default-value"] appearing as a child of a define, or of a div that contains several related defines, will contain a prose description of the default value for the attribute being defined.
• rng:choice/@cnxml:class[.="possible-values"] in the definition of an attribute indicates that the member values of the choice element represent the full range of valid values for the attribute being defined.
• rng:choice/@cnxml:class[.="supported-values"] in the definition of an attribute indicates that the member values of the choice element represent the full range of values supported by Connexions/Rhaptos for the attribute being defined; other values are possible (generally, <text/> is one of the values), but they aren't given application support by Conexions/Rhaptos.

By adding @cnxml:class to a Relax NG element, we can make the RNG element serve two purposes: grammar definition, and documentation source.

When the RNG schema specifies one of an enumerated list of values as the default value in an attribute definition, it makes use of @defaultValue in the RNG Annotations namespace ('http://relaxng.org/ns/compatibility/annotations/1.0'). An XSLT stylesheet or other XML process that extracts documentation from the schema can make use of this attribute and value in indicating the default value for the attribute being defined.

Note that I did not not get around to providing documentation for the majority of definitions in cnxml-defs.rng. Note also that the above approach was arrived at as I worked on documenting the schemas, and it isn't applied consistently in some of the earlier work I did (esp. in CollXML).

Some examples:

An attribute definition with a description, content description, and default value.

  <define name="mark-prefix-attribute">
    <cnxml:para class="description">An attribute that specifies 
      characters that should appear beforethe marks of the 'item' 
      children of the parent 'list' element.</cnxml:para>
    <cnxml:para class="content">Content is text 
      (Relax NG).</cnxml:para>
    <cnxml:para class="default-value">Default is the empty 
      string.</cnxml:para>
    <optional>
      <attribute name="mark-prefix"/>
    </optional>
  </define>

An attribute definition with a description and a list of possible values. The default value for the attribute is indicated by the rng:attribute/@a:defaultValue value, and this construct should be used by a documentation extractor/formatter.

  <define name="number-style-attribute">
    <cnxml:para class="description">An attribute that style of 
      number to use for the enumerations in the parent 'list' 
      element's 'item' children.  May occur only on 'list' elements 
      with a 'list-type' of 'enumerated'.</cnxml:para>
    <optional>
      <attribute name="number-style" a:defaultValue="arabic">
        <choice cnxml:class="possible-values">
          <value>arabic</value>
          <value>upper-alpha</value>
          <value>lower-alpha</value>
          <value>upper-roman</value>
          <value>lower-roman</value>
        </choice>
      </attribute>
    </optional>
  </define>