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">
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>
FD0BCA133D9079489F2973E63A4966F803D2C5B7@xmb-rtp-204.amer.cisco.com"
type="cite">
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>
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
|