Modularization in DTDs

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.

Parent topic: Specialization in design

Previous topic: Integration

Next topic: Modularization in schemas

Domain specialization pattern

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.

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.