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: Re: [dita] Another somewhat technical DTD issue - nesting topics

I agree ‹ SHOULD.

By loosening this requirement, it should not affect backward compatibility


On 2/23/15, 4:15 PM, "Eliot Kimber" <ekimber@contrext.com> wrote:

>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
>Eliot Kimber, Owner
>Contrext, LLC
>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
>>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
>>     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.
>>Thanks -
>>Robert D Anderson
>>IBM Authoring Tools Development
>>Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
>To unsubscribe from this mail list, you must leave the OASIS TC that
>generates this mail.  Follow this link to all your TCs in OASIS at:

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