RE: [dita] Why There are Constraints on Conref

["Ogden, Jeff" <jogden@ptc.com>]

I went back and checked the Arbortext 5.4 release (our current release)
which uses the preliminary DITA 1.2 DTDs and XSDs and adding a domains
attribute construction such as w(...) to allow the declaration of weak
constraints won't cause any problems.  Of course we just ignore the new
construct at this point, but since we haven't implemented DITA 1.2
constraint checking on conrefs, all constraints are "weak".

As I said in a previous note, if our Specialization Validation function
encounters the new w(...) construct, it will flag it as an error with
the message:

	Domain attribute value at "xxxx" is improperly formatted

But this validation is only done upon request, the error can be safely
ignored, and in some future release we can update things so w(...) isn't
flagged as an error.

   -Jeff

> -----Original Message-----
> From: Ogden, Jeff
> Sent: Monday, September 28, 2009 2:39 PM
> To: 'ekimber'; 'Michael Priestley'
> Cc: 'dita'; 'rob@ascan.ca'; 'Su-Laine Yeo'
> Subject: RE: [dita] Why There are Constraints on Conref
> 
> Eliot wrote:
> > If there are existing implementations of constraint checking (I'm
> thinking specifically of
> > Arbortext Editor here), then I would think we are obligated to wait
> > until 1.3.
> 
> Arbortext Editor doesn't implement constraint checking for conrefs.
> 
> Adding a new construct for weak constraints, w(...), will produce an
> error message from our Specialization Validation function about an
> invalid value in a domains attribute, but that validation is only done
> on request and the error can be ignored without any harm other than
> possibly some confusion or worry on the part of the person who asked
> for the validation.
> 
> What I need to check is if adding the w(...) construct will be ignored
> by our conref code or if it might cause problems.  I'm guessing that
it
> will be ignored, but I've been wrong about such things before.  I'll
> try to check this in more detail this afternoon.
> 
> Are there implementations other than Arbortext Editor and the DITA
Open
> Toolkit that implement conrefs?  I assume there are and I assume it
> would be good to hear from everyone about what sorts or problems this
> late change to DITA 1.2 might or might not cause.
> 
>    -Jeff
> 
> > -----Original Message-----
> > From: ekimber [mailto:ekimber@reallysi.com]
> > Sent: Friday, September 25, 2009 2:17 PM
> > To: Michael Priestley
> > Cc: dita; Ogden, Jeff; rob@ascan.ca; Su-Laine Yeo
> > Subject: Re: [dita] Why There are Constraints on Conref
> >
> > I think it's a very useful idea.
> >
> > On first read it appears to satisfy the requirements on both sides
of
> > the
> > issue
> >
> > As for should it be in 1.2? Has anyone implemented actual constraint
> > declaration checking that would have to be updated to reflect this
> > change?
> > If this is only a change to syntax that all processors (and many
> > vocabulary
> > module developers) ignore, I would say that we explore adding this
in
> > 1.2 if
> > further thought on the proposal holds up. If there are existing
> > implementations of constraint checking (I'm thinking specifically of
> > Arbortext Editor here), then I would think we are obligated to wait
> > until
> > 1.3.
> >
> > Cheers,
> >
> > Eliot
> >
> > On 9/25/09 1:05 PM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:
> >
> > > Eliot, I think that's an eloquent description of the rationale for
> > the
> > > current situation, and it's certainly where my thinking is coming
> > from as
> > > well.
> > >
> > > I did have a thought on how we might be able to achieve a
> compromise
> > of
> > > sorts, preserving the strict validation that we both consider
> > necessary
> > > for robust processes, while allowing for broader reuse scope in
> some
> > of
> > > the cases Rob and others have been asking for (including task-
> > >general
> > > task).
> > >
> > > Here's my thought:
> > >
> > > - if the doctype developer knows upfront whether a constraint is
> just
> > an
> > > authoring guideline or whether it's a strict business requirement,
> > they
> > > could annotate the constraint on inclusion
> > > - constraints noted as "weak" would be ignored by conref
validation,
> > and
> > > would be considered unreliable by processors, which would need to
> > assume
> > > the constraint wasn't there as well
> > >
> > > Example:
> > > - group A introduces a constraint that makes title in fig required
> -
> > they
> > > have a figlist generator that depends on this, so they make the
> > constraint
> > > required - if someone tries to conref from a place that allows
> title-
> > less
> > > figs, they'll get an error, and will have to negotiate with the
> other
> > team
> > > to introduce the constraint in their shared content
> > > - group B introduces a constraint that makes <ul> unavailable in
> <p>,
> > > because they think it's simpler for their authors. But they don't
> > depend
> > > on it, the output looks the same whether they allow <ul> inside
<p>
> > or
> > > not, and they may need to conref content from another team that
> > doesn't
> > > use the constraint. So they make the constraint "weak" instead of
> > > required.
> > >
> > > Technical complexity:
> > > - add a flag to constraints to indicate when they are included as
> > "weak" -
> > > eg - domains=" w(myconstraint) "
> > > - add a check to conref validation that ignores weak constraints
> when
> > > determining validity
> > >
> > > If we wanted to, we could then implement our strict task as a weak
> > > constraint, so it would be able to conref from loose task.
> > >
> > > I think this might address the concerns of both sides - it gives
us
> > strong
> > > constraints when there are business or processing requirements on
> the
> > > constrained structure, but allows reuse in other cases.
> > >
> > > All that said, I'm very aware of how late in the cycle we are, and
> I
> > don't
> > > think the cross-constraint use case is actually going to come up
> that
> > > often. So there's probably a few questions to ask:
> > >
> > > - is this a useful idea?
> > > - does it address the use cases of both sides?
> > > - if it is, is it useful enough to change in 1.2, or should it
wait
> > till
> > > 1.3?
> > >
> > > Michael Priestley, Senior Technical Staff Member (STSM)
> > > Lead IBM DITA Architect
> > > mpriestl@ca.ibm.com
> > > http://dita.xml.org/blog/25
> > >
> > >
> > >
> > > From:
> > > ekimber <ekimber@reallysi.com>
> > > To:
> > > <rob@ascan.ca>, Su-Laine Yeo <su-laine.yeo@justsystems.com>,
> Michael
> > > Priestley/Toronto/IBM@IBMCA
> > > Cc:
> > > dita <dita@lists.oasis-open.org>, Jeff Ogden <jogden@ptc.com>
> > > Date:
> > > 09/24/2009 11:52 PM
> > > Subject:
> > > Re: [dita] Why There are Constraints on Conref
> > >
> > >
> > >
> > > On 9/24/09 10:23 PM, "Rob Hanna" <rob@ascan.ca> wrote:
> > >
> > >>> They might be making content outside
> > >>> their environment unusable *by them*
> > >>> but they would not be making their
> > >>> content unusable to others who use fewer
> > >>> constraints.
> > >>
> > >> What if instead of having fewer constraints, they have different
> > > constraints?
> > >> This is not simply a matter of just two task variations. Over
time
> > the
> > >> variations of standard topic types introduced through constraints
> > will
> > > grow.
> > >
> > > This is why you have the domains attribute at all: so you can
> analyze
> > the
> > > constraints at use in two DITA documents to determine if they are
> > > compatible. This at least lets you detect this situation early,
> > rather
> > > than
> > > late (such as after a publication has been published).
> > >
> > >> For example, consider one possible scenario I see where this
might
> > > present a
> > >> problem:
> > >>
> > >> "Over the course of several years a department's style guide
> changes
> > > several
> > >> times through reorgs and acquisitions - each time enforced with a
> > > different
> > >> set of constraints introduced. There is no budget to convert the
> > older
> > >> content. Over time reuse opportunities are lost and content must
> be
> > > duplicated
> > >> to suit different doc sets written to adhere to separate
> > constraints."
> > >>
> > >> As it stands now, constraints do not deprecate gracefully as
would
> > > domain
> > >> specializations. Even substructures within structurally
> specialized
> > > content
> > >> can generally be reused safely.
> > >
> > > Note that it is *easy* to remove constraints: you simply update
> your
> > > shells
> > > to stop including the constraint modules. No need to modify the
> > documents
> > > involved.
> > >
> > > That means that given two sets of content that have incompatible
> > > constraints
> > > you can make them compatible by changing their governing shells to
> be
> > less
> > > constrained.
> > >
> > > But in fact I think what you are expressing is a problem inherent
> in
> > any
> > > interoperation situation. DITA isn't changing the fact that two
> > > interchanging communities might have divergent rules over time
such
> > that
> > > there may be data and processing interoperation problems: that's
an
> > > unavoidable fact of life.
> > >
> > > What DITA is saying is "we're giving you a way to detect that case
> > early,
> > > rather than late" and make an informed decision about how to
react.
> > >
> > > In practice I think most DITA users will tend to avoid constraints
> > simply
> > > because any constraint, by its nature, tends to impede
> bidirectional
> > > interchange.
> > >
> > > The only reason we're having this discussion at all is because
DITA
> > 1.0
> > > inherited an over-constrained task model from IBM, something we
> > should
> > > have
> > > fixed in 1.1 but didn't. It's only now that we have the constraint
> > > mechanism
> > > that we can fix the problem (overconstrained tasks) in a way that
> > allows
> > > backward compatibility without having to define a completely
> > different
> > > task
> > > base type and specialization.
> > >
> > >> This is an issue that can only get more complex over time. In my
> > > opinion,
> > >> processors must be designed to handle the base (or call it
general
> > or
> > > loose)
> > >> structures with warnings to ensure seamless exchange of content.
> > >
> > > But it's not that easy: there may be processing cases where it
> would
> > be at
> > > best wrong, at worst impossible, to properly process and render
> > > unconstrained content in a constrained context, because the
> > constraints
> > > are
> > > there, in that case, to enable or ensure a particular
presentation.
> > So you
> > > can't simply say "processors have to be able to process any
> > combination of
> > > stuff".
> > >
> > > 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>
> > >
> > >
> > >
-------------------------------------------------------------------
> --
> > > To unsubscribe from this mail list, you must leave the OASIS TC
> that
> > > generates this mail.  Follow this link to all your TCs in OASIS
at:
> > > https://www.oasis-
> > open.org/apps/org/workgroup/portal/my_workgroups.php
> > >
> > >
> > >
> >
> > ----
> > 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>