[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 either. ‹Scott 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 >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.h >>t >>ml >>[2] >>http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/dtdTopicTypeCodingR >>e >>q.html >> >>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: >https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]