RELAX NG: Coding requirements for document-type shells

This section is non-normative.

A RNG-based document-type shell is organized into sections; each section follows a pattern. These patterns help ensure that the shell follows XML parsing rules for RELAX NG; they also establish a modular design that simplifies creation of new document-type shells.

An RNG-based document-type shell contains the following sections:

  1. Root element declaration
  2. specializations attribute
  3. Element-type configuration integration
  4. Module inclusions
  5. ID-defining element overrides
Root element declaration

Document-type shells use the RELAX NG start declaration to specify the root element of the document type. The <start> element defines the root element, using a reference to a tagname.element pattern.

For example:
<div>
  <a:documentation>ROOT ELEMENT DECLARATION</a:documentation>
  <start combine="choice">
    <ref name="topic.element"/>
  </start>
</div>
@specializations attribute

This section lists the tokens that attribute-domain and element-configuration modules contribute to the @specializations attribute.

For example:
<div>
  <a:documentation>SPECIALIZATIONS ATTRIBUTE</a:documentation>
  <define name="specializations-att">
    <optional>
      <attribute name="specializations"
                 a:defaultValue="@props/audience
                                 @props/deliveryTarget                                 
                                 @props/otherprops
                                 @props/platform
                                 @props/product"
      />
    </optional>
  </define>
</div>
Element-type configuration integration

This section of the document-type shell contains includes for element-type configuration modules (constraint and expansion). Because an element-configuration module imports the module that it overrides, any module that is configured in this section (including the base topic or map modules) is left out of the following "Module inclusion" section.

The following code sample shows the section of an RNG-based document-type shell that redefines the <taskbody> element to create the strict task topic.

<div>
<a:documentation>ELEMENT-TYPE CONFIGURATION INTEGRATION</a:documentation>
  <include href="strictTaskbodyConstraintMod.rng"/>            
</div>
Module inclusions

This section of the RNG-based document-type shell includes all unconstrained domain or structural modules.

For example:
  <div>
    <a:documentation>MODULE INCLUSIONS</a:documentation>
    <include href="topicMod.rng">
      <define name="topic-info-types">
        <ref name="topic.element"/>
      </define>
    </include>
    <include href="audienceAttDomain.rng" dita:since="2.0"/>
    <include href="deliveryTargetAttDomain.rng"/>
    <include href="otherpropsAttDomain.rng" dita:since="2.0"/>
    <include href="platformAttDomain.rng" dita:since="2.0"/>
    <include href="productAttDomain.rng" dita:since="2.0"/>
    <include href="alternativeTitlesDomain.rng" dita:since="2.0"/>
    <include href="emphasisDomain.rng" dita:since="2.0"/>
    <include href="hazardstatementDomain.rng"/>
    <include href="highlightDomain.rng"/>
    <include href="utilitiesDomain.rng"/>
  </div>
ID-defining element overrides

This section declares any element in the document type that uses an @id attribute with an XML data type of ID. This declaration is required in order to prevent RELAX NG parsers from issuing errors.

If the document-type shell includes domains for foreign vocabularies such as SVG or MathML, this section also includes exclusions for the namespaces used by those domains.

For example, the following code sample is from an RNG-based document-type shell for a task topic. It declares that both the <topic> and <task> elements have an @id attribute with an XML data type of ID. These elements and any elements in the SVG or MathML namespaces are excluded from the "any" pattern by being placed within the <except> element:
  <div>
      <a:documentation> ID-DEFINING-ELEMENT OVERRIDES </a:documentation>
      <define name="any">
         <zeroOrMore>
            <choice>
               <ref name="idElements"/>
               <element>
                  <anyName>
                     <except>
                        <name>topic</name>
                        <name>task</name>
                        <nsName ns="http://www.w3.org/2000/svg"/>
                        <nsName ns="http://www.w3.org/1998/Math/MathML"/>
                     </except>
                  </anyName>
                  <zeroOrMore>
                     <attribute>
                        <anyName/>
                     </attribute>
                  </zeroOrMore>
                  <ref name="any"/>
               </element>
               <text/>
            </choice>
         </zeroOrMore>
      </define>
  </div>