DTD: Coding requirements for structural modules

Required topic and map element attributes

The topic or map element type must set the @DITAArchVersion attribute to the version of DITA in use, typically by referencing the arch-atts parameter entity. It must also set the @domains attribute to the included-domains entity. These attributes give processors a reliable way to check the architecture version and look up the list of domains available in the document type.

The following example shows how these attributes are defined for the <concept> element in DITA 1.3:

<!ATTLIST concept    
  %concept.attributes;
  %arch-atts;
  domains  CDATA  "&included-domains;">

Controlling nesting in topic types

Specialized topics typically use a parameter entity to define what topic types are permitted to nest. While there are known exceptions described below, the following rules apply when using parameter entities to control nesting.

Parameter entity name

The name of the parameter entity is the topic element name plus the -info-types suffix.

For example, the name of the parameter entity for the concept topic is concept-info-types.

Parameter entity value

To set up default topic nesting rules, set the entity to the desired topic elements. The default topic nesting will be used when a document-type shell does not set up different rules.

For example, the following parameter entity sets up default nesting so that <concept> will nest only other <concept> topics:

<!ENTITY % concept-info-types "%concept;">

As an additional example, the following parameter entity sets up a default that will not allow any nesting:

<!ENTITY % glossentry-info-types "no-topic-nesting">

Default topic nesting in a structural module often set up to use the %info-types; parameter entity rather than using a specific element. When this is done consistently, a shell that includes multiple structural modules can set common nesting rules for all topic types by setting %info-types; entity. The following example shows a structural module that uses %info-types; for default topic nesting:

<!ENTITY % concept-info-types "%info-types;">

Content model of the root element

The last position in the content model defined for the root element of a topic type SHOULD be the topictype-info-types parameter entity. A document-type shell then can control how topics are allowed to nest for this specific topic type by redefining the topictype-info-types entity for each topic type. If default nesting rules reference the info-types parameter entity, a shell can efficiently create common nesting rules by redefining the info-types entity.

For example, with the following content model defined for <concept>, a document-type shell that uses the concept specialization can control which topics are nested in <concept> by redefining the concept-info-types parameter entity:

<!ENTITY % concept.content
  "((%title;), 
    (%titlealts;)?,
    (%abstract; | %shortdesc;)?, 
    (%prolog;)?, 
    (%conbody;)?, 
    (%related-links;)?,
    (%concept-info-types;)*)"
>

In rare cases, it might not be desirable to control topic nesting with a parameter entity. For example:

• If a specialized topic type should never allow any nested topics, regardless of context, it can be defined without any entity or any nested topics.
• If a specialized topic type should only ever allow specific nesting patterns, such as allowing only other topic types that are defined in the same module, it can nest those topics directly in the same way that other nested elements are defined.