2.1.4.3.8.1.1 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

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

<!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.

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

<!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.

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

<!ELEMENT topichead    %topichead.content;>

<!ATTLIST topichead    %topichead.attributes;>

<!--                    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

The attributes of an element type must restrict or conserve those of the element type it specializes. Specialized element types may not add new attributes. New global attributes may be defined via attribute domain modules. Structural modules may require the use of attribute domain modules.

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.