Re: [dita] Why There are Constraints on Conref

[ekimber <ekimber@reallysi.com>]

On 9/25/09 5:53 PM, "ekimber" <ekimber@reallysi.com> wrote:

> Give a strict task and a general task:
> 
> 1. Can conref elements from strict task into general task
> 2. Cannot conref elements from general task into strict task
> 
> That is, you can *always* conref more-constrained elements into
> less-constrained elements. You can *never* conref less-constrained elements
> into more-constrained elements.

I realized that I was getting personally confused by two distinct cases and
I wanted to make sure we were all clear.

Say we have two docs: doc-01 and doc-02.

For a conref from element A in doc-01 to element B in doc-02, there are two
levels of check to be made:

Check 1: Is element B the same type, or more specialized type, as element A?

If B is the same type as or more specialized than A, then the conref *might*
be allowed, pending check 2. If B is less specialized than A or is not in
the same type hierarchy, the conref cannot be allowed at all (e.g., you
cannot conref from <p> to <table> under any circumstances).

Check 2: If check 1 succeeds, compare the set of constraints used by
documents doc-01 and doc-02.

"Checking the constraints" means, for each vocabulary module used in the
referencing document, check to see if the target document uses the same
module. For each shared module, if the referencing document has an
associated constraint domain for that module, the target document must use
the same constraint domain.

If the referencing document uses a module and constrains it and the target
document does not use that module at all, then conref is allowed because the
target document cannot include elements of the constrained type (meaning
that a constrained type in the referencing document only has available to it
less-specialized elements in target document, and in that case, conref from
the more-specialized elements is never allowed, so it's not an issue that
the module used only by the referencing element is constrained) [brain hurts
now].

Keep in mind that constraints are bound to vocabulary modules and that, for
a given module used in a document, you can have at most one associated
constraint. Thus, for the topic type vocabulary module, two documents that
include the task module either have no constraints, both use the same
constraint module for task, or both use different (and thus incompatible)
constraint modules.

The current Arch Spec has a fairly clear description of how constraint
module usage affects conref in the topic "Conref and generalization for
constraint domains" under the Constraint domains topic in the Configuration
and Extension section.

There is one subtle case from that discussion, which took me a minute to
figure out:

Referencing Document domains declaration:

  (topic task)
  (topic hi-d basicHighlight-c)

Referenced Document domains declaration:

  (topic simpleSection-c task simpleTaskSection-c)

The doc says this is *allowed*, because the target is more constrained for
the task topic type.

So this means that you can have a topic that includes no modules and that
holds elements intended for conref, e.g., <ph>, <keyword>, etc. and conref
those elements from *any* topic, no matter how specialized or constrained,
because the "conref to same or more specialized only" rule applies, meaning
you can only use <ph>, and not some specialization of <ph>, to conref those
phrases from any referencing topic.

But, if you have two <task> documents *and* you want to conref <step>
elements (and element type defined in the task vocabulary module), both task
documents have to have the same constrain applied to the task vocabulary
module (meaning either both are unconstrained or both use the same
constraint module).

Whew. 

Cheers,

Eliot

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