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

[Michael Priestley <mpriestl@ca.ibm.com>]

Hi Jeremy,

>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.

The reason we didn't do this - with
domains as well - was because there's a very real difference between "this
reuse is valid at the time it was created" and "this reuse will
remain valid throughout a working authoring/editing lifecycle unless you
change doctypes".

By validating that the document types
provide equivalent constraints and markup capabilities, you can protect
yourself against last-minute edits that break your publishing pipeline.

If your publishing pipeline can't be
broken by the kinds of inclusion you're doing (in other words, it can tolerate
unconstrained content or markup from unincluded domains), then it makes
sense to turn that validation off.

But if your processing chain depends
on tight/specific markup, and will be broken by incoming markup that is
looser/unexpected, then validating compatibility of the document types
is much stronger and more reliable than validating compatibility of the
specific content at a single point in time (the time the reuse relationship
is created).

There are other ways to accomplish the
same kind of strong validation - for example, I can imagine setting up
a testing rule that says every time you change a reused element, you must
revalidate every reusing document - but the current DITA approach works
with distributed systems and with no dependency on special technologies
or even a CMS.

Again, I'm in favour of making "loose"
conref the default, and documenting that clearly in DITA 1.3, 

But changing to a model that only ever
checks content validity (ie that content is ok to reuse right here), and
never checks context validity (ie that markup relationship is always ok
to reuse, no matter what changes in its content) would sacrifice something
of real value: the ability to make valid reuse relationships that aren't
vulnerable to changes in the reused content.

Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25



From:      
 "Jeremy H. Griffith"
<jeremy@omsys.com>
To:      
 dita-comment@lists.oasis-open.org,

Cc:      
 Joe Pairman <joepairman@gmail.com>
Date:      
 12/16/2013 08:37 AM
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/

-- 
This publicly archived list offers a means to provide input to the
OASIS Darwin Information Typing Architecture (DITA) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: dita-comment-subscribe@lists.oasis-open.org
Unsubscribe: dita-comment-unsubscribe@lists.oasis-open.org
List help: dita-comment-help@lists.oasis-open.org
List archive: http://lists.oasis-open.org/archives/dita-comment/
Feedback License: http://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
Committee: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
Join OASIS: http://www.oasis-open.org/join/