Thanks, Kris. The first part of
my reply tried to make that question more concrete.
IF conref push works at the map level, does it work in the way
I indicated? (Modulo the error of putting conaction="mark" with pushreplace -- my bad, copy/paste
error.)
The remainder has to do with
conref push generally, and is a series of questions that came up for me reading
the lang ref topic entitled "The conaction attribute".
conaction="mark" with each and every pushbefore or
pushafter --
IMO this is poor design per
stated motivation and per usability. Stated motivation is to ensure that more
than one <x> can occur (the function of the separate element instance) at
the addressed point (the function of mark), and motivation is satisfied by one
instance with conaction="mark". Usability: intuitively,
mark sets an address, and if I have to set the same address several times
in several (near-)contiguous elements my reaction as a user is that this code
was written for the coder's convenience without thinking of the
user.
Question 5 is a no-op, my goof
as noted by Elliot. Questions 1, 4, 6, 7 still open. (My questions below are
numbered sequentially this time--should have taken a bit longer before
sending!)
/Bruce
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.)
5. 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.
7. 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