Re: [dita-comment] Remove or change emphasis of spec section on constraint compatibility?

["Jeremy H. Griffith" <jeremy@omsys.com>]

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/