@conrefend
attributeThe @conrefend
attribute is used when referencing a range of elements
with the conref mechanism. The @conref
or @conkeyref
attribute
references the first element in the range, while @conrefend
references the last
element in the range.
@conref
together with @conrefend
Several items must be taken into account when using or implementing
@conrefend
.
@conref
and @conrefend
attributes on an <li>
element might reference other
<li>
elements, or they might reference specializations of
<li>
such as <step>
.@conref
, if the @conrefend
references a more specialized
version of the referencing element, applications should generalize the target when
resolving. @conrefend
to reference a more general version of an
element (such as using <step>
to reference an
<li>
element).<conbody>
into <body>
, because <conbody>
is
generalizable to <body>
. It is not possible to pull a range from
<body>
into <conbody>
, because the result
might not be valid in
<conbody>
.@id
attribute from the referenced element will not be
preserved on the resolved content. With a range, an @id
on both the start
and the end elements will not be preserved. @id
attributes on intermediate
or child nodes should be preserved; if this results in duplicate @id
values, an application can recover by changing the @id
,
warning the user, or implementing another strategy.@id
attribute is specified on the referencing element, it
will only be preserved on the first element of the resolved range.<step>
is used to pull in a
range of sequential <step>
elements, locally specified
attributes apply to all steps in the range. If <ol>
is used to
pull in a series of (<ol>
, <p>
,
<ol>
), locally specified attributes apply only to the
<ol>
elements in that range.<topic id="x"> ... <body> <ol> <li id="apple">A</li> <li id="bear">B</li> <li id="cat">C</li> <li id="dog">D</li> <li id="eel">E</li> </ol> </body> </topic>
<topic id="y"> ... <body> <ol> <li>My own first item</li> <li conref="topic.dita#x/bear" conrefend="topic.dita#x/dog"/> <li>And a different final item</li> </ol> </body> </topic>
<topic id="y"> ... <body> <ol> <li>My own first item</li> <li>B</li> <li id="cat">C</li> <li>D</li> <li>And a different final item</li> </ol> </body> </topic>
<topic id="x"> ... <body> <p id="p1">First para</p> <ol id="mylist"> <li id="apple">A</li> <li id="bear">B</li> <li id="cat">C</li> <li id="dog">D</li> <li id="eel">E</li> </ol> <p id="p2">Second para</p> </body> </topic>
<topic id="y"> ... <body> <p conref="topic.dita#x/p1" conrefend="topic.dita#x/p2"/> </body> </topic>
<topic id="y"> ... <body> <p>First para</p> <ol id="mylist"> <li id="apple">A</li> <li id="bear">B</li> <li id="cat">C</li> <li id="dog">D</li> <li id="eel">E</li> </ol> <p>Second para</p> </body> </topic>
@conrefend
together with @conkeyref
When the @conkeyref
attribute is used in place of @conref
,
a key is used to address the target of the reference. The @conrefend
attribute, which indicates the end of a @conref
range, cannot use a key. Instead the the map or topic element
addressed by the key name component of the @conkeyref
is used in place of
whatever map or topic element is addressed by the @conrefend
attribute.
For example, if the value of the @conkeyref
attribute is "config/step1" and
the value of the @conrefend
is
defaultconfig.dita#config/laststep, the conref range will end with the
step that has id="laststep" in whatever topic is addressed by the key name "config". If the
key name "config" is not defined, and the @conref
attribute itself is not
present for fallback, the @conrefend
attribute is ignored.
@conrefend
with @conkeyref
@conkeyref
In this example the key "xmp" is defined as the first topic in the file examples.dita.
<map> <!-- ... --> <keydef keys="xmp" href="examples.dita"/> <!-- ... --> </map> examples.dita: <topic id="examples"> <title>These are examples</title> <body> <ul> <li id="first">A first example</li> <li>Another trivial example</li> <li id="last">Final example</li> </ul> </body> </topic>
@conkeyref
attribute
combines the key itself with the sub-topic id (first) to define the start of the range.
The @conrefend
attribute defines a default high-level object along with
the sub-topic id (last) that ends the
range:<li conkeyref="xmp/first" conrefend="default.dita#default/last"/>
The @conkeyref
attribute uses a key to reference the first topic in
examples.dita, so the range begins with the object
examples.dita#examples/first. The high-level object in the
@conrefend
attribute (default.dita#default) is replaced
with the object represented by the key (the first topic in
examples.dita), resulting in a range that ends with the object
examples.dita#examples/last.
@conref
, @conkeyref
, and
@conrefend
When @conref
, @conkeyref
, and @conrefend
are all specified, the key value takes priority.
<li conkeyref="thisconfig/start" conref="standardconfig.dita#config/start" conrefend="standardconfig.dita#config/end"/>
@conref
and
@conrefend
attributes are used as fallback. In that case, the range
will go from the list item with id="start" to the list item with id="end" within the
topic standardconfig.dita#config.When encountering an error condition, an implementation can issue an error message.
Condition or Issue | Result |
---|---|
The @conref attribute cannot be resolved in the
target document (the target element might have been
removed or its id has changed). |
The @conref is ignored. |
The @conrefend attribute cannot be resolved in
the target document (the target element might have
been removed or its id has changed). |
Range cannot be resolved, optional recovery processes the result as a simple conref. |
Start and end elements are not siblings in the target document. | If the start element exists, optional recovery processes the result as a simple conref. |
End element occurs before the start element in the target document. | If the start element exists, optional recovery processes the result as a simple conref. |
An element has a @conrefend attribute but is
missing the @conref attribute. |
No result. |
Return to main page.
dita-v1.3-cos01-part2-tech-content Non-Standards Track | Copyright © OASIS Open 2015. All Rights Reserved. | 03 September 2015 |