[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Conref push in a DITA map?
On 10/4/09 10:31 AM, "Kristen James Eberlein" <keberlein@pobox.com> wrote: > Again, my primary question was whether or not conref push was intended to work > at the DITA map level. The original proposal and the current draft > specification ONLY refer to conref push at the topic level. Add currently, one > cannot push content into a DITA map using the DITA Open Toolkit. Conref in general is a general facility usable in both maps and topics (and, as we've just established, doable between maps and topics for common elements). If conref push was *not* allowed for maps that would be very strange indeed. Cheers, Eliot > This is an important point that I think we need to clarify. > > Bruce, I've added some comments (in <kje> tags) to your response below. > Michael, I'm e-mailing you directly about this since you were the > owner/champion for this feature. > > I'll attach a draft of my article in case any one else would like to review > it. (Note that I have not yet cleaned up all the references to source and > target elements ...) > > Best, > > Kris > > Bruce Nevin (bnevin) wrote: >> >> 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> >> > <kje>You do not need to set the @conaction attribute to "mark" for a > pushreplace operation. The purpose of conaction="mark" is 1) to specify the > location of a pushbefore or pushafter operation, and 2) enable processors to > check whether having two elements in a particular location is valid.</kje> >> >> >> 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> >> > <kje>No. You'd get an error message similar to the following: > > [ERROR] There is no target specified for conref push action > "pushafter".Xtrf="<location of conref file>" Xtrc="step:3" Please add > <elementname conref="pushtarget" conaction="mark"> before current element. > > If you wanted to push <step> elements both before and after, you'd need your > conref file to contain the following code: > > <step conaction="pushbefore"><cmd>Do this BEFORE B</cmd></step> > <step conaction="mark" conref="example.dita#example/b"></cmd></step> > <step conaction="mark" conref="example.dita#example/b"></cmd></step> > <step conaction="pushafter"><cmd>Do this AFTER B</cmd></step> > > </kje> >> >> >> 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 >>> >>> >>> >>> >> >> >> --------------------------------------------------------------------- >> 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 >> >> >> >> > --------------------------------------------------------------------- > 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>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]