[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]