From 1c4781112b7e9b6bfa22e131caae19d78b3bd4ca Mon Sep 17 00:00:00 2001 From: "Robert D. Anderson" Date: Fri, 13 Sep 2024 11:43:07 -0500 Subject: [PATCH 1/2] Move conref examples into example topics --- .../example-conref-conaction-pushafter.dita | 47 +++++++++++ .../example-conref-conaction-pushbefore.dita | 47 +++++++++++ .../example-conref-conaction-replace.dita | 45 ++++++++++ .../base/example-conref-conkeyref.dita | 62 ++++++++++++++ ...ple-conref-includes-xref-and-keyscope.dita | 53 ++++++++++++ .../base/example-conref-includes-xref.dita | 82 +++++++++++++++++++ .../base/example-conref-range-blocks.dita | 62 ++++++++++++++ .../base/example-conref-range-conkeyref.dita | 67 +++++++++++++++ .../base/example-conref-range-list.dita | 61 ++++++++++++++ .../archSpec/base/example-conref-simple.dita | 60 ++++++++++++++ .../archSpec/base/examples-conref.dita | 7 ++ 11 files changed, 593 insertions(+) create mode 100644 specification/archSpec/base/example-conref-conaction-pushafter.dita create mode 100644 specification/archSpec/base/example-conref-conaction-pushbefore.dita create mode 100644 specification/archSpec/base/example-conref-conaction-replace.dita create mode 100644 specification/archSpec/base/example-conref-conkeyref.dita create mode 100644 specification/archSpec/base/example-conref-includes-xref-and-keyscope.dita create mode 100644 specification/archSpec/base/example-conref-includes-xref.dita create mode 100644 specification/archSpec/base/example-conref-range-blocks.dita create mode 100644 specification/archSpec/base/example-conref-range-conkeyref.dita create mode 100644 specification/archSpec/base/example-conref-range-list.dita create mode 100644 specification/archSpec/base/example-conref-simple.dita create mode 100644 specification/archSpec/base/examples-conref.dita diff --git a/specification/archSpec/base/example-conref-conaction-pushafter.dita b/specification/archSpec/base/example-conref-conaction-pushafter.dita new file mode 100644 index 00000000..a1102541 --- /dev/null +++ b/specification/archSpec/base/example-conref-conaction-pushafter.dita @@ -0,0 +1,47 @@ + + + + Example: Using <xmlatt>conaction</xmlatt> to push content after another element + In this scenario, a conref and conaction are used to + push content after an element in another topic. + +

Consider the following topic, which is set up to push a step after a step in another topic. + It needs to use two step elements to set up the reuse. The referencing element itself uses + conaction="mark" to mark the referenced element. The element to be pushed + immediately follows the marking element and uses conaction="pushafter": + <steps> + <step conaction="mark" conref="example.dita#example/b"> + <cmd/> + </step> + <step conaction="pushafter"> + <cmd>Do this after B</cmd> + </step> +</steps>

+

The referenced element is in the file example.dita, which looks like + this before a processor resolves the + reference:<task id="example" xml:lang="en"> + <title>Example topic</title> + <taskbody> + <steps> + <step id="a"><cmd>A</cmd></step> + <step id="b"><cmd>B</cmd></step> + <step id="c"><cmd>C</cmd></step> + </steps> + </taskbody> +</task>

+

After the content reference is resolved, the document example.dita + includes the pushed step element after the step with + id set to + b:<task id="example" xml:lang="en"> + <title>Example topic</title> + <taskbody> + <steps> + <step id="a"><cmd>A</cmd></step> + <step id="b"><cmd>B</cmd></step> + <step><cmd>Do this after B</cmd></step> + <step id="c"><cmd>C</cmd></step> + </steps> + </taskbody> +</task>

+ + diff --git a/specification/archSpec/base/example-conref-conaction-pushbefore.dita b/specification/archSpec/base/example-conref-conaction-pushbefore.dita new file mode 100644 index 00000000..58dfaa38 --- /dev/null +++ b/specification/archSpec/base/example-conref-conaction-pushbefore.dita @@ -0,0 +1,47 @@ + + + + Example: Using <xmlatt>conaction</xmlatt> to push content before another element + In this scenario, a conref and conaction are used to + push content before an element in another topic. + +

Consider the following topic, which is set up to push a step before a step in another topic. + It needs to use two step elements to set up the reuse. The referencing element itself uses + conaction="mark" to mark the referenced element. The element to be pushed + immediately preceeds the marking element and uses conaction="pushbefore": + <steps> + <step conaction="pushbefore"> + <cmd>Do this before B</cmd> + </step> + <step conaction="mark" conref="example.dita#example/b"> + <cmd/> + </step> +</steps>

+

The referenced element is in the file example.dita, which looks like + this before a processor resolves the + reference:<task id="example" xml:lang="en"> + <title>Example topic</title> + <taskbody> + <steps> + <step id="a"><cmd>A</cmd></step> + <step id="b"><cmd>B</cmd></step> + <step id="c"><cmd>C</cmd></step> + </steps> + </taskbody> +</task>

+

After the content reference is resolved, the document example.dita + includes the pushed step element before the step with + id set to + b:<task id="example" xml:lang="en"> + <title>Example topic</title> + <taskbody> + <steps> + <step id="a"><cmd>A</cmd></step> + <step><cmd>Do this before B</cmd></step> + <step id="b"><cmd>B</cmd></step> + <step id="c"><cmd>C</cmd></step> + </steps> + </taskbody> +</task>

+ + diff --git a/specification/archSpec/base/example-conref-conaction-replace.dita b/specification/archSpec/base/example-conref-conaction-replace.dita new file mode 100644 index 00000000..e72bfeb7 --- /dev/null +++ b/specification/archSpec/base/example-conref-conaction-replace.dita @@ -0,0 +1,45 @@ + + + + Example: Using <xmlatt>conaction</xmlatt> to replace content + In this scenario, a conref and conaction are used to + replace content in another topic. + +

Consider the following task in example.dita that has the + id attribute set to example. The task contains a + step element with the id set to + b:

+ <task id="example" xml:lang="en"> + <title>Example topic</title> + <taskbody> + <steps> + <step id="a"><cmd>A</cmd></step> + <step id="b"><cmd>B</cmd></step> + <step id="c"><cmd>C</cmd></step> + </steps> + </taskbody> +</task> +

In order to replace the step with id="b", another topic must combine a + conaction value of pushreplace with a + conref attribute that references this + step:<!-- Steps element within another task --> +<steps> + <step conaction="pushreplace" + conref="example.dita#example/b"> + <cmd>Updated B</cmd> + </step> +</steps> +</task>

+

The result will be an updated version of example.dita which contains the + pushed step:<task id="example" xml:lang="en"> + <title>Example topic</title> + <taskbody> + <steps> + <step id="a"><cmd>A</cmd></step> + <step id="b"><cmd>Updated B</cmd></step> + <step id="c"><cmd>C</cmd></step> + </steps> + </taskbody> +</task>

+ + diff --git a/specification/archSpec/base/example-conref-conkeyref.dita b/specification/archSpec/base/example-conref-conkeyref.dita new file mode 100644 index 00000000..c5d6d3da --- /dev/null +++ b/specification/archSpec/base/example-conref-conkeyref.dita @@ -0,0 +1,62 @@ + + + + Example: Simple <xmlatt>conkeyref</xmlatt> usage + In this scenario, a conkeyref attribute is used as an indirect + reference to pull content from the referenced element in another topic. + +

Consider the following topic:

+ <task id="setup-widget" xml:lang="en"> + <title>Setting up the widget</title> + <taskbody> + <steps> + <step><cmd>Turn the widget on for the first time.</cmd></step> + <step><cmd>Follow the prompts to select your language and region.</cmd></step> + <step conkeyref="reuselibrary/setup-profile"><cmd></cmd></step> + <step><cmd>Step outside and activate the widget.</cmd></step> + </steps> + </taskbody> +</task> +

The key is defined as a reference to a resue library:

+ <map> + <title>Key definitions</title> + <keydef keys="reuselibrary" href="reuse-library.dita"/> + <!-- ... --> +</map> +

The library topic reuse-library.dita is set up as follows:

+ <task id="reuse-library" xml:lang="en"> + <title>Reuse library topic</title> + <taskbody> + <steps> + <!-- ... other steps used across tasks ... --> + <step id="setup-profile"> + <cmd>Follow the prompts to set up your name and contact information.</cmd> + <info>Contact information is optional, but recommended.</info> + </step> + </steps> + </taskbody> +</task> +

When the conkeyref attribute is resolved, the key resolves to the topic + that contains the referenced ID setup-profile. The result is the same as if + the original topic contained + conref="reuse-library.dita#reuse-library/setup-profile" instead of + conkeyref="reuselibrary/setup-profile". However, the indirection created by + using a key allows this reference to resolve differently in other contexts.

+

The processed version of the original topic will include content from the referenced + element:

+ <task id="setup-widget" xml:lang="en"> + <title>Setting up the widget</title> + <taskbody> + <steps> + <step><cmd>Turn the widget on for the first time.</cmd></step> + <step><cmd>Follow the prompts to select your language and region.</cmd></step> + <step> + <cmd>Follow the prompts to set up your name and contact information.</cmd> + <info>Contact information is optional, but recommended.</info> + </step> + <step><cmd>Step outside and activate the widget.</cmd></step> + </steps> + </taskbody> +</task> + + diff --git a/specification/archSpec/base/example-conref-includes-xref-and-keyscope.dita b/specification/archSpec/base/example-conref-includes-xref-and-keyscope.dita new file mode 100644 index 00000000..7d6b4f64 --- /dev/null +++ b/specification/archSpec/base/example-conref-includes-xref-and-keyscope.dita @@ -0,0 +1,53 @@ + + + + Example: Resolving conrefs to elements that contain cross references, with key + scopes + In this scenario, elements referenced by conref include cross references using a + variety of referencing styles. The topics themselves are used in a map that makes use of key + scopes. + +

Consider the following paragraphs in paras-01.dita that are intended to + be used by reference from other topics:

+ <topic id="paras-01"> + <title>Reusable paragraphs</title> + <body> + <p id="p1">See <xref href="#paras-01/p5"/>.</p> + <p id="p2">See <xref href="topic-02.dita#topic02/fig-01"/>.</p> + <p id="p3">See <xref href="#./p5"/>.</p> + <p id="p4">See <xref keyref="task-remove-cover"/>.</p> + <p id="p5">Paragraph 5 in paras-01.</p> + </body> +</topic> +

The paragraphs are used by content reference from other topics, including the + using-topic-01.dita topic:

+ <topic id="using-topic-01"><title>Using topic one</title> + <body> + <p id="A" conref="paras-01.dita#paras-01/p1"/> + <p id="B" conref="paras-01.dita#paras-01/p2"/> + <p id="C" conref="paras-01.dita#paras-01/p3"/> + <p id="D" conref="paras-01.dita#paras-01/p4"/> + <p id="p5">Paragraph 5 in using-topic-01</p> + </body> +</topic> +

Now consider the following map, which uses each of the topics above:<map> + <topicgroup keyscope="product-1"> + <topicref keys="task-remove-cover" href="prod-1-task-remove-cover.dita"/> + <topicref href="using-topic-01.dita"/> + </topicgroup> + <topicgroup keyscope="product-2"> + <topicref keys="task-remove-cover" href="prod-2-task-remove-cover.dita"/> + <topicref href="using-topic-01.dita"/> + </topicgroup> +</map>

+

The map establishes two key scopes: "product-1" and "product-2". Within the map branches, the + key name "task-remove-cover" is bound to a different topic. The topic + using-topic-01.dita, which includes a conref to a paragraph that + includes a cross reference to the key name "task-remove-cover", is also referenced in each + branch. When each branch is rendered, the target of the cross reference is different.

+

In the first branch with the key scope set to "product-1", the cross reference from paragraph + p4 is resolved to prod-1-task-remove-cover.dita. In the second branch + with the key scope set to "product-2", the cross reference from paragraph p4 is resolved to + prod-2-task-remove-cover.dita.

+ + diff --git a/specification/archSpec/base/example-conref-includes-xref.dita b/specification/archSpec/base/example-conref-includes-xref.dita new file mode 100644 index 00000000..e76ab880 --- /dev/null +++ b/specification/archSpec/base/example-conref-includes-xref.dita @@ -0,0 +1,82 @@ + + + + Example: Resolving conrefs to elements that contain cross references + In this scenario, elements referenced by conref include cross references using a + variety of referencing styles. + +

Consider the following paragraphs in paras-01.dita that are intended to + be used by reference from other topics:

+ <topic id="paras-01"> + <title>Reusable paragraphs</title> + <body> + <p id="p1">See <xref href="#paras-01/p5"/>.</p> + <p id="p2">See <xref href="topic-02.dita#topic02/fig-01"/>.</p> + <p id="p3">See <xref href="#./p5"/>.</p> + <p id="p4">See <xref keyref="task-remove-cover"/>.</p> + <p id="p5">Paragraph 5 in paras-01.</p> + </body> +</topic> +

The paragraphs are used by content reference from other topics, including the + using-topic-01.dita topic:

+ <topic id="using-topic-01"><title>Using topic one</title> + <body> + <p id="A" conref="paras-01.dita#paras-01/p1"/> + <p id="B" conref="paras-01.dita#paras-01/p2"/> + <p id="C" conref="paras-01.dita#paras-01/p3"/> + <p id="D" conref="paras-01.dita#paras-01/p4"/> + <p id="p5">Paragraph 5 in using-topic-01</p> + </body> +</topic> +

Processors must consider different contexts when resolving xref + references within the referenced paragraphs. The rendered cross references in + using-topic-01.dita are shown in the following table.

+ + + Paragraph + Value of id attribute on conrefed paragraph + xref within conrefed paragraph + Resolution + + + A + p1 + <xref href="#paras-01/p5"/> + The cross reference in paragraph p1 is a direct URI reference that does not contain + a same-topic fragment identifier. It can be resolved only to paragraph p5 in + paras-01.dita, which contains the content "Paragraph 5 in + paras-01". + + + B + p2 + <xref href="topic-02.dita#topic02/fig-01"/> + The cross reference in paragraph p2 is a direct URI reference. It can be resolved + only to the element with id="fig-01" in + topic-02.dita. + + + C + p3 + <xref href="#./p5"/> + +

The cross reference in paragraph p3 is a direct URI reference that contains a + same-topic fragment identifier. Because the URI reference contains a same-topic fragment + identifier, the reference is resolved in the context of the referencing topic + (using-topic-01.dita).

+

If using-topic-01.dita did not contain an element with + id="p5", then the conref to paragraph p3 would result in a link + resolution failure.

+ + + + D + p4 + <xref keyref="task-remove-cover"/> + The cross reference in paragraph p4 is a key reference. It is resolved to whatever + resource is bound to the key name "task-remove-cover" in the applicable map + context. + + + + diff --git a/specification/archSpec/base/example-conref-range-blocks.dita b/specification/archSpec/base/example-conref-range-blocks.dita new file mode 100644 index 00000000..7a588c09 --- /dev/null +++ b/specification/archSpec/base/example-conref-range-blocks.dita @@ -0,0 +1,62 @@ + + + + Example: Reusing a sequence of elements of different types + In this scenario, a conref and conrefend are used + to reference a range of block elements that do not have the same element type. + +

In the following code sample, we have a library topic that defines several elements, + including paragraphs and lists. Each block element has an id attribute, + making it possible to reuse them individually or as ranges.

+ + Source <filepath>topic.dita</filepath> with ids + <topic id="x"> + <title>Library file topic.dita</title> + <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> + +

In the following sample, the referencing element is a paragraph. It references a starting + paragraph and an ending paragraph, which defines a range that includes those paragraphs along + with everything that falls between them.

+ + Referencing the starting and ending paragraphs + <topic id="y"> + <title>Sample file reusing content</title> + <body> + <p conref="topic.dita#x/p1" conrefend="topic.dita#x/p2"/> + </body> +</topic> + +

In the resolved topic, all list items from the starting paragraph to the ending paragraph are + pulled in to replace the referencing element. The id attributes on the + referenced elements are not preserved, but any id attributes on intermediate + elements are preserved.

+ + Block level example: Processed result of reusing topic + <topic id="y"> + <title>Sample file reusing content</title> + <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> + + + diff --git a/specification/archSpec/base/example-conref-range-conkeyref.dita b/specification/archSpec/base/example-conref-range-conkeyref.dita new file mode 100644 index 00000000..e194f529 --- /dev/null +++ b/specification/archSpec/base/example-conref-range-conkeyref.dita @@ -0,0 +1,67 @@ + + + + Example: Reusing a range with <xmlatt>conkeyref</xmlatt> + In this scenario, a conkeyref is used to define the start of a range + and conrefend is used to define the end of a range. + +

In the following sample, the key xmp is defined as the first topic in the + file examples.dita.

+ + Defining and referencing a key with <xmlatt>conkeyref</xmlatt> + <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> + +

To reuse these list items by using the key, the 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.

+ + Combining <xmlatt>conref</xmlatt>, <xmlatt>conkeyref</xmlatt>, and + <xmlatt>conrefend</xmlatt> +

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"/> +
    +
  • If the key thisconfig is defined as + mySpecialConfig.dita#myconfig, then the range will go from the list + item with id="start" to the list item withid="end" in + the topic mySpecialConfig.dita#myconfig.
    • +
  • If the key thisconfig is defined as myConfig.dita, + then the range will go from the list item with id="start" to the list + item with id="end" within the first topic in + myConfig.dita.
    • +
  • If the key thisconfig is not defined, then the unchanged + 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.
    • +
+ + + diff --git a/specification/archSpec/base/example-conref-range-list.dita b/specification/archSpec/base/example-conref-range-list.dita new file mode 100644 index 00000000..6d217ad2 --- /dev/null +++ b/specification/archSpec/base/example-conref-range-list.dita @@ -0,0 +1,61 @@ + + + + Example: Reusing a sequence of list items + In this scenario, a conref and conrefend are used + to reference a range of list items. + +

In the following code sample, we have a library topic that defines a series of list items. + Each list item has an id attribute, making it possible to reuse them + individually or as ranges.

+ + Source document <filepath>topic.dita</filepath> + <topic id="x"> + <title>Sample file topic.dita</title> + <body> + <ol id="list"> + <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> + +

The following topic reuses a range of items from that list, without reusing the entire + list.

+ + Reusing a range of items + <topic id="y"> + <title>Sample file reusing content</title> + <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> + +

In the resolved topic, all list items from the starting "bear" to the ending "dog" are pulled + in to replace the referencing element. The id attributes on the referenced + elements are not preserved, but any id attributes on intermediate elements + are preserved.

+ + Processed result of reusing topic + <topic id="y"> + <title>Sample file reusing content</title> + <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> + + + diff --git a/specification/archSpec/base/example-conref-simple.dita b/specification/archSpec/base/example-conref-simple.dita new file mode 100644 index 00000000..fe03867d --- /dev/null +++ b/specification/archSpec/base/example-conref-simple.dita @@ -0,0 +1,60 @@ + + + + Example: Simple <xmlatt>conref</xmlatt> usage + In this scenario, a conref attribute is used to pull content from + the referenced element in another topic. + +

Consider the following topic:

+ <task id="setup-widget" xml:lang="en"> + <title>Setting up the widget</title> + <taskbody> + <steps> + <step><cmd>Turn the widget on for the first time.</cmd></step> + <step><cmd>Follow the prompts to select your language and region.</cmd></step> + <step conref="reuse-library.dita#reuse/setup-profile"><cmd></cmd></step> + <step><cmd>Step outside and activate the widget.</cmd></step> + </steps> + </taskbody> +</task> +

That topic requires the existence of another topic, + reuse-library.dita:

+ <task id="reuse-library" xml:lang="en"> + <title>Reuse library topic</title> + <taskbody> + <steps> + <!-- ... other steps used across tasks ... --> + <step id="setup-profile"> + <cmd>Follow the prompts to set up your name and contact information.</cmd> + <info>Contact information is optional, but recommended.</info> + </step> + </steps> + </taskbody> +</task> +

These topics highlight some important things to remember when using + conref attributes:

    +
  • The attribute includes both the ID of the referenced topic and the ID of the + referenced element.
    • +
  • When an element with a conref attribute has required child + elements, those child elements must still be specified. The use of DITA's + conref attribute does not override the XML rules that + require such child elements.
    • +

+

When the conref attribute is resolved, the processed version of the + original topic will include content from the referenced element:

+ <task id="setup-widget" xml:lang="en"> + <title>Setting up the widget</title> + <taskbody> + <steps> + <step><cmd>Turn the widget on for the first time.</cmd></step> + <step><cmd>Follow the prompts to select your language and region.</cmd></step> + <step> + <cmd>Follow the prompts to set up your name and contact information.</cmd> + <info>Contact information is optional, but recommended.</info> + </step> + <step><cmd>Step outside and activate the widget.</cmd></step> + </steps> + </taskbody> +</task> + + diff --git a/specification/archSpec/base/examples-conref.dita b/specification/archSpec/base/examples-conref.dita new file mode 100644 index 00000000..60a71769 --- /dev/null +++ b/specification/archSpec/base/examples-conref.dita @@ -0,0 +1,7 @@ + + + + Examples of conref + This section contains examples and scenarios that illustrate the use and processing + of conref and related content-referencing attributes. + From a482745bba57d2ba228fee4c9116c6928eac8424 Mon Sep 17 00:00:00 2001 From: "Robert D. Anderson" Date: Fri, 13 Sep 2024 11:43:34 -0500 Subject: [PATCH 2/2] Revising conref topics ahead of review --- ...nref-attributes-specified-on-elements.dita | 2 +- .../archSpec/base/conref-overview.dita | 17 +- .../archSpec/base/conref-processing.dita | 62 ++++- specification/archSpec/base/conref.dita | 8 +- specification/archSpec/base/conref.ditamap | 18 +- ...andling-xref-and-conref-within-topics.dita | 107 +------- .../archSpec/base/theconactionattribute.dita | 157 +++--------- .../archSpec/base/theconkeyrefattribute.dita | 33 +-- .../archSpec/base/theconrefattribute.dita | 14 +- .../archSpec/base/theconrefendattribute.dita | 229 +----------------- specification/common/conref-file.dita | 11 +- 11 files changed, 153 insertions(+), 505 deletions(-) diff --git a/specification/archSpec/base/conref-attributes-specified-on-elements.dita b/specification/archSpec/base/conref-attributes-specified-on-elements.dita index 4b0a21b4..312c5b45 100644 --- a/specification/archSpec/base/conref-attributes-specified-on-elements.dita +++ b/specification/archSpec/base/conref-attributes-specified-on-elements.dita @@ -52,7 +52,7 @@ originating context, even if they are not valid in an intermediate context.

For example, if topic A and topic C allow highlighting, and topic B does not, then a content reference chain of topic A-to-topic B-to-topic C should preserve any - highlighting elements in the referenced content. The result, however it is achieved, must be + highlighting elements in the referenced content. The result, however it is achieved, is equivalent to the result of resolving the conref pairs recursively starting from the original referencing element in topic A.

diff --git a/specification/archSpec/base/conref-overview.dita b/specification/archSpec/base/conref-overview.dita index 4eee8b61..32df80c9 100644 --- a/specification/archSpec/base/conref-overview.dita +++ b/specification/archSpec/base/conref-overview.dita @@ -35,19 +35,18 @@
Pushing content from the referencing element

The conaction attribute reverses the direction of reuse from pull to - push. With a push, the referencing element is rendered before, - after, or in place of the referenced element. The location (before, after, or in place - of) is determined by the value of the conaction attribute. - Because the conaction and conrefend attributes cannot - both be used within the same referencing element, it is not possible to push a range of - elements.

+ push. With a push, the referencing element is rendered before, after, or in place of the + referenced element. The location (before, after, or in place of) is determined by the + value of the conaction attribute. The conaction and + conrefend attributes cannot both be used within the same referencing + element, so it is not possible to push a range of elements.

A fragment of DITA content, such as an XML document that contains only a single paragraph - without a topic ancestor, does not contain enough information for the conref processor to be - able to determine the validity of a reference to it. Consequently, the value of a conref must - specify one of the following items:

+ without a topic ancestor, does not contain enough information for a conref processor to be + able to determine the validity of a reference to it. Consequently, the value of a + conref attribute must be one of the following items: