Skip to content

Commit

Permalink
Merge pull request #946 from robander/conref-reorg
Browse files Browse the repository at this point in the history 
Reworking conref attribute topics
  • Loading branch information
@robander
robander authored Nov 26, 2024
2 parents 8c70853 + 9ea6478 commit c7adb2d
Show file tree
Hide file tree
Showing 4 changed files with 64 additions and 49 deletions.
74 changes: 43 additions & 31 deletions specification/archSpec/base/theconactionattribute.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"concept.dtd">
<concept id="theconactionattribute" xml:lang="en-us">
<title>The <xmlatt>conaction</xmlatt> attribute</title>
<title rev="review-ella">Pushing reusable content to a new location</title>
<shortdesc>The <xmlatt>conaction</xmlatt> attribute allows users to push content from one location
into another. It causes the <xmlatt>conref</xmlatt> attribute to work in reverse, so that
content is pushed from the referencing element into another location, rather than pulled from
Expand All @@ -16,18 +16,24 @@
</prolog>
<conbody>
<note>In the descriptions below, the word <i>target</i> always refers to the element referenced by a
<xmlatt>conref</xmlatt> attribute.</note><p>There are three possible functions using the <xmlatt>conaction</xmlatt> attribute: replacing an
element, pushing content before an element, and pushing content after an element. The
<xmlatt>conaction</xmlatt> attribute always declares the desired function while the
<xmlatt>conref</xmlatt> attribute provides the target of the reference using the standard
<xmlatt>conref</xmlatt> syntax.</p><p>In each case, an element pushed using <xmlatt>conref</xmlatt> must be of the same type as, or
more specialized than, its target. If the pushed element is more specialized than the
target, then it should be generalized when the <xmlatt>conref</xmlatt> is resolved. This
ensures that the content will be valid in the target topic.</p><ul>
<li>It is valid to push using <xmlatt>conref</xmlatt> when the two elements involved are of the same
type. For example, a <xmlelement>step</xmlelement> element can use the conref push feature
with another <xmlelement>step</xmlelement> as the target of the
<xmlatt>conref</xmlatt>.</li>
<xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute.</note><p>There are three possible functions using the <xmlatt>conaction</xmlatt> attribute: replacing an
element, pushing content before an element, <ph rev="review-ella">or</ph> pushing content
after an element. The <xmlatt>conaction</xmlatt> attribute always declares the desired
function while the <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute provides the target of the
reference <ph rev="review-ella">using standard syntax for that attribute</ph>.</p><p>In each case, an element pushed using <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph>must be of the same type as, or more
specialized than, its target. If the pushed element is more specialized than the target, then
it should be generalized when the <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> is resolved. This ensures that the
content will be valid in the target topic.</p><ul>
<li>It is valid to push using <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> when the two elements involved are
of the same type. For example, a <xmlelement>step</xmlelement> element can use the conref
push feature with another <xmlelement>step</xmlelement> as the target of the
<xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph>.</li>
<li>The target element can be more general than the source. For example, it is legal to push a
<xmlelement>step</xmlelement> element to replace a general list item
(<xmlelement>li</xmlelement>); the <xmlelement>step</xmlelement> element should be
Expand All @@ -41,26 +47,31 @@
<title>Replacing content in another topic</title>
<p>When the <xmlatt>conaction</xmlatt> attribute is set to <keyword>pushreplace</keyword>, the
referencing element will replace the referenced element specified by the
<xmlatt>conref</xmlatt> attribute. The pushed content remains in the source topic where it
was originally authored.</p>
<xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute. The pushed content
remains in the source topic where it was originally authored.</p>
<p>When resolving a conref push action, attributes are resolved using the same precedence as
for normal <xmlatt>conref</xmlatt>, with one exception. Attributes on the element with the
<xmlatt>conref</xmlatt> attribute (in this case, the source doing the push) will take
priority over those on the referenced element. The exception is that if the source element
does not specify an ID, the ID on the referenced element remains; if the source element does
specify an ID then that replaces the ID on the referenced element.</p>
<xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute (in this case, the source
doing the push) will take priority over those on the referenced element. The exception is
that if the source element does not specify an ID, the ID on the referenced element remains;
if the source element does specify an ID then that replaces the ID on the referenced
element.</p>
<p outputclass="errorcondition">It is an error for two source topics to replace the same
element. Applications <term outputclass="RFC-2119">MAY</term> warn users if more than one
element attempts to replace a single target.</p>
</section>
<section id="pushing-content">
<title>Pushing content before or after another element</title>
<p>Setting the <xmlatt>conaction</xmlatt> attribute to <keyword>pushbefore</keyword> allows an
element to be pushed before the element referenced by the <xmlatt>conref</xmlatt> attribute.
Likewise, setting the <xmlatt>conaction</xmlatt> attribute to <keyword>pushafter</keyword>
allows an element to be pushed after the element referenced by the <xmlatt>conref</xmlatt>
attribute. Multiple sources can push content before or after the same referenced element;
the order in which that content is pushed is undefined.</p>
element to be pushed before the element referenced by the <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute. Likewise, setting the
<xmlatt>conaction</xmlatt> attribute to <keyword>pushafter</keyword> allows an element to
be pushed after the element referenced by the <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute. Multiple sources can
push content before or after the same referenced element; the order in which that content is
pushed is undefined.</p>
<p>When an element is pushed before or after a referenced element, the resulting document will
have at least two of that element. Because this is not always valid, a document attempting
to push content before or after a target must take an extra step to ensure that the result
Expand All @@ -69,13 +80,14 @@
<xmlelement>body</xmlelement> element before or after another
<xmlelement>body</xmlelement> element, because it is not valid to have two body elements
in sequence.</p>
<p>When pushing before, the <xmlatt>conref</xmlatt> attribute itself looks just as it did when
replacing, but the <xmlatt>conaction</xmlatt> attribute is set to <keyword>mark</keyword>
because it is marking the referenced element. This element remains empty; its purpose is to
ensure that it is legal to have more than one of the current element. The element
immediately before the marking element is the content that will actually be pushed. This
element will set the <xmlatt>conaction</xmlatt> attribute to
<keyword>pushbefore</keyword>.</p>
<p>When pushing before, the <xmlatt>conref</xmlatt>
<ph rev="review-ella">or <xmlatt>conkeyref</xmlatt></ph> attribute itself looks just as it
did when replacing, but the <xmlatt>conaction</xmlatt> attribute is set to
<keyword>mark</keyword> because it is marking the referenced element. This element remains
empty; its purpose is to ensure that it is legal to have more than one of the current
element. The element immediately before the marking element is the content that will
actually be pushed. This element will set the <xmlatt>conaction</xmlatt> attribute to
<keyword>pushbefore</keyword>.</p>
<p>When pushing after, the procedure is the same, except that the order of the elements is
reversed. The element with <codeph>conaction="pushafter"</codeph> comes immediately after
the element which marks the target.</p>
Expand Down
11 changes: 6 additions & 5 deletions specification/archSpec/base/theconkeyrefattribute.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"concept.dtd">
<concept id="theconkeyrefattribute" xml:lang="en-us">
<title>The <xmlatt>conkeyref</xmlatt> attribute</title>
<title rev="review-ella">Indirect key-based content reuse</title>
<shortdesc>The <xmlatt>conkeyref</xmlatt> attribute provides an indirect content reference to
topic elements, map elements, or elements within maps or topics. It allows the referencing
element to use a key in place of a file name when referencing another topic or map.</shortdesc>
element to use a key in place of a <ph rev="review-ella">URI reference</ph> when referencing
another topic or map.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -14,13 +15,13 @@
</metadata>
</prolog>
<conbody>
<p>When the target of a content reference is a topic or map, the value of the
<xmlatt>conkeyref</xmlatt> attribute is a key name that directly resolves to that topic or
map.</p>
<p>When the target of a content reference is an element within a topic or map, the value of
the <xmlatt>conkeyref</xmlatt> attribute is a key name, followed by a slash ("/"), followed
by the ID of the referenced element. The key name must be bound to the topic or map that
contains the referenced element.</p>
<p>When the target of a content reference is a topic or map, the value of the
<xmlatt>conkeyref</xmlatt> attribute is a key name that directly resolves to that topic or
map.</p>
<p>When the key name specified by the <xmlatt>conkeyref</xmlatt> attribute is not defined and
the element also specifies a <xmlatt>conref</xmlatt> attribute, the <xmlatt>conref</xmlatt>
attribute is used to determine the referenced element. If no <xmlatt>conref</xmlatt>
Expand Down
7 changes: 4 additions & 3 deletions specification/archSpec/base/theconrefattribute.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"concept.dtd">
<concept id="theconrefattribute" xml:lang="en-us">
<title>The <xmlatt>conref</xmlatt> attribute</title>
<shortdesc>The <xmlatt>conref</xmlatt> attribute is used to reference content that can be reused. It
allows reuse of DITA elements, including topic or map level elements.</shortdesc>
<title rev="review-ella">Direct URI-based content reuse</title>
<shortdesc>The <xmlatt>conref</xmlatt> attribute is used to reference <ph rev="review-ella">reusable
content by URI</ph>. It allows reuse of DITA elements, including <ph rev="review-ella">topic-
or map-based elements</ph>.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand Down
21 changes: 11 additions & 10 deletions specification/archSpec/base/theconrefendattribute.dita
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="theconrefendattribute" xml:lang="en-us">
<title>The <xmlatt>conrefend</xmlatt> attribute</title>
<shortdesc>The <xmlatt>conrefend</xmlatt> attribute is used when referencing a range of elements
with the conref mechanism. The <xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> attribute
references the first element in the range, while <xmlatt>conrefend</xmlatt> references the last
element in the range. </shortdesc>
<title rev="review-ella">Reusing a range of elements</title>
<shortdesc rev="review-ella">The <xmlatt>conrefend</xmlatt> attribute is used in a conref range. A
<xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> attribute references the first element
in the range, while <xmlatt>conrefend</xmlatt> references the last element in the range. </shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -24,14 +23,16 @@
the same parent, and the start element <term outputclass="RFC-2119">MUST</term> precede
the end element in document order.</li>
<li>The parent of the referencing element <term outputclass="RFC-2119">MUST</term> be the
same as the parent of the referenced range or generalizable to the parent of the
referencing element.
same <ph rev="review-ella">type</ph> as the parent of the referenced range or
generalizable to the parent of the referencing element.
<!--For example, it is possible to pull a range from <xmlelement>conbody</xmlelement> into <xmlelement>body</xmlelement>, because <xmlelement>conbody</xmlelement> is generalizable to <xmlelement>body</xmlelement>. It is not possible to pull a range from <xmlelement>body</xmlelement> into <xmlelement>conbody</xmlelement>, because the result <ph>might</ph> not be valid in <xmlelement>conbody</xmlelement>.--></li>
</ul></p><p>In addition, several other items must be taken into account:</p><ul>
<li>Processors will resolve the range by pulling in the starting referenced element and
following sibling XML nodes across to and including the ending referenced element.</li>
<li>As with <xmlatt>conref</xmlatt>, if the <xmlatt>conrefend</xmlatt> references a more
specialized version of the referencing element, applications should generalize the target
following sibling XML nodes <ph rev="review-ella">up</ph> to and including the ending
referenced element.</li>
<li>As with <xmlatt>conref</xmlatt>, if the <xmlatt>conrefend</xmlatt>
<ph rev="review-ella">attribute</ph> references a more specialized version of the
referencing element, applications <ph rev="review-ella">can</ph> generalize the target
when resolving.</li>
<li>As with <xmlatt>conref</xmlatt>, it is not valid to use <xmlatt>conrefend</xmlatt> to
reference a more general version of an element (such as using
Expand Down

0 comments on commit c7adb2d

Please sign in to comment.