RE: [dita] Conref push in a DITA map?

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

I assume the question is about pushing a topicref element, e.g. in
example fribblewhiskets.ditamap

<map id="fa" title="Fribblewhiskets">
 <topicref id="a" href="Fribblewhiskets.dita" type="topic">
  <topicref id="b" href="Fribblewhisket_internals.dita"
type="concept"></topicref>
  <topicref id="c" href="Fribblewhisket_configuration.dita"
type="task"></topicref>
  <topicref id="d" href="Fribblewhisket_corroboration.dita"
type="task"></topicref>
  <topicref id="e" href="Fribblewhisket_LEDs.dita"
type="reference"></topicref>
  <topicref id="f" href="Fribblewhisket_FRUs.dita"
type="reference"></topicref>
 </topicref>
</map>

Example newfribblefru.ditamap:

<map id="fb" title="New Fribblewhisket FRUs">
 <topicref
         href="Fribblewhisket_new_FRUs.dita" type="reference"
         conaction="mark"
         conaction="pushreplace" 
         conref="fribblewhiskets.ditamap#c"/></topicref>
</map>

A second topicref would be needed for pushbefore or pushafter.
_____________________________________________________________

The topic entitled "The conaction attribute" says "Multiple sources may
push content {before|after} the same target; the order in which that
content is pushed is undefined." 

1. I infer that it is up to the processing code to decide the push
order, closest first (inside out), closest last (outside in), or some
other order (though that seems unlikely to me). If this is true,
shouldn't we tell implementers explicitly that this is their
responsibility?

2. I infer that you can do both pushbefore and pushafter wrt the same
mark. True? For example:

  <step conaction="pushbefore"><cmd>Do this BEFORE B</cmd></step>
  <step conaction="mark"
         conref="example.dita#example/b"/>
  <step conaction="pushafter"><cmd>Do this AFTER B</cmd></step>

3. How about combinations with @pushreplace? If this is valid, is
@pushreplace in the same element instance with @mark? For example:

  <step conaction="pushbefore"><cmd>Do this BEFORE B</cmd></step>
  <step conaction="mark"
         conaction="pushreplace" 
         conref="example.dita#example/b"/>
  <step conaction="pushafter"><cmd>Do this AFTER B</cmd></step>

If this is valid, does relative order of conaction="mark",
conaction="pushreplace", and @conref matter within the element? (I
assume not.)

4. conaction="mark" has one meaning and a restriction on its location
has another. 

   - The meaning suggested by the attribute name is akin to a 
     word anchor,marking a location for action. 

   - The test that plural instances of the conref-bearing
     element are valid is supported by requiring that 
     conaction="mark" be on a separate element instance. 

Do we require that processing software verify that conaction="mark" be
on a separate element instance? If so, shouldn't we tell implementers
explicitly? (I don't know any way to enforce it in DTD syntax.)
   

4. Is the depth of nesting restricted? That is, the length of the
'|'-separated part of the conref value in e.g.

      conref="example.dita#example/first/second/.../last"/>

6. The restrictions about @mark must appear twice, as they do now, so we
should clean up the "before or after" language.

When an element is pushed before a target, the resulting document will
have at least two of that element. Because this is not always valid, a
document attempting to push content before a target must take an extra
step to ensure that the result will be valid. The extra step makes use
of the conaction="mark" value.

When an element is pushed after a target, the resulting document will
have at least two of that element. Because this is not always valid, a
document attempting to push content after a target must take an extra
step to ensure that the result will be valid. The extra step makes use
of the conaction="mark" value.

5. Looks to me like this topic might benefit from a section called
something like "Restrictions on combinations of attributes". This could
be the location of statements common to @pushbefore and @pushafter, and
maybe the above considerations as well. Here are some examples from that
topic (with some rewriting):

It is an error for two source topics to replace the same element.
Applications may, but need not, warn users if more than one element
attempts to replace a single target.

Multiple sources may push content before or after the same target; the
order in which that content is pushed [is undefined --> must be defined
by processing software].

The following restrictions apply when pushing content before or after an
element: 

. The element that uses conaction="mark" must be of the same type, or a
specialization descended from the same type, as the element referenced
by its conref attribute. This restriction ensures validity. 

. Elements that use conaction="pushbefore" or conaction="pushafter must
be of the same type as the adjacent element with conaction="mark", and
no elements other than these may intervene. This restriction ensures
that it is valid to insert more than one instance of that element. 




> -----Original Message-----
> From: Kristen James Eberlein [mailto:keberlein@pobox.com] 
> Sent: Thursday, October 01, 2009 9:53 AM
> To: DITA TC
> Subject: [dita] Conref push in a DITA map?
> 
> I've drafted an article about conref push for the DITA 
> Adoption Committee. Seth Park, Elliot Kimber, and Paul Grosso 
> were kind enough to review it.
> 
> One of Elliot's comments led to a discussion about whether or 
> not conref push works at a DITA map level.
> 
>     * The use case in the original proposal
>       
> (http://www.oasis-open.org/committees/download.php/26290/Issue
> Number17e.html)
>       focuses entirely on pushing content into an existing DITA topic.
> 
>     * The most recent draft of the DITA 1.2 documentation
>       
> (http://www.oasis-open.org/apps/org/workgroup/dita/download.ph
> p/34300/dita1.2-spec-complete_20September2009.chm)
>       explicitly defines the @conaction attribute as an attribute that
>       "allows user to push content from one topic into another."
> 
>     * The @conaction attribute *is* available for <topicref> elements,
>       although pushing content into a DITA map does not work with the
>       DITA OT (milestone 17).
> 
> Should conref push work at the DITA map level?
> 
> Best,
> 
> Kris
> 
> Kristen James Eberlein
> 
> 
> 
> ---------------------------------------------------------------------
> 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_workgr
> oups.php 
> 
>