General element type declaration coding requirements

Module names

Each vocabulary module has a short name that is used to construct file names, entity names, and other names used in associated declarations. Modules may also have abbreviated names that further shorten the short name, for example "sw" for the "software" domain, where "software" is the short name and "sw" is the abbreviated name.

For structural modules, the module name must be the element type name of the top-level topic or map type defined by the module, such as "concept", "bookmap".

For element domain modules, the module name must be a name that reflects the subject domain to which the domain applies, such as "highlight", "software". Domain module names should be sufficiently unique that they are unlikely to conflict with any other domains.

Module files

A structural or element domain vocabulary module must have two files:

• A module entity declaration file, which declares the entities used to integrate the module into a shell DTD.

  For structural modules, the file name is the module name plus the ent extension, e.g. concept.ent.

  For domain modules, the file name is the domain name plus Domain plus the ent extension, e.g. highlightDomain.ent, newAttDomain.ent.

• A definition module, which contains the element type and/or attribute list declarations for the module.

  For structural modules, the file name is the module name plus the mod extension, e.g., concept.mod

  For domain modules, the file name is the domain name plus "Domain" and the mod extension, e.g., highlightDomain.mod, newAttDomain.mod.

Domain declaration entity

The domain declaration entity must conform to the following implementation pattern:

The declaration file must define an entity that associates the domain with a module. The name of the entity is the structure type name or domain abbreviation plus the -att suffix, e.g. "concept-att", "hi-d-att".

The value of the entity must list the dependencies of the domain module in order of dependency from left to right within enclosing parentheses, starting with the topic module. Domain abbreviations are used in the list, and the defining domain is the last item in the list. The following example declares the dependency of the highlight domain on the base topic module.

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

The domain declaration entity is used to construct the effective value of the domains attribute for a map or topic type as configured in a shell DTD.

Element definitions

A structural or domain vocabulary module must contain a declaration for each specialized element type named by the module. While the XML standard allows content models to refer to undeclared element types, all element types named in content models or attribute list declarations within a vocabulary module must have an ELEMENT declaration, in one of:

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

The specialized elements must follow the rules of the architecture in defining content models and attributes.

For each element type declared in the vocabulary module there must be an element name parameter entity whose default value is the name of the element, e.g.:

<!ENTITY % conbody "conbody">

The element name entity provides a layer of abstraction that facilitates redefinition. A document type shell can predefine an element entity to add domain-specialized elements or replace a base element type with one or more specializations of that type. Because declarations use the entity rather than the element type name to include the element in a content model, the redefinition given in a shell is propagated to every context in which the base element occurs.

The element name parameter entities must be grouped together at the top of the vocabulary module before any other declarations to ensure they are declared before any use in content models declared in the same module. The declarations may occur in any order. By convention, they are usually ordered alphabetically or grouped logically.

For each element type, the content model and attribute list declarations should start with a descriptive comment. For example:

<!--                    LONG NAME: Topic Head                      -->

Each element type must have a corresponding content model parameter entity named %tagname.content. The value of the entity must be the complete content model definition. For example:

<!ENTITY % topichead.content
  "((%topicmeta;)?, 
    (%anchor; | 
     %data.elements.incl; | 
     %navref; | 
     %topicref;)*)
">

The content model parameter entity may be overridden in shell DTDs or constraint modules to further constrain the content model for the element type.

Each element type must have a corresponding attribute list parameter entity named %tagname.attributes. The parameter entity must declare all attributes used by the element type (except for the attributes provided by the %global-atts; parameter entity, which is always referenced as part of the attribute list declaration for an element's class attribute). For example:

<!ENTITY % topichead.attributes
 "navtitle 
     CDATA 
          #IMPLIED
   outputclass 
     CDATA 
          #IMPLIED
   keys 
     CDATA 
          #IMPLIED
   %topicref-atts;
   %univ-atts;"
>

The ELEMENT declaration for each element type must consist entirely of a reference to the corresponding content model parameter entity:

<!ELEMENT topichead    %topichead.content;>

The ATTLIST declaration for each element type must consist entirely of a reference to the corresponding attribute list parameter entity:

<!ATTLIST topichead    %topichead.attributes;>

The content model parameter entity, attribute list parameter entity, ELEMENT declaration, and ATTLIST declaration should be grouped together within the module. Each such group of declarations may occur in any order within the module. For example:

<!--                    LONG NAME: Topic Head                      -->
<!ENTITY % topichead.content
  "((%topicmeta;)?, 
    (%anchor; | 
     %data.elements.incl; | 
     %navref; | 
     %topicref;)* )
">
<!ENTITY % topichead.attributes
  "navtitle 
      CDATA 
          #IMPLIED
   outputclass 
      CDATA 
           #IMPLIED
   keys 
      CDATA 
          #IMPLIED
   %topicref-atts;
   %univ-atts;"
>
<!ELEMENT topichead    %topichead.content;>
<!ATTLIST topichead    %topichead.attributes;>

Attributes

A vocabulary module must define a @class attribute for every specialized element declared in the module. The @class attribute must include the value of the @class attribute of the base element, and append to it the element name qualified by the topic element name with at least one leading and trailing space. The @class attribute for an element introduced by a structural specialization must start with a minus sign ("-"). The @class attribute for a domain specialization must start with a plus sign ("+"). The initial minus or plus sign must be followed by one or more spaces. The attribute value must end with one or more trailing spaces.

The ATTLIST declaration for the @class attribute must also include a reference to the %global-atts parameter entity.

For example, the ATTLIST definition for the <conbody> element (a specialization of the <body> element in the <topic> base type) includes global attributes with an entity, then the definition of the @class attribute, as follows:

<!ATTLIST conbody     %global-atts;  class CDATA "- topic/body  concept/conbody ">

The @class attribute declarations for a module must be grouped together at the end of the module after any other declarations. The declarations may occur in any order. By convention they are often ordered alphabetically or grouped logically.

See Element type specialization hierarchy declaration (the @class attribute) for complete details on the @class attribute.