Another somewhat technical DTD issue - nesting topics

["Robert D Anderson" <robander@us.ibm.com>]

I've found what I think is conflicting information in the 1.2 specification, regarding how topic nesting is controlled.

There is language in 1.2 that explicitly allows you to create a single module that has a specialized topic, along with required specialized child topics. That language is:

A topic vocabulary module must define exactly one top-level topic type. It may define additional topic types that are then allowed to occur as subordinate topics within the top-level topic. However, such subordinate topic types may not be used as the root elements of conforming DITA documents. For example, a given top-level topic type may require the use of subordinate topic types that would only ever be meaningful in the context of their containing type and thus would never be candidates for standalone authoring or aggregation via maps. In that case, the subordinate topic type may be declared in the module for the top-level topic type that uses it. However, in most cases, potential subordinate topics should be defined in their own vocabulary modules. [1]

To give an example, this means I could have a specialized topic that contains one main point, where each main point requires one or more child topics to provide backup information. This could be defined in one DTD/XSD/RNG module:
<mainPoint> <-- Topic specialization
  specialized title, body
  <backupContent> <-- Required child topic specialization
    specialized title, body
</mainPoint>
    
However, when that edge case was recognized and described in 1.2, the coding requirements were not updated. The coding requirements state that any topic specialization MUST control topic nesting using a variable parameter entity:

A topic type module must define an entity to specify default subordinate topics. The entity name must be the topic element name plus the -info-types suffix. For example, the info-types entity for the concept topic is concept-info-types. If the topic has default subordinate topics, this entity can default to a list of element entities. [2]

This rule means that you must create any topic specialization in a manner that allows others to use it; you must allow others to change what topics can be nested; even if you know that your topic is only meaningful with a required sub-topic, you must make that sub-topic optional, and you must do so in an indirect manner. 

This rule contradicts the bit I copied in from the first topic. If you MUST control nesting with a parameter entity, then you cannot create a mainPoint specialization with a required backupContent child topic. Both statements can't be true.

I understand why that rule was originally added. In the DITA 1.0 days, each specialized module was expected to be as portable / reusable as any DITA topic. Enforcing this rule ensures everybody code specializations to that goal. However ... we're left with conflicting rules. We say that when needed, you can nest topics using method Z; then we say that you must nest topics using method A, which does not allow Z. I don't think we can disallow the first method - which was explicitly allowed in 1.2 - so we have to relax the requirements in the second method.

My suggestion is to just change the "MUST" to "SHOULD" in the second rule - which still makes this the usual case, but allows for the first edge case. On the plus side, as long as somebody still follows all the other DITA coding rules, I cannot think of any problems that would result from this change.

[1] http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/vocabularymodules.html
[2] http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dtdTopicTypeCodingReq.html

Thanks -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)