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.
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 isconcept-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.