DTD: Coding requirements for element type declarations

This topic covers general coding requirements for defining element types in both structural and element-domain vocabulary modules. In addition, it covers how to create the @domains attribute contribution for these modules.

A vocabulary module that defines a structural or element domain specialization is composed of two files:

  • An entity declaration (.ent) file, which declares the text entities that are used to integrate the vocabulary module into a document-type shell
  • A definition module (.mod) file, which declares the element names, content models, and attribute lists for the element types that are defined in the vocabulary module

@domains attribute contribution

A domain declaration entity is used to construct the effective value of the @domains attribute for a map or topic type.

Text entity name

The name of the text entity is the structural type name or the domain abbreviation, followed by a hyphen ("-") and the literal att.

Text entity values

The value of the text entity is the @domains attribute contribution for the current module. See domains attribute rules and syntax for details on how to construct this value.

For example, the @domains attribute contributions for the concept structural module and the highlighting domain module are are constructed as follows.

  • <!ENTITY concept-att "(topic concept)">
  • <!ENTITY hi-d-att "(topic hi-d)">.

Element definitions

A structural or domain vocabulary module must contain a declaration for each element type that is named by the module. While the XML standard allows content models to refer to undeclared element types, the DITA standard does not permit this. All element types or attribute lists that are named within a vocabulary module must be declared in one of the following objects:

  • The vocabulary module
  • A base module of which the vocabulary module is a direct or indirect specialization
  • (If the vocabulary module is a structural module) A required domain module

The following components make up a single element definition in a DITA DTD-based vocabulary module.

Element name entities

For each element type, there must be a parameter entity with a name that matches the element type name. The default value is the element type name. This parameter entity provides a layer of abstraction when setting up content models; it can be redefined in a document-type shell in order to create domain extensions or constraints. Element name entities for a single vocabulary module are typically grouped together at the top of the vocabulary module.

For example: <!ENTITY % topichead "topichead">

Content-model parameter entity

For each element type, there must be a parameter entity that defines the content model. The name of the parameter entity is tagname.content, and the value is the content model definition. Consistent use and naming of the tagname.content parameter entity enables the use of constraint modules to restrict the content model.

For example:
<!ENTITY % topichead.content
  "((%topicmeta;)?, 
    (%anchor; | 
     %data.elements.incl; | 
     %navref; | 
     %topicref;)*)
">
Attribute-list parameter entity

For each element type, there must be a parameter entity that declares the attributes that are available on the element. The name of the parameter entity is tagname.attributes, and the value is a list of the attributes that are used by the element type (except for @class and the attributes provided by the global-atts parameter entity). Consistent use and naming of the tagname.attributes parameter entity enables the use of constraint modules to restrict attributes.

For example:
<!ENTITY % topichead.attributes
 "navtitle CDATA #IMPLIED
  outputclass CDATA #IMPLIED
  keys CDATA #IMPLIED
  copy-to CDATA #IMPLIED
  %topicref-atts;
  %univ-atts;"
>
Element declaration

For each element type, there must be an element declaration that consists of a reference to the content-model parameter entity.

For example:
<!ELEMENT topichead    %topichead.content;>
Attribute list declaration

For each element type, there must be an attribute list declaration that consists of a reference to the attribute-list parameter entity.

For example:
<!ATTLIST topichead    %topichead.attributes;>
Specialization attribute declarations

A vocabulary module must define a @class attribute for every element that is declared in the module. The value of the attribute is constructed according to the rules in class attribute rules and syntax. The ATTLIST declaration for the @class attribute should also include a reference to the global-atts parameter entity.

For example, the ATTLIST definition for the <topichead> element (a specialization of the <topicref> element in the base map type) includes global attributes with an entity, then the definition of the @class attribute, as follows:
<!ATTLIST topichead  %global-atts;  class CDATA "+ map/topicref  mapgroup-d/topichead ">