RE: [dita] Why There are Constraints on Conref

["Tony Self" <tself@hyperwrite.com>]

Hi all

I have to admit to not previously spending much time trying to understand
constraints. I am only now trying to get my head around the feature, and the
recently raised conref issues (which did alarm me). I have drawn together a
simplistic summary of the feature, prior to Michael's proposed "weak"
addition. I have attached that summary, in case it is useful to anyone also
playing catch-up. I hope I have got the fundamentals right.

As I understand it, the main problem is that I can't conref something like a
simple <note>Don't run with scissors!</note> element from a base
(unconstrained) concept topic into a constrained concept topic (even if
<note> is allowed in the constrained topic), because conreffing from a less
restrictive to a more restrictive topic is not permitted.

Michael's "weak" proposal will impact on the way constraints are declared,
and the way processors handle constraints.

Perhaps I'm displaying my ignorance on the issue, but would an alternative
be for the constraints to be ignored unless the conref inclusion "broke" the
content model rules of the target topic? So, provided the imported <note>
would be valid if it were pasted into the target, constrained topic, then
the conref is valid.

Hope I'm not muddying the water.

Tony Self

Title: Constraints in DITA 1.2

Constraints in DITA 1.2

Constraints are an architectural enhancement to DITA, introduced in DITA 1.2.

A constraint defines a set of restrictions that conform to the rules of specialisation. (The constraints mechanism was originally proposed as replacement domains.) Constraints aim to provide a more simplified authoring environment by restricting the markup options available to DITA authors to conform to business rules.

A constraint can remove an optional element from a content model, make an otherwise optional element required, and modify the attributes of an element by adding attributes or making them required. However, a constraint cannot make a mandatory element optional, and nor can it make a mandatory.

Constraints are similar in purpose to specialisations, but attempt to avoid the perceived technical complexity of specialisation. They also allow non-semantic structural changes to be made without the specialisation mechanism, which was designed more for semantic changes.

A typical constraint might apply the following business rules to an authoring environment:

• Remove the ph element, and prefer its filepath, userinput, and systemoutput specialisations instead.
• Remove the keyword element, and prefer its cmdname and varname specialisations.
• Remove the ability to nest block elements such as ol and table within lq and p block elements.
• Make shortdesc a required element.

A constrained topic will always be valid as an unconstrained topic, as constraints only restrict what it permitted, not extend. For example, if a constrained concept content model prevented section elements in a concept topic, a constrained concept topic would still be a valid concept topic, because the base content model allows a concept topic without a section.

Elements of a constrained topic can be transcluded (conreffed) into a base (unconstrained) topic, but elements of a base (unconstrained) topic may not be able to be transcluded (conreffed) into a constrained topic if the source topic would not conform to the constraint rules. In other words, elements from a less restrictive document cannot be incorporated into a more restrictive document, regardless of whether the conreffed element itself would be valid in the target (constrained) topic.

Constraints are specified, or declared, in attributes in the topic element, and reference the constraint rules specified in DTD or XSD modules. There are two constraint attributes: constraints and constraint-scope. A constraint stored in shortdescReqConstraints.mod is declared in the topic as shortdescReq-c.

Example of a constraint declaration

A constraint to make the audience attribute required, to specify a list of valid values for the audience attribute, and to make the title element within a shortdesc element required, would look like:

<reference ...
        audience="administrator"
        constraints=" db-audience-enum-c topic-audience-req-c shortdescReq-c"
        constraint-scope="db-audience-enum-c( topic/topic ... )
            topic-audience-req-c( topic/topic )
            shortdescReq-c( reference/shortdesc )">