DTD: Coding requirements for document-type shells

A DTD-based document-type shell is organized into sections; each section contains entity declarations that follow specific coding rules.

The DTD-based approach to configuration, specialization, and constraints relies heavily upon parameter entities. Several of the parameter entities that are declared in document type shells contain references to other parameter entities. Because parameter entities must be declared before they are used, the order of the sections in a DTD-based document-type shell is significant.

A DTD-based document-type shell contains the following sections:

  1. Topic [or map] entity declarations
  2. Domain constraint integration
  3. Domain entity declarations
  4. Domain attributes declarations
  5. Domain extensions
  6. Domain attribute extensions
  7. Topic nesting override
  8. Domains attribute override
  9. Content constraint integration
  10. Topic [or map] element integration
  11. Domain element integration

Each of the sections in a DTD-based document-type shell follows a pattern. These patterns help ensure that the shell follows XML parsing rules for DTDs; they also establish a modular design that simplifies creation of new document-type shells. By convention, an .ent file extension is used to indicate files that define only parameter entities, while a .mod file extension is used to indicate files that define elements or constraints.

Topic [or map] entity declarations

This section declares and references an external parameter entity for each of the following:

  • The top-level topic or map type that the document-type shell configures
  • Any additional structural modules that are used by the document type shell

Each parameter entity (.ent) file contributes a domain token for structural topics or maps. The parameter entity is named type-name-dec.

For example, a document-type shell that integrates the <concept> specialization would include:
<!ENTITY % concept-dec     
  PUBLIC "-//OASIS//ENTITIES DITA 1.3 Concept//EN" 
         "concept.ent"
>%concept-dec;
Domain constraint integration

For each domain constraint module that is integrated into the document type shell, this section declares a parameter entity and references the constraint module file where the constraint is defined. The parameter entity is named descriptorDomainName-c-dec.

In the following example, the entity file for a constraint module that reduces the highlighting domain to a subset is included in a document type shell:
<!-- ============================================================= -->
<!--                    DOMAIN CONSTRAINT INTEGRATION              -->
<!-- ============================================================= -->

<!ENTITY % HighlightingDomain-c-dec  
  PUBLIC "-//ACME//ENTITIES DITA Highlighting Domain Constraint//EN" 
  "acme-HighlightingDomainConstraint.mod"
>%basic-HighlightingDomain-c-dec;
Domain entity declarations

For each element domain that is integrated into the document-type shell, this section declares a parameter entity and references the external entities file where the element domain is defined. The parameter entity is named shortDomainName-dec.

In the following example, the entity file for the highlighting domain is included in a document-type shell:
<!ENTITY % hi-d-dec PUBLIC
    "-//OASIS//ENTITIES DITA Highlight Domain//EN" 
    "highlightDomain.ent"
>%hi-d-dec;
Domain attributes declarations

For each attribute domain that is integrated into the document-type shell, this section declares a parameter entity and references the external entities file where the attribute domain is defined. The parameter entity is named domainName-dec.

In the following example, the entity file for the @deliveryTarget attribute domain is included in a document-type shell:
<!ENTITY % deliveryTargetAtt-d-dec
  PUBLIC "-//OASIS//ENTITIES DITA 1.3 Delivery Target Attribute Domain//EN"
         "deliveryTargetAttDomain.ent"
>%deliveryTargetAtt-d-dec;
Domain extensions

For each element that is extended by one or more domains, this section redefines the parameter entity for the element. These entities are used by later modules to define content models; redefining the entity adds domain specializations wherever the base element is allowed.

In the following example, the entity for the <pre> element is redefined to add specializations from the programming, software, and user interface domains:
<!ENTITY % pre
    "pre        | 
     %pr-d-pre; | 
     %sw-d-pre; | 
     %ui-d-pre;">
Domain attribute extensions

For each attribute domain that is integrated into the document-type shell, this section redefines the parameter entities for the attribute. It adds an extension to the parameter entity for the relevant attribute.

In the following example, the @props attribute is specialized to create the @new and @othernew attributes, while the @base attribute is specialized to create @newfrombase and @othernewfrombase attributes:
<!ENTITY % props-attribute-extensions
        "%newAtt-d-attribute; 
         %othernewAtt-d-attribute;">
<!ENTITY % base-attribute-extensions
        "%newfrombaseAtt-d-attribute; 
         %othernewfrombaseAtt-d-attribute;">
Topic nesting override

For each topic type that is integrated into the document-type shell, this section specifies whether and how subtopics nest by redefining the topictype-info-types entity. The definition is usually an OR list of the topic types that can be nested in the parent topic type. Use the literal root-element name, not the corresponding parameter entity. Topic nesting can be disallowed completely by specifying the <no-topic-nesting> element.

In the following example, the parameter entity specifies that <concept> can nest any number of <concept> or <myTopicType> topics, in any order:
<!ENTITY % concept-info-types "concept | myTopicType">
Domains attribute override

This section sets the effective value of the @domains attribute for the top-level document type that is configured by the document type shell. It redefines the included-domains entity to include the text entity for each domain, constraint, and structural specialization that is either included or reused in the document type shell.

In the following example, entities are included for both the troubleshooting specialization and the task specialization on which the troubleshooting specialization depends; for the highlighting and utilities element domains; for the newAtt-d attribute domain, and for the noBasePre-c constraint module:
<!ENTITY included-domains
    "&troubleshooting-att;
     &task-att;
     &hi-d-att; 
     &ut-d-att; 
     &newAtt-d-att;
     &noBasePre-c-ph;
   "
>
Note: Although parameter entities (entities that begin with "%") must be defined before they are referenced, text entities (entities that begin with "&") can be referenced before they are defined. This allows the included-domains entity to include the constraint entity, which is not defined until the constraint module is referenced later in the document type shell.
Content constraint integration

For each constraint module that is integrated into the document-type shell, this section declares and references the external module file where the constraint is defined. The parameter entity is named constraintName-c-def.

In the following example, the constraint module that constrains the content model for the <taskbody> element is integrated into the document-type shell for strict task:
<!ENTITY % strictTaskbody-c-def  
  PUBLIC "-//OASIS//ELEMENTS DITA 1.3 Strict Taskbody Constraint//EN" 
  "strictTaskbodyConstraint.mod"
>%strictTaskbody-c-def;
Topic [or map] element integration

For each structural module that is integrated into the document-type shell, this section declares a parameter entity and references the external module file where the structural module is defined. The parameter entity is named structuralType-type. The modules must be included in ancestry order, so that the parameter entities that are used in an ancestor module are available for use in specializations. When a structural module depends on elements from a vocabulary module that is not part of its ancestry, the module upon which the structural module has a dependency (and any ancestor modules not already included) should be included before the module with a dependency.

The following example declares and references the structural modules that are integrated into the document-type shell for troubleshooting:
<!ENTITY % topic-type
  PUBLIC "-//OASIS//ELEMENTS DITA 1.3 Topic//EN"
         "../../base/dtd/topic.mod"
>%topic-type;

<!ENTITY % task-type
  PUBLIC "-//OASIS//ELEMENTS DITA 1.3 Task//EN"
         "task.mod"
>%task-type;

<!ENTITY % troubleshooting-type
  PUBLIC "-//OASIS//ELEMENTS DITA 1.3 Troubleshooting//EN"
         "troubleshooting.mod"
>%troubleshooting-type;
Domain element integration

For each element domain that is integrated into the document-type shell, this section declares a parameter entity and references the external module file where the element domain is defined. The parameter entity is named domainName-def.

For example, the following code declares and references the parameter entity used for the highlighting domain:
<!ENTITY % hi-d-def PUBLIC
    "-//OASIS//ELEMENTS DITA Highlight Domain//EN" 
    "highlightDomain.mod"
>%hi-d-def;
Note: If a structural module depends on a domain, the domain module should be included before the structural module. This erases the boundary between the final two sections, but it is necessary to ensure that modules are embedded after their dependencies. Technically, the only solid requirement is that both domain and structural modules be declared after all other modules that they specialize from or depend on.