[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Conref push in a DITA map?
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. 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: FD0BCA133D9079489F2973E63A4966F803D2C5B7@xmb-rtp-204.amer.cisco.com" type="cite"><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>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> FD0BCA133D9079489F2973E63A4966F803D2C5B7@xmb-rtp-204.amer.cisco.com" type="cite"><kje>No. You'd get an error message similar to the following: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> [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> FD0BCA133D9079489F2973E63A4966F803D2C5B7@xmb-rtp-204.amer.cisco.com" type="cite">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. FD0BCA133D9079489F2973E63A4966F803D2C5B7@xmb-rtp-204.amer.cisco.com" type="cite">-----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 |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]