RELAX NG: Coding requirements for structural modules

A structural vocabulary module defines a new topic or map type as a specialization of a topic or map type.

All vocabulary and constraint modules must document their @domains attribute contribution. The value of the contribution is constructed according to the rules found in domains attribute rules and syntax. The OASIS grammar files use a <domainsContribution> element to document the contribution; this element is used to help enable generation of DTD and XSD grammar files. An XML comment or <a:documentation> element can also be used.

Required topic and map element attributes

The topic or map element type must reference the arch-atts pattern, which defines the @DITAArchVersion attribute in the DITA architecture namespace and sets the attribute to the version of DITA in use. In addition, the topic or map element type must reference the domains-att pattern, which will pull in a definition for the @domains attribute. These attributes give processors a reliable way to check the architecture version and list of available domains.

For example, the following definition references the arch-atts and domains-att patterns as part of the definition for the <concept> element.

<div>
  <a:documentation> LONG NAME: Concept </a:documentation>
  <!-- ... -->
  <define name="concept.attlist" combine="interleave">
    <ref name="concept.attributes"/>
    <ref name="arch-atts"/>
    <ref name="domains-att"/>
  </define>
  <!-- ... -->
</div>

Controlling nesting in topic types

Specialized topics typically define an info-types style pattern to specify default topic nesting. Document type shells can then control how topics are allowed to nest by redefining the pattern. While there are known exceptions described below, the following rules apply when using a pattern to control topic nesting.

Pattern name

The pattern name is the topic element name plus the suffix -info-types. For example, the info-types pattern for the concept topic type is concept-info-types.

Pattern value

To set up default topic nesting rules, set the pattern to the desired topic elements. The default topic nesting will be used when a document-type shell does not set up different rules. For example:

<div>
  <a:documentation>INFO TYPES PATTERNS</a:documentation>
  <define name="mytopic-info-types">
    <ref name="subtopictype-01.element"/>
    <ref name="subtopictype-02.element"/>
  </define>
  <!-- ... -->
</div>

If the topic does not permit nested topics by default, this pattern uses the <empty> element. For example:

<define name="learningAssessment-info-types">
  <empty/>
</define>

The info-types pattern can also be used to refer to common nesting rules across the document-type shell. For example:

<div>
  <a:documentation>INFO TYPES PATTERNS</a:documentation>
  <define name="mytopic-info-types">
    <ref name="info-types"/>
  </define>
  <!-- ... -->
</div>

Content model of the root element

In the declaration of the root element of a topic type, the last position in the content model SHOULD be the topictype-info-types pattern. For example, the <concept> element places the pattern after <related-links>:

<div>
  <a:documentation>LONG NAME: Concept</a:documentation>
  <define name="concept.content">
    <!-- ... -->
    <optional>
      <ref name="related-links"/>
    </optional>
    <zeroOrMore>
      <ref name="concept-info-types"/>
    </zeroOrMore>
  </define>
</div>

In rare cases, it might not be desirable to control topic nesting with the info-types pattern. For example:

If a specialized topic type should never allow any nested topics, regardless of context, it can be defined without any pattern or any nested topics.
If a specialized topic type should only ever allow specific nesting patterns, such as allowing only other topic types that are defined in the same module, it can nest those topics directly in the same way that other nested elements are defined.