DTD: Overview of coding requirements

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition
Version
1.3
Author
OASIS DITA Technical Committee

DITA coding practices for DTDs rely heavily on entities to implement specialization and constrraints. As such, an understanding of entities is critical when working with DTD document-type shells, vocabulary modules, or constraint modules.

Entities can be defined multiple times within a single document type, but only the first definition is effective. How entities work shapes DTD coding practices. The following list describes a few of the more important entities that are used in DITA DTDs:

Elements defined as entities
In DITA DTDs, every element is defined as an entity. When elements are added to a content model, they are added using the entity. This enables extension with domain specializations. For example, the entity %ph; usually just means "the ph element", but can be (pre)defined in a document-type shell to mean "ph plus several elements from the highlighting domain". Because the document-type shell places that entity definition before the usual definition, every element that included %ph; in its content model now includes ph plus every phrase specialization in the highlighting domain.
Content models defined as entities
Every element in a DITA DTD defines its content model using an entity. For example, rather than directly setting what is allowed in ph, that element sets its content model to %ph.content;; that entity defines the actual content model. This is done to enable constraints; a constraint module can (pre)define the %ph.content; model to remove selected elements.
Attribute sets defined as entities
Every element in a DITA DTD defines its attribute using an entity. For example, rather than directly defining attributes for ph, that element sets its attributes using the %ph.attributes; entity; that entity defines the actual attributes. As above, this is done to enable constraints; a constraint module can (pre)define the %ph.attributes; model to remove selected attributes.
Note: When constructing a constraint module or document-type shell, new entities are usually viewed as "redefinitions" because they redefine entities that already exist. However, these new definitions only work because they are added to a document-type shell before the existing definitions, which is why they are described here as (pre)definitions. Most topics about DITA DTDs, including others in this specification, will describe these overrides as redefinitions to ease understanding.