Re: [dita] Fw: [dita-comment] #12013 Referencing a range of elements

[Deborah_Pickett@moldflow.com]

My comments below...

-- 
Deborah Pickett
Information Architect, Moldflow Corporation, Melbourne
Deborah_Pickett@moldflow.com

"Yas Etessam" <yas.etessam@justsystems.com>
wrote on 08/08/2007 11:03:40 AM:

> Hello Deborah, 
> 
> Thank you for your comments, please see responses below.  
> 
> Yas
> 
> 
> > The proposal doesn't speak of what happens when filtering removes
one
> > or
> > both ends of the range.  Is this invalid?  Or is it
valid, with the
> > intervening unfiltered elements remaining?  Is it still
valid if all
> > elements are filtered out?
> According to this diagram that shows the DOT's pre-processing
> architecture,
> http://dita-ot.sourceforge.net/SourceForgeFiles/doc/DITA-preprocessarch.
> html, filtering will happen before conrefs are resolved.
> 
> If the start/end markers are filtered out, there is nothing to pull
in.
> 
> The situation would be the same if a pair of matched start/end markers
> are orphaned because of filtering.  There is no way to pull in
the
> intervening (unfiltered elements) if a start or end markers is been
> filtered out.  

That's a problem.  It breaks a use case that
I expect to see a lot: pulling in a series of steps that contain filtering
for different products.

Example:

<task id="sharedsteps">
  ...
  <steps>
    <step id="first" product="one"><cmd>Flush
all widgets.</cmd></step>
    <step><cmd>Open a new widget.</cmd></step>
    <step product="two"><cmd>Set
advanced options.</cmd><substeps>...</substeps></step>
    <step id="last"><cmd>Press
OK to continue.</cmd></step>
  </steps>
  ...
</task>

Pulling this series of steps thus:
  <steps>
    <step conref="shared.xml#sharedsteps/first"
conreftype="start"/>
    <step conref="shared.xml#sharedsteps/last" conreftype="end"/>
    <step><cmd>Now go do something
else.</cmd></step>
  </steps>
will work only if product "one" is not filtered
out.

I think that this is going to astonish a lot of users.
 I don't want to have to respond to their question "why doesn't
it work" with "that's how we designed it".

I see three choices for a resolution:
- Conref resolution must be done before filtering,
and DITA-OT is currently off spec.  Then this example would get the
useful behaviour of filtering the sequence of steps after they are pulled
into existence.
- We state that the proposal isn't intended to cover
this use case.  In big letters, because users will expect it to work
irrespective of filtering.
- The proposal needs further work to cover this use
case.

> After conferring with Rob Anderson offline, bringing
in nodes as part of
> the intermediary range is fine. 

Good, thanks, that makes me happy.

> > What happens when conrefs are chained? [...]
> If you have a regular conref and it points to
an element that has a
> start conref, the user's intention is probably to pull in that single
> element not the range. 

This needs to be specified, not left to a default
"probable user's intention".  Particularly since normal
conref processing might pick up the conreftype="start" attribute
and leave you with a dangling start without end.  It may be safest
to simply forbid conref chaining where the types don't match.  If
we find a use for it later, re-allow it.
 
> > I worry about the onus that the author of the reusable content
has in
> > marking the start/end elements *and not messing with them later*.
> That
> > presents a level of coupling that standard conref doesn't have.
 In
> > particular, the common use case of "pull all of the steps
in a task,
> > then add some of my own" has more overhead than it should.
 (Think of
> a
> > task with only one step (and so only one id on the step).  Others
pull
> > this singleton step with a range conref, with start/end ids the
same.
> > I
> > then add a second step, and give it a new id.  But all the
range
> > conrefs
> > pulling my steps don't know about this, because they only know
of the
> > one id, of my original step.)

I particularly wanted to hear people's reaction to
this one.  Here's an example spelling it out.

With one step:
<task id="sharedsteps">
  ...
  <steps id="allsteps">
    <step id="first"><cmd>Do
this thing.</cmd></step>
  </steps>
  ...
</task>

Pulled into this file which someone else is maintaining:
<steps>
  <step conref="shared.xml#sharedsteps/first"
conreftype="start"></step>
  <step conref="shared.xml#sharedsteps/first"
conreftype="end"></step>
  <step><cmd>Now do some other stuff.</cmd></step>
</steps>

All fine, until I add a second step:
<task id="sharedsteps">
  ...
  <steps>
    <step id="first"><cmd>Do
this thing.</cmd></step>
    <step id="last"><cmd>I
forgot, do this thing too.</cmd></step>
  </steps>
  ...
</task>

All of the tasks which pull my list of steps need
to be updated to point to sharedsteps/last.  This amounts to finding
backreferences, which I am not at all comfortable with.  Not every
user has a cosy CMS to handle that for them automatically.

It's the transition from one thing to two things that
is the issue here.  Even moving to a one-element/two-conref-attribute
model won't solve this one.

Thinking out loud, how about something like:
<steps>
  <step conref="shared.xml#sharedsteps/allsteps"
conreftype="allchildren"/>
  <step><cmd>Now do some other stuff.</cmd></step>
</steps>
The elements would all have to be the same type, but
here they happen to be . . .

> > And now the big one . . . I need to be convinced
that the
> > two-adjacent-element conreftype=start/end markup is better than
the
> > alternative one-element-with-two-conref-attributes markup.
[...]
> As the conref feature is already implemented in many tools and CMS
> systems, the addition of a single modifier to enable this form of
> short-hand conref is a simpler change.

Yes, I imagine that the changes for maintainers of
tools, editors and CMSs will probably prefer that over rehashing their
conref-resolution code.  It still feels to me like a case of the tail
wagging the dog, but I won't argue it any more; I've made my opinion clear.
 But I'd still like to know your (and others') thoughts on the above
two examples.

Oh, one more thing.  Explicitly naming the first
and last elements at the pulling end leaves room for there to be some generalizing-during-conref
on those elements (e.g., you pull in a <b> with <ph conref="...">).
 What about the intervening elements?  Generalize as little as
needed to make them fit?  Is that information available during conref?
 Or forbid generalization-during-conref for ranges?