[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita-comment] Remove or change emphasis of spec section on constraint compatibility?
On Mon, 16 Dec 2013 15:26:04 +0800, Joe Pairman <joepairman@gmail.com> wrote: > >The constraints rules are intended to prevent (or at least discourage) the >transclusion of less-constrained content into a more-constrained context. The real purpose of that is to ensure that the document resulting from the resolution of the conrefs is still valid DITA. I don't see any other purpose. That's less restrictive than the spec requirement that the imported element have an equally or more constrained content model. For example, the imported content may be only text, even though the content model allows other elements. >This is supposed to apply on an element level; that is that a >less-constrained element should not be conreffed by a more-constrained one, >regardless of the content models of other elements in the document. I think the spec should state the real restriction, that the result must be valid DITA, and not impose arbitrary and often onerous requirements intended to enforce that result. It should be the responsibility of the author, not a rule for the processor. >However, the current section on checking for constraint compatibility >suggests that because it is impractical to check the content model of each >element, all the constraints applying to the document type as a whole >should be compared: >http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/constraintsGeneralize.html Extending that constraint rule to apply to the entire document containing the imported content just makes a bad situation worse. This is especially true because DITA currently lacks the concept of a "library", a repository for shared content which is never, itself, produced as a document, despite the obvious need for such a file type in a documentation system that supports and encourages the re-use of content. >This is not widely practiced, if at all. But if it *were* practiced, this >would prevent many groups' perfectly legal uses of conref (while the >section says that processors "can" or "may" compare constraints in this >way, the examples show that resolution is "prevented" rather than a warning >being created). According to Eliot Kimber's helpful reply on my DITA-Users >thread: >"The place where this tends to really surprise people is using generic >topics to hold content intended to be conreffed from less-generic topics." >(From >http://groups.yahoo.com/neo/groups/dita-users/conversations/topics/33538 , >where Julio Vazquez also made a useful reply regarding a common-sense >approach to this.) It surprises and confounds people by imposing a pointless restriction on the way they organize their work. >Another practical example where a document-level compatibility check would >cause problems is for our team, where we conreffing a keyword from another >topic type (that we use as a library topic) into a specialization of task. >The two topics have different domains applied. The concept topic is using >one constraint on CommonElements, and the specialized task topic is using a >different constraint on CommonElements (removing fig, simpletable, and >table). However, the keyword element itself is defined identically. Exactly the use case fr a "library" topic type, or, better, a library as a third kind of file, like a map or a topic. >All a document-level constraint compatibility check can do is tell you that >you *might* be conreffing a less-constrained element into a >more-constrained one. As such, the result of such a check should only ever >be a warning, not a blocking error as implied by the word "prevented" in >the spec. I would question whether document-level compatibility checks are >useful at all, and it seems that most toolmakers agree, as no-one seems to >know of a tool that actually implements this. We emphatically do not; in fact, we do not "enforce" the element content-model restriction. It's a job for a validator, not for a processor. >But if the suggestion of such >a check must be kept in the spec, I would suggest: > > 1. Describing the limitations of such a check > 2. Insisting that the strongest consequence of such a check should only > ever be a warning, not a blocking error which could prevent perfectly legal > and very common conref practices and hence limit interchange and increase > the overhead of purchasing and updating tools. Yes. We'd rather see the requirement removed entirely, but at the very least, it should be limited to warnings. >Thanks in advance for considering this! Yes indeed! -- Jeremy H. Griffith <jeremy@omsys.com> DITA2Go site: http://www.dita2go.com/
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]