DTD document-type shell: Coding requirements

DTD document type shells may not directly declare element types or attributes. A DTD document type shell must conform to the following coding requirements.

Each section of the shell is introduced by a comment. Shells should use these comments to identify each section of the shell. Each section should be present in the shell DTD, even if the section contains no declarations, and must occur in the order they are presented here. The ordering is required by the XML rules for entity declaration precedence and also serve to enable automatic shell creation and modification. Shells should have an initial set of comments that describe the shell and indicate the public identifiers, URNs, or absolute URLs by which the shell should be referenced in DOCTYPE declarations.

Topic or map entity inclusions

The topic or map entity declarations section includes the .ent file for the top-level topic or map type the shell is configuring.

Topic shells should use the comment:

<!-- ============================================================= -->
<!--                    TOPIC ENTITY DECLARATIONS                  -->
<!-- ============================================================= -->  

Map shells should use the comment:

<!-- ============================================================= -->
<!--                    MAP ENTITY DECLARATIONS                    -->
<!-- ============================================================= -->

This section must declare and reference as an external parameter entity the .ent file for the topic or map module where the entity is named %typename-dec. For example:

<!ENTITY % concept-dec     
  PUBLIC "-//OASIS//ENTITIES DITA 1.2 Concept//EN" 
         "concept.ent"
>%concept-dec;

Domain entity inclusions

The domain entity inclusions section includes the entity declaration files for each element domain integrated by the document type. This section should use the comment:

<!-- ============================================================= -->
<!--                    DOMAIN ENTITY DECLARATIONS                 -->
<!-- ============================================================= -->

For each element domain included in the shell, this section must declare an external parameter entity for the domain's entity declaration file and immediately reference the entity. The entity name for the domain declaration consists of the domain name plus the dec suffix. In the following example, the entity file for the highlight domain is included in the document type shell:

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

Domain attribute inclusions

The domain attribute inclusions section includes the entity declaration files for each attribute domain integrated by the document type. This section should use the comment:

<!-- ============================================================= -->
<!--                    DOMAIN ATTRIBUTE DECLARATIONS              -->
<!-- ============================================================= -->

For each attribute domain included in the shell, this section must declare an external parameter entity for the domain's entity declaration file and immediately reference the entity. The entity name for the domain declaration consists of the domain name plus the ent suffix. In the following example, the entity file for a new attribute domain is included in the document type shell:

<!ENTITY % newAtt-d-dec PUBLIC
    "-//My Company//ENTITIES New Attribute Domain//EN"
    "newAttDomain.ent"
>%newAtt-d-dec;

Element extension redefinitions

The element extension redefinition section contains redefinitions of element name parameter entities to reflect the integration of domain-provided element types into base content models. This section should use the comment:

<!-- ============================================================= -->
<!--                    DOMAIN EXTENSIONS                          -->
<!-- ============================================================= -->

For each element that is extended by one or more domains, the document type shell redefines the entity for the element. The new definition is a disjunctive list of alternatives comprising the literal name of the element followed by the element extension entity from each domain that is providing specializations. In the following example, the entity for the <pre> element is redefined to allow specializations from the programming, software, and user interface domains:

<!ENTITY % pre
    "pre        | 
     %pr-d-pre; | 
     %sw-d-pre; | 
     %ui-d-pre;">

The value of the entity may omit any base types from which other types listed are specialized. For example, the preceding example could omit the <pre> element, effectively allowing only specializations of <pre>, but not <pre> itself:

<!ENTITY % pre
    "%pr-d-pre; | 
     %sw-d-pre; | 
     %ui-d-pre;">

note

Omitting base types from domain extensions constitutes a form of constraint. The constraint must be represented by a constraint module that declares the @domains attribute declaration for the constraint. For the omission of <pre> in the preceding example the constraint might be called "noBasePre-c" and would be declared in a file named "noBasePreConstraint.mod", containing the following declarations:

<!ENTITY noBasePre-c-pre  "%pr-d-pre; | %sw-d-pre; | %ui-d-pre;">
<!ENTITY noBasePre-c-att  "(topic noBasePre-c)" >
<!ENTITY % pre          “%noBasePre-c-pre ;“>

Attribute extension redefinitions

The attribute extension redefinition section integrates the declarations of specializations of the base and props attributes (defined in attribute domain modules included in the attribute domain inclusion section). This section must use the comment:

<!-- ============================================================= -->
<!--                    DOMAIN ATTRIBUTE EXTENSIONS                -->
<!-- ============================================================= -->

The entities for extending the props and base attributes have a null value by default:

<!ENTITY % props-attribute-extensions  "" >
<!ENTITY % base-attribute-extensions   "" >

For each attribute domain included by the shell, the shell must redefine the entity that is extended. The new definition is a list of the attribute extension entities for the domains that are providing specializations.

<!ENTITY % props-attribute-extensions
        "%newAtt-d-attribute; 
         %othernewAtt-d-attribute;">
<!ENTITY % base-attribute-extensions
        "%newfrombaseAtt-d-attribute; 
         %othernewfrombaseAtt-d-attribute;">

Topic nesting redefinitions

The topic nesting section contains redefinitions of the topic nesting control parameter entities defined by the topic modules integrated in the shell. This section should use the comment:

<!-- ============================================================= -->
<!--                    TOPIC NESTING OVERRIDES                    -->
<!-- ============================================================= -->

For each topic type integrated in the shell, the document type shell may control nesting of subtopics by redefining the topictype-info-types entity. The definition is usually an OR list of topic types that can be nested in the corresponding parent topic type. Use the literal root element name of each topic, not the corresponding element entity, as in the following example:

<!ENTITY % concept-info-types "concept | myTopicType">

The document type shell may also set the default for most topic types by defining the global info-types entity, for example:

<!ENTITY % info-types "concept | myTopicType">

Domain declaration redefinition

The domain declaration redefinition section sets the effective value of the @domains attribute for the topic or map type modules integrated into the shell. This section should use the comment:

<!-- ============================================================= -->
<!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
<!-- ============================================================= -->

The document type shell must redefine the included-domains entity to list the domains for specializations that are included in the document type, as well as any constraint modules, as in the following example:

<!ENTITY included-domains
    "&hi-d-att; 
     &ut-d-att; 
     &ui-d-att; 
     &pr-d-att; 
     &sw-d-att; 
     &newAtt-d-att;
     &noBasePre-c-ph;
   "
>

For a domain or structural module, the domains attribute value entity is declared in the domain's .ent file. For constraint modules, the domains attribute value entity is declared in the module's .mod file constraint modules do not use separate .ent files).

Content constraint module inclusions

The content constraint module inclusion section includes constraint modules that override the base content models for structural or domain types integrated in the shell. This section should use the comment:

<!-- ============================================================= -->
<!--                    CONTENT CONSTRAINT INTEGRATION             -->
<!-- ============================================================= -->

For each constraint module integrated in the shell, the shell must declare an external parameter entity for the constraint's .mod file and immediately reference the entity. The entity name for the constraint declaration consists of the constraint module name plus the -c-mod suffix. For example, this constraint inclusion for the task topic type constrains the DITA 1.2 relaxed task content model to match the more constrained DITA 1.1 task content model:

<!ENTITY % strictTaskbody-c-def  
  PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Strict Taskbody Constraint//EN" 
  "strictTaskbodyConstraint.mod"
>%strictTaskbody-c-def;

Structural definition inclusions

The structural definition inclusion section includes the element type declaration (.mod) files for each topic or map type integrated into the shell. For topic shells, this section should use the comment:

<!-- ============================================================= -->
<!--                    TOPIC ELEMENT INTEGRATION                  -->
<!-- ============================================================= -->

For map shells, this section should use the comment:

<!-- ============================================================= -->
<!--                    MAP ELEMENT INTEGRATION                    -->
<!-- ============================================================= -->

For each structural type integrated in the document type, the document type shell must declare and reference an external parameter entity for the structural type module's .mod file. The entity name consists of the name of the structural type plus a -type suffix. For example:

<!ENTITY % topic-type PUBLIC
    "-//OASIS//ELEMENTS DITA Topic//EN" 
    "topic.mod"
>%topic-type;

Element domain definition inclusions

The element domain definition inclusion section includes the element definition files for each element domain integrated into the shell. This section should use the comment:

<!-- ============================================================= -->
<!--                    DOMAIN ELEMENT INTEGRATION                 -->
<!-- ============================================================= -->

For each element domain used in the document type, the document type shell must declare and reference an external parameter entity for the domain definition module file (.mod). The entity name consists of the domain name plus a -def suffix. For example:

<!ENTITY % hi-d-def PUBLIC
    "-//OASIS//ELEMENTS DITA Highlight Domain//EN" 
    "highlightDomain.mod"
>%hi-d-def;