Why There are Constraints on Conref

[ekimber <ekimber@reallysi.com>]

The recent discussion around ditabase and the various task configurations
suggests that we need more public discussion of why DITA imposes what may at
first appear to be draconian constraints on conref.

I think it's important to understand that there are several different use
cases in which constraints are or are not important, but that, overall, the
constraints are necessary in order for DITA content to be both interoperable
and interchangeable.

In the case of processing, for the most part, conref constraints are not
relevant, because most, if not all processors, will be able to process any
valid DITA elements, in any combination, constrained or not. That means, for
example, that a constrained topic referencing content from an unconstrained
topic wouldn't normally cause problems for processors. I suspect this is the
way most DITA users think about the implications of conref constraints.

[Note: This is not the same as allowing specialized elements to conref
unspecialized content--that's a different issue and allowing that *would*
break processors, because specializations may establish specific contracts
for what they can contain and how they need to be processed. The textbook
example is <step>, which specializes <li> but does not, and could not
meaningfully, include everything allowed in <li> (which is just about
everything.]

However, there *could* be processors that are specifically designed to only
handle elements allowed in some constrained set of models and of course
those processors would not be able to handle the constraint mismatch case.

In the case of authoring, there are two primary concerns:

1. Consistency of imposed rules
2. Supporting editors that need to literally copy conreffed content in order
to show resolved conrefs or validate the effective result.

Item 1 is about business rules expressed through constraints: the
presumption is that those rules are there for a reason and it would be
inappropriate, if not counter productive, to allow the use of content that
doesn't reflect the constraints, because such content would violate
editorial or business rules. DITA provides a powerful mechanism for
expressing local structuring rules with a minimum of effort and cost. If
you've taken the trouble to use it you have a reasonable expectation that
your decisions will be enforced.

Item 2 is about practical implementation of DITA support. In theory, editors
could be designed so that they could validate or render any conrefs without
regard to the DTD validity of the resolved result. But in practice most, if
not all, XML editors were not designed that way. Thus they need to have the
conref result be DTD valid so that they can, for example, show the resolved
conref result inline in the editor or validate the conref itself.

In the case of interchange, there is the matter of surprise--even if, in
your local environment, your processors and editors could handle constraint
mismatches, your interchange partners' tools might not. So you must ensure
consistency and validity for the purpose of interchange.

For the 2nd review I added a topic to the Intro to DITA section specifically
on module usage consistency and domain usage comparison, which is what we're
talking about here.

It's also important to understand that DITA's module consistency rules and
the mechanism for checking them is unique among XML applications for
documentation--it is a key aspect of DITA's ability to support true blind
interchange in a way that no other XML or SGML application ever has. It is
the enabling of blind interchange of DITA content that truly distinguishes
DITA from all other XML applications for human-readable documents.

Cheers,

E.

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>