Skip to content

Commit

Permalink
Revising conref topics ahead of review
Browse files Browse the repository at this point in the history
  • Loading branch information
@robander
robander committed Sep 13, 2024
1 parent 1c47811 commit a482745
Show file tree
Hide file tree
Showing 11 changed files with 153 additions and 505 deletions.
2 changes: 1 addition & 1 deletion specification/archSpec/base/conref-attributes-specified-on-elements.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
originating context, even if they are not valid in an intermediate context. </p>
<p otherprops="examples">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.</p>
</conbody>
Expand Down
17 changes: 8 additions & 9 deletions specification/archSpec/base/conref-overview.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,19 +35,18 @@
<dt>Pushing content from the referencing element</dt>
<dd>
<p>The <xmlatt>conaction</xmlatt> attribute reverses the direction of reuse from pull to
push. <ph >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 <xmlatt>conaction</xmlatt> attribute.</ph>
Because the <xmlatt>conaction</xmlatt> and <xmlatt>conrefend</xmlatt> attributes cannot
both be used within the same referencing element, it is not possible to push a range of
elements.</p>
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 <xmlatt>conaction</xmlatt> attribute. The <xmlatt>conaction</xmlatt> and
<xmlatt>conrefend</xmlatt> attributes cannot both be used within the same referencing
element, so it is not possible to push a range of elements.</p>
</dd>
</dlentry>
</dl>
<p>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:</p>
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
<xmlatt>conref</xmlatt> attribute must be one of the following items:</p>
<ul>
<li>A referenced element within a DITA map</li>
<li>A referenced element within a DITA topic</li>
Expand Down
62 changes: 58 additions & 4 deletions specification/archSpec/base/conref-processing.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@
</prolog>
<conbody>
<note>The DITA <xmlatt>conref</xmlatt> attribute is a transclusion mechanism similar to XInclude
and to HyTime value references. DITA differs from these mechanisms, however, in that conref
validity does not apply simply to the current content at the time of replacement, but to the
possible content given the restrictions of both the referencing document type and the referenced
document type.</note>
and to HyTime value references. DITA differs from these mechanisms, however, in that conref
validity does not apply simply to the current content at the time of replacement, but to the
possible resolved content given the restrictions of both the referencing document type and the
referenced document type.</note>
<p>When content is reused between two documents with different domains or constraints, it is
possible for the reused content to include domain extensions that are not defined for the new
context, or to include elements that would be constrained out of the new context. When pulling
Expand All @@ -33,5 +33,59 @@
<p>A conref processor <term outputclass="RFC-2119">SHOULD NOT</term> permit resolution of a reuse
relationship that could be rendered invalid under the rules of either the reused or reusing
content.</p>
<p>When resolving <xmlatt>conkeyref</xmlatt> attributes, processors <term outputclass="RFC-2119"
>SHOULD</term> issue a warning when a <xmlatt>conkeyref</xmlatt> reference cannot be
resolved and there is no <xmlatt>conref</xmlatt> attribute to use as a fallback. Processors
<term outputclass="RFC-2119">MAY</term> issue a warning when a <xmlatt>conkeyref</xmlatt>
cannot be resolved to an element and a specified <xmlatt>conref</xmlatt> is used as a
fallback.</p>
<section id="error-conditions" outputclass="errorcondition">
<title>Common error conditions related to conref ranges</title>
<p>When encountering the following error conditions, an implementation can optionally issue an
error message.</p>
<table id="table_pbn_czf_scc">
<tgroup cols="2">
<colspec colname="col1" colnum="1" colwidth="1*"/>
<colspec colname="col2" colnum="2" colwidth="1*"/>
<thead>
<row>
<entry colname="col1">Condition or Issue</entry>
<entry colname="col2">Result</entry>
</row>
</thead>
<tbody>
<row>
<entry colname="col1">The <xmlatt>conref</xmlatt> attribute cannot be resolved in the
target document (the target element might have been removed or its id has changed). </entry>
<entry colname="col2">The <xmlatt>conref</xmlatt> is ignored.</entry>
</row>
<row>
<entry colname="col1">The <xmlatt>conrefend</xmlatt> attribute cannot be resolved in
the target document (the target element might have been removed or its id has
changed).</entry>
<entry colname="col2">Range cannot be resolved, optional recovery processes the result
as a simple conref.</entry>
</row>
<row>
<entry colname="col1">Start and end elements are not siblings in the target
document.</entry>
<entry colname="col2">If the start element exists, optional recovery processes the
result as a simple conref. </entry>
</row>
<row>
<entry colname="col1">End element occurs before the start element in the target
document.</entry>
<entry colname="col2">If the start element exists, optional recovery processes the
result as a simple conref.</entry>
</row>
<row>
<entry colname="col1">An element has a <xmlatt>conrefend</xmlatt> attribute but is
missing the <xmlatt>conref</xmlatt> attribute.</entry>
<entry colname="col2">No result.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</conbody>
</concept>
8 changes: 4 additions & 4 deletions specification/archSpec/base/conref.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conref" xml:lang="en-us">
<title>Content <ph >reference</ph> (conref)</title>
<shortdesc >The DITA conref attributes provide mechanisms for reusing content.
DITA content references support reuse scenarios that are difficult or impossible to implement
using other XML-based inclusion mechanisms like XInclude and entities. Additionally, DITA content
references have rules that help ensure that the results of content inclusion remain valid after
<shortdesc>The DITA conref attributes provide mechanisms for reusing content. DITA content
references support reuse scenarios that are difficult or impossible to implement using many
XML-based inclusion mechanisms like XInclude and entities. Additionally, DITA content references
have rules that help ensure that the results of content inclusion remain valid after
resolution</shortdesc>
<prolog>
<metadata>
Expand Down
18 changes: 15 additions & 3 deletions specification/archSpec/base/conref.ditamap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,26 @@
<title>Content reference (conref)</title>
<topicref href="conref.dita" keys="conref">
<topicref href="conref-overview.dita"/>
<topicref keyref="attributes-conref"/>
<topicref keyref="attributes-conkeyref"/>
<topicref keyref="attributes-conrefend"/>
<topicref keyref="attributes-conaction"/>
<topicref keyref="attributes-conrefend"/>
<topicref keyref="attributes-conkeyref"/>
<topicref keyref="attributes-conref"/>
<topicref keyref="attributes-useconreftarget"/>
<topicref href="conref-processing.dita"/>
<topicref href="conref-attributes-specified-on-elements.dita"/>
<topicref href="handling-xref-and-conref-within-topics.dita"/>
<topicref href="examples-conref.dita">
<topicref href="example-conref-simple.dita"/>
<topicref href="example-conref-conkeyref.dita"/>
<topicref href="example-conref-range-list.dita"/>
<topicref href="example-conref-range-blocks.dita"/>
<topicref href="example-conref-range-conkeyref.dita"/>
<topicref href="example-conref-conaction-replace.dita"/>
<topicref href="example-conref-conaction-pushbefore.dita"/>
<topicref href="example-conref-conaction-pushafter.dita"/>
<topicref href="example-conref-includes-xref.dita"/>
<topicref href="example-conref-includes-xref-and-keyscope.dita"/>
</topicref>
</topicref>
<reltable title="Source&lt;-->Target">
<relheader>
Expand Down
107 changes: 3 additions & 104 deletions specification/archSpec/base/handling-xref-and-conref-within-topics.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,109 +62,8 @@
same-topic fragment identifier is resolved in the context of the topic that contains the
content reference, and a key reference is resolved in the context of the key scope that is in
effect for each use of the topic that contains the content reference. </p>
<note>In the case of same-topic fragment identifiers, it is the responsibility of the author of
the content reference to ensure that any element IDs that are specified in same-topic fragment
identifiers in the referenced content will also be available in the referencing topic at
resolution time.</note>
<example id="example" otherprops="examples">
<title>Example: Resolving conrefs to elements that contain cross references</title>
<p>Consider the following paragraphs in <filepath>paras-01.dita</filepath> that are intended
to be used by reference from other topics:</p>
<codeblock>&lt;topic id="paras-01">&lt;title>Reusable paragraphs&lt;/title>
&lt;body>
&lt;p id="p1">See &lt;xref href="#paras-01/p5"/>.&lt;/p>
&lt;p id="p2">See &lt;xref href="topic-02.dita#topic02/fig-01"/>.&lt;/p>
&lt;p id="p3">See &lt;xref href="#./p5"/>.&lt;/p>
&lt;p id="p4">See &lt;xref keyref="task-remove-cover"/>.&lt;/p>
&lt;p id="p5">Paragraph 5 in paras-01.&lt;/p>
&lt;/body>
&lt;/topic></codeblock>
<p>The paragraphs are used by content reference from other topics, including the
<filepath>using-topic-01.dita</filepath> topic:</p>
<codeblock>&lt;topic id="using-topic-01">&lt;title>Using topic one&lt;/title>
&lt;body>
&lt;p id="A" conref="paras-01.dita#paras-01/p1"/>
&lt;p id="B" conref="paras-01.dita#paras-01/p2"/>
&lt;p id="C" conref="paras-01.dita#paras-01/p3"/>
&lt;p id="D" conref="paras-01.dita#paras-01/p4"/>
&lt;p id="p5">Paragraph 5 in using-topic-01&lt;/p>
&lt;/body>
&lt;/topic></codeblock>
<p>Following resolution of the content references and processing of the
<xmlelement>xref</xmlelement> elements in the referenced paragraphs, the rendered cross
references in <filepath>using-topic-01.dita</filepath> are <ph >shown
in the following table</ph>.</p>
<simpletable frame="all" relcolwidth="1.0* 1.0* 2.0* 3.0*">
<sthead>
<stentry>Paragraph</stentry>
<stentry>Value of <xmlatt>id</xmlatt> attribute on conrefed paragraph</stentry>
<stentry><xmlelement>xref</xmlelement> within conrefed paragraph</stentry>
<stentry>Resolution</stentry>
</sthead>
<strow>
<stentry>A</stentry>
<stentry>p1</stentry>
<stentry><codeph>&lt;xref href="#paras-01/p5"/></codeph></stentry>
<stentry>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
<filepath>paras-01.dita</filepath>, which contains the content "Paragraph 5 in
paras-01".</stentry>
</strow>
<strow>
<stentry>B</stentry>
<stentry>p2</stentry>
<stentry><codeph>&lt;xref href="topic-02.dita#topic02/fig-01"/></codeph></stentry>
<stentry>The cross reference in paragraph p2 is a direct URI reference. It can be resolved
only to the element with <codeph>id="fig-01"</codeph> in
<filepath>topic-02.dita</filepath>.</stentry>
</strow>
<strow>
<stentry>C</stentry>
<stentry>p3</stentry>
<stentry><codeph>&lt;xref href="#./p5"/></codeph></stentry>
<stentry>
<p>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
(<filepath>using-topic-01.dita</filepath>). </p>
<p>If <filepath>using-topic-01.dita</filepath> did not contain an element with
<codeph>id="p5"</codeph>, then the conref to paragraph p3 would result in a link
resolution failure.</p>
</stentry>
</strow>
<strow>
<stentry>D</stentry>
<stentry>p4</stentry>
<stentry><codeph>&lt;xref keyref="task-remove-cover"/></codeph></stentry>
<stentry>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.</stentry>
</strow>
</simpletable>
</example>
<example id="example-w-scoped-keys" otherprops="examples">
<title>Example: Resolving conrefs to elements that contain key-based cross references </title>
<p >Consider the following map, which uses the topics from the previous
example:</p>
<codeblock>&lt;map>
&lt;topicgroup keyscope="product-1">
&lt;topicref keys="task-remove-cover" href="prod-1-task-remove-cover.dita"/>
&lt;topicref href="using-topic-01.dita"/>
&lt;/topicgroup>
&lt;topicgroup keyscope="product-2">
&lt;topicref keys="task-remove-cover" href="prod-2-task-remove-cover.dita"/>
&lt;topicref href="using-topic-01.dita"/>
&lt;/topicgroup>
&lt;/map></codeblock>
<p>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
<filepath>using-topic-01.dita</filepath>, 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.</p>
<p>In the first branch with the key scope set to "product-1", the cross reference from
paragraph p4 is resolved to <filepath>prod-1-task-remove-cover.dita</filepath>. In the
second branch with the key scope set to "product-2", the cross reference from paragraph p4
is resolved to <filepath>prod-2-task-remove-cover.dita</filepath>.</p>
</example>
<note>In the case of same-topic fragment identifiers, the author of the content reference needs
to ensure that any element IDs that are specified in same-topic fragment identifiers in the
referenced content will also be available in the referencing topic at resolution time.</note>
</conbody>
</concept>
Loading

0 comments on commit a482745

Please sign in to comment.