OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Another somewhat technical DTD issue - nesting topics

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:

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

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:
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/)

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]