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:
-
Topic [or map] entity declarations
-
Domain constraint integration
- Domain entity declarations
-
Domain attributes declarations
-
Domain extensions
-
Domain attribute extensions
-
Topic nesting override
-
Domains attribute override
-
Content constraint integration
-
Topic [or map] element integration
-
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.