Re: [dita] Another somewhat technical DTD issue - nesting topics

[Eliot Kimber <ekimber@contrext.com>]

I agree--SHOULD rather than MUST.

The intent of the first part you quote was simply to make it explicitly
allowed to have non-standalone topic types definable within a standalone
topic type module and of course for those topics you likely don't want to
allow any topics to nest within them.

More generally spec should *really* say that topic types can configure the
base topic nesting any way they want, but if the intent to allow complete
configuration through document type shells, then topics SHOULD use the
*-info-types approach for consistency and ease of configuration. I don't
know if we can make that big of a change in 1.3.

Fundamentally, the only real requirement is that the grammar can only
allow topics where the base model for <topic> allows topics--how you go
about defining that content model in your grammar doesn't really matter.
The extension conventions are there for consistency and convenience.
Clearly we we over expressed our desire to encourage/ensure consistency of
implementation.

Cheers,

E.
—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 2/23/15, 4:54 PM, "Robert D Anderson" <robander@us.ibm.com> wrote:

>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.ht
>ml
>[2] 
>http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dtdTopicTypeCodingRe
>q.html
>
>Thanks -
>
>Robert D Anderson
>IBM Authoring Tools Development
>Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)