RELAX NG: Coding requirements for structural and element-domain modules

Module files

Each RELAX NG vocabulary module consists of a single module file.

Element definitions

A structural or element-domain vocabulary module contains a declaration for each element type that is named in the module. While the XML standard allows content models to refer to undeclared element types, the DITA standard does not permit it. All element types or attribute lists that are named in a vocabulary module are declared in one of the following objects:

• The vocabulary module
• A base module of which the vocabulary module is a direct or indirect specialization
• (If the vocabulary module is a structural module) A required domain or structural module

The element type patterns are organized into the following sections:

Element type name patterns

For each element type that is declared in the vocabulary module, there is a pattern whose name is the element type name and whose content is a reference to the tagname.element pattern for the element type.

Example

This section is non-normative.

The following example shows the pattern for the <b> element:

<div>
  <a:documentation>ELEMENT TYPE NAME PATTERNS</a:documentation>
    <!-- ... -->
    <define name="b">
      <ref name="b.element"/>
    </define>
    <!-- ... -->
</div>

The element-type name pattern provides a layer of abstraction that facilitates redefinition. The element-type name patterns are referenced from content model and domain extension patterns. Specialization modules can re-declare the patterns to include specializations of the type, allowing the specialized types in all contexts where the base type is allowed.

The declarations can occur in any order.

Common content-model patterns

Structural and element-domain modules can include a section that defines the patterns that contribute to the content models of the element types that are defined in the module.

Common attribute sets

Structural and element-domain modules can include a section that defines patterns for attribute sets that are common to one or more of the element types that are defined in the module.

Element type declarations

For each element type that is declared in the vocabulary module, the following set of patterns are used to define the content model and attributes for the element type. Each set of patterns typically is grouped within a <div> element.

tagname.content

Defines the complete content model for the element tagname. The content model pattern can be overridden in element-configuration modules (constraint and expansion).

tagname.attributes

Defines the complete attribute list for the element tagname, except for @class. The attribute list declaration can be overridden in element-configuration modules (constraint and expansion).

tagname.element

Provides the actual element-type definition. It contains an <element> element whose @name value is the element type name and whose content is a reference to the tagname.content and tagname.attlist patterns.

tagname.attlist

Contains an additional attribute-list pattern with a @combine attribute set to the value interleave. This pattern contains only a reference to the tagname.attributes pattern. This pattern enables the integration of attribute specializations.

Example

This section is non-normative.

The following example shows the declaration for the <topichead> element, including the definition for each pattern described above.

    <div>
      <a:documentation>Topic Head</a:documentation>
      <define name="topichead.content">
        <optional>
          <ref name="topicmeta"/>
        </optional>
        <zeroOrMore>
          <choice>
            <ref name="data.elements.incl"/>
            <ref name="navref"/>
            <ref name="topicref"/>
          </choice>
        </zeroOrMore>
      </define>
      <define name="topichead.attributes">
        <optional>
          <attribute name="keys"/>
        </optional>
        <ref name="topicref-atts"/>
        <ref name="univ-atts"/>
      </define>
      <define name="topichead.element">
        <element name="topichead">
          <a:documentation/>
          <ref name="topichead.attlist"/>
          <ref name="topichead.content"/>
        </element>
      </define>
      <define name="topichead.attlist" combine="interleave">
        <ref name="topichead.attributes"/>
      </define>

    </div>

idElements pattern contribution

Element types that declare the @id attribute as type "ID", including all topic and map element types, provide a declaration for the idElements pattern. This is required to correctly configure the any pattern override in document-type shells and avoid errors from RELAX NG parsers. The declaration is specified with a @combine attribute set to the value choice.

For example:

<div>
  <a:documentation>LONG NAME: Map</a:documentation>
  <!-- ... -->
  <define name="idElements" combine="choice">
    <ref name="map.element"/>
  </define>
</div>

Specialization attribute declarations

A vocabulary module must define a @class attribute for every specialized element. This is done in a section at the end of each module that includes a tagname.attlist pattern for each element type that is defined in the module. The declarations can occur in any order.

The tagname.attlist pattern for each element defines the value for the @class attribute for the element. @class is declared as an optional attribute. The default value is declared using the @a:defaultValue attribute, and the value of the attribute is constructed according to the rules in The class attribute rules and syntax.

For example:

<define name="topichead.attlist" combine="interleave">
  <optional>
    <attribute name="class" 
        a:defaultValue="+ map/topicref mapgroup-d/topichead "
    />
  </optional>
</define>