Modularization in DTDs

To support extensibility and pluggability, DITA requires that a DTD implementation of structural and domain specialization modules conform to well-defined design patterns.

This section describes those design patterns. These design patterns realize the specialization architecture with the capabilities and within the limitations of the DTD grammar.

Structural specialization pattern

Each structural type must be defined in a separate DTD module with a name consisting of the topic element name and the mod extension. To see an example, look at the concepts.mod module for the concept topic type.

The structural type module must conform to the following design pattern.

Default element entities
Each element defined in the module must have a corresponding entity whose default value is the name of the element. The following example comes from the definition for the concept topic.
<!ENTITY % conbody "conbody">

The document type shell can predefine an element entity to add domain specialized elements into every context in which the base element occurs.

Default included domains entity
The module must define the included-domains entity with a default empty that is empty as in the following example:
<!ENTITY included-domains "">

The document type shell can predefine the included-domains entity to list domains added to the document type.

Default nested topics entity
Topic type modules must define an info-types entity that is named with a prefix of the topic element name and a suffix of -info-types. This entity can default to a list of element entities if the topic has default subordinate topics. If the topic doesn't have default subordinate topics, the entity can default to the value of the info-types entity as in the following example:
<!ENTITY % concept-info-types "%info-types;">

The document type shell can then control how topics are allowed to nest by redefining the topictype-info-types entity for each topic type, or quickly create common nesting rules by redefining the main info-types entity.

Structural type's root element content model
As with all specializations, the root element of a structural specialization must have a content model that restricts or conserves the content model of the element it specializes. In addition, for topic types, the last position in the content model must be the nested topics entity as in the following example:
<!ELEMENT concept        ((%title;), (%titlealts;)?, (%shortdesc;)?,
        (%prolog;)?, (%conbody;), (%related-links;)?, 
        (%concept-info-types;)* )>
Attributes
As with all specializations, the root element's attributes must restrict or conserve the attributes of the element it specializes. In particular, the topic must set the DITAArchVersion attribute to the DITAArchVersion entity and the domains attribute to the included-domains entity.
<!ATTLIST concept         id ID #REQUIRED
                          ...
                          DITAArchVersion CDATA "&DITAArchVersion;"
                          domains CDATA "&included-domains;"
>

These attributes give processes a reliable way to check the architecture version and look up the list of domains available in the document type.

Element and attribute definitions
The module defines every specialized element used as substructure within the topic. The specialized elements must follow the rules of the architecture in defining content models and attributes. Content models must use element entities instead of literal element names.

In particular, the module defines a class attribute for every specialized element. The class attribute must include the value of the class attribute of the base element and append the element name qualified by the topic element name with at least one leading and trailing space. The class attribute for an element introduces by a structural specialization must start with a minus sign.

Domain specialization pattern

Each domain specialization must have two files:


To see an example, look at the highlightDomain.ent and highlightDomain.mod files.

Domain entity declaration file

The domain entity declaration file must conform to the following design pattern:

Element extension entity
The declaration file must define an entity for each element extended by the domain. The contents of the entity must be the list of specialized elements for the extended element. The name of the entity has a prefix of the abbreviation for the domain and an extension of the name of the extended element. In the following example, the highlight domain (abbreviated as hi-d) extends the ph element.
<!ENTITY % hi-d-ph "b | u | i | tt | sup | sub">
Domain declaration entity
The declaration file must define one entity for the document type shell to register the domain. The name of the entity has a prefix of the abbreviation for the domain and an att extension. The value of the entity must list the dependencies of the domain module in order of dependency from left to right within enclosing parentheses, starting with the topic module and listing domain dependencies using their abbreviations (including the defining domain as the last item in the list). The following example declares the dependency of the highlight domain on the base topic module.
<!ENTITY hi-d-att "(topic hi-d)">

Domain definition module

The domain definition module conforms to the following design pattern:

Default element entities
As in a topic module, the domain definition module must declare a default entity for each element defined by the domain so that other domains can extend the elements.
<!ENTITY % b "b">
Element and attribute definitions
As in a topic module, the domain definition module must define each specialized element and its attributes. As with any specialization, the domain element must restrict the base element. The class attribute of the domain element must start with a plus sign but, otherwise, follows the same rules as the class attribute for an element introduced by a topic specialization.

Attribute domain specialization pattern

The attribute domain pattern is a special case of the domain specialization pattern, which allows the creation of new attributes specialized from the props or base attribute.

Create one module entity file per attribute, for example newAttDomain.ent. Each module should contain the following:
Attribute extension entity
The entity which holds the actual declaration of the attribute in entity form. This entity can then be used in document type shells to add the new attribute. For example:
<!ENTITY % newAtt-d-attribute "new   CDATA #IMPLIED">
Domain declaration entity
The entity which holds the name of the attribute domain in entity form. This entity can then be used in document type shells to signal the availability of the attribute to DITA-aware processes. It uses the same syntax as a regular domain declaration entity but with the addition of a leading "a" to signal that it is in attribute domain. For example:
<!ENTITY newAtt-d-att       "a(props new)"  >

Document type shell pattern

The document type shell must conform to the following design pattern. To see an example, look at the concepts.dtd module for the concept document type.

Domain entity inclusions
The document type shell starts by including the domain entity declaration files. The entity for the domain declaration consists of the domain name prefix with the dec suffix, as in the following examples:
<!ENTITY % hi-d-dec PUBLIC
    "-//OASIS//ENTITIES DITA Highlight Domain//EN" "highlightDomain.ent">
    %hi-d-dec;
<!ENTITY % newAtt-d-dec PUBLIC
    "-//My Company//ENTITIES new Attribute Domain//EN" "newAttDomain.ent">
    %newAtt-d-dec;
Element extension redefinitions
For each element extended by one or more domains, the document type shell redefines the entity for the element to a list of alternatives including the literal name of the element and the element extension entity from each domain that is providing specializations.
<!ENTITY % pre
    "pre     | %pr-d-pre;     | %sw-d-pre;     | %ui-d-pre;">
For each attribute extended by one or more domains, the document type shell redefines the entity for the attribute to a list of alternatives including the literal name of the attribute and the attribute extension entity from each domain that is providing specializations. Attributes can only be specialized from props or base in DITA 1.1.
<!ENTITY % props-attribute-extensions
        "%newAtt-d-attribute; 
         %othernewAtt-d-attribute;">
<!ENTITY % base-attribute-extensions
        "%newfrombaseAtt-d-attribute; 
         %othernewfrombaseAtt-d-attribute;">
Topic nesting redefinitions
For each topic type, the document type shell can control nesting of subtopics by redefining the nested topics entity to the literal element name for any of the topics included in the document type. The document type shell can also simply define the info-types entity to set the default for most topic types. Here is an example:
<!ENTITY % concept-info-types "concept">
Domain declaration redefinition
The document type shell redefines the included-domains entity to list the domains included in the document type as in the following example:
<!ENTITY included-domains
    "&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att; &ut-d-att; &newAtt-d-att">
Structural definition inclusions
The document type shell includes the definitions for the structural type modules used in the document type. The entity for the structural definition consists of the structural type's name with the type suffix, as in the following example:
<!ENTITY % topic-type PUBLIC
    "-//OASIS//ELEMENTS DITA Topic//EN" "topic.mod">
    %topic-type;
Domain definition inclusions
The document type shell includes the domain definitions for the domains used in the document type. The entity for the domain definition consists of the domain name prefix with the def suffix, as in the following example:
<!ENTITY % hi-d-def PUBLIC
    "-//OASIS//ELEMENTS DITA Highlight Domain//EN" "highlightDomain.mod">
    %hi-d-def;
There are no domain definition files for attribute domains.

Return to main page.

OASIS DITA Architectural Specification v1.1 -- Committee Draft 02, 8 May 2007
Copyright © OASIS Open 2005, 2007. All Rights Reserved.