Modularization in DTDs

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 #FIXED "&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.

Each domain specialization must have two files:

• A DTD entity declaration file with a name consisting of the domain name and the ent extension.
• A DTD definition module with a name consisting of the domain name and the mod extension.

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

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 example:

<!ENTITY % hi-d-dec PUBLIC
    "-//OASIS//ENTITIES DITA Highlight Domain//EN" "highlightDomain.ent">
    %hi-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;">

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;">

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;