Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Review comments from conref arch spec review #942

Merged
merged 1 commit into from
Oct 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions specification/archSpec/base/conref-overview.dita
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conref" xml:lang="en-us">
<title><ph >Conref overview</ph></title>
<title><ph rev="review-ella">Content referencing</ph> overview</title>
<shortdesc><ph conkeyref="reuse-general/conref-shortdesc"/></shortdesc>
<prolog>
<metadata>
Expand All @@ -18,17 +18,18 @@
as defined in <xref href="linking-and-addressing-terms.dita"/>.</p>
<dl>
<dlentry>
<dt>Pulling content to the referencing element</dt>
<dt>Pulling content <ph rev="review-ella">into</ph> the referencing element</dt>
<dd>
<p>When the <xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> attribute is used alone,
the referencing element acts as a placeholder for the referenced element, and the
content of the referenced element is rendered in place of the referencing element.</p>
the referencing element acts as a placeholder for the referenced <ph rev="review-ella"
>element. The</ph> content of the referenced element is rendered in place of the
referencing element.</p>
<p>The combination of the <xmlatt>conrefend</xmlatt> attribute with either
<xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> specifies a range of elements
that is rendered in place of the referencing element. <ph >Although
the start and end elements must be of the same type as the referencing element (or
specialized from that element type), the elements inside the range can be any
type.</ph></p>
that is rendered in place of the referencing element. <ph rev="review-ella">The start
and end elements in a range must be siblings.</ph> Although the start and end elements
must be of the same type as the referencing element (or specialized from that element
type), the elements inside the range can be any type.</p>
</dd>
</dlentry>
<dlentry>
Expand Down
10 changes: 5 additions & 5 deletions specification/archSpec/base/conref.dita
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +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 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>
<shortdesc rev="review-ella">The DITA conref attributes are mechanisms that enable effective
content reuse. DITA content references support complex reuse scenarios that are otherwise
challenging or impossible to achieve. In addition, DITA content references have rules to ensure
that the content is valid DITA after the content reference has been resolved.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -16,4 +15,5 @@
</keywords>
</metadata>
</prolog>
<conbody/>
</concept>
17 changes: 8 additions & 9 deletions specification/archSpec/base/ditauseconreftarget.dita
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="usingthe-dita-use-conref-targetvalue" xml:lang="en-us">
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="usingthe-dita-use-conref-targetvalue" xml:lang="en-us">
<title>Using the <keyword>-dita-use-conref-target</keyword> value</title>
<shortdesc>The value <keyword>-dita-use-conref-target</keyword> is available on enumerated
attributes and can also be specified on other attributes. When an element uses
Expand All @@ -15,14 +15,13 @@
</keywords>
</metadata>
</prolog>
<refbody>
<section id="section_nwl_xxy_qpb">
<conbody>
<draft-comment author="robander" time="19 May 2021">This topic is moving into the arch spec,
but needs further editing to split overview / conceptual info from processing info; this and
other conref-attribute topics currently have a bunch of processing info that is missing from
the actual "Processing conref" arch spec topics.</draft-comment>
</section>
<section id="section-1"><p>Ordinarily, when an element uses <xmlatt>conref</xmlatt>, any other

<p>Ordinarily, when an element uses <xmlatt>conref</xmlatt>, any other
attributes specified locally will be preserved when the reference is resolved. This causes
problems when attributes are required, because required attributes must be specified
regardless of whether the <xmlatt>conref</xmlatt> attribute is present. The purpose of the
Expand All @@ -37,7 +36,7 @@
<xmlelement>tgroup</xmlelement>. However, the token is not allowed for the
<xmlatt>id</xmlatt> attribute on the <xmlelement>topic</xmlelement> element, because
"-dita-use-conref-target" does not fit the syntax required by the XML grammar
files.</p></section>
files.</p>
<example id="example" otherprops="examples">
<p>This example shows a DITA map where the <xmlelement>topichead</xmlelement> element uses
<xmlatt>conref</xmlatt>. It specifies the <xmlatt>deliveryTarget</xmlatt> attribute as
Expand Down Expand Up @@ -90,5 +89,5 @@
</codeblock>
</fig>
</example>
</refbody>
</reference>
</conbody>
</concept>
16 changes: 8 additions & 8 deletions specification/archSpec/base/theconactionattribute.dita
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"reference.dtd">
<reference id="theconactionattribute" xml:lang="en-us">
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"concept.dtd">
<concept id="theconactionattribute" xml:lang="en-us">
<title>The <xmlatt>conaction</xmlatt> attribute</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
Expand All @@ -14,8 +14,8 @@
</keywords>
</metadata>
</prolog>
<refbody>
<section id="section-1"><note>In the descriptions below, the word <i>target</i> always refers to the element referenced by a
<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
Expand All @@ -36,7 +36,7 @@
not legal to push a list item (<xmlelement>li</xmlelement>) in order to replace a
<xmlelement>step</xmlelement>, because the list item allows many items that are not
valid in the specialized context.</li>
</ul></section>
</ul>
<section id="replacing-content">
<title>Replacing content in another topic</title>
<p>When the <xmlatt>conaction</xmlatt> attribute is set to <keyword>pushreplace</keyword>, the
Expand Down Expand Up @@ -120,6 +120,6 @@ was not addressed in the original proposal.-->
application can recover by warning the user, ignoring the <xmlatt>conrefend</xmlatt>
attribute, or with some other implementation strategy.</p>
</section>
</refbody>
</reference>
</conbody>
</concept>

15 changes: 7 additions & 8 deletions specification/archSpec/base/theconkeyrefattribute.dita
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"reference.dtd">
<reference id="theconkeyrefattribute" xml:lang="en-us">
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"concept.dtd">
<concept id="theconkeyrefattribute" xml:lang="en-us">
<title>The <xmlatt>conkeyref</xmlatt> attribute</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
Expand All @@ -13,8 +13,7 @@
</keywords>
</metadata>
</prolog>
<refbody>
<section id="section-1">
<conbody>
<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
Expand All @@ -32,6 +31,6 @@
by the <xmlatt>conrefend</xmlatt> attribute. See <xref
keyref="attributes-conrefend/conkeyref"/> for more information and for examples of this
behavior.</p>
</section>
</refbody>
</reference>

</conbody>
</concept>
22 changes: 11 additions & 11 deletions specification/archSpec/base/theconrefattribute.dita
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"reference.dtd">
<reference id="theconrefattribute" xml:lang="en-us">
<!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>
Expand All @@ -12,16 +12,16 @@
</keywords>
</metadata>
</prolog>
<refbody>
<section id="section-1"><p>The value of the <xmlatt>conref</xmlatt> attribute is a URI reference to a DITA element. See
<conbody>
<p>The value of the <xmlatt>conref</xmlatt> attribute is a URI reference to a DITA element. See
<xref href="../../archSpec/base/uri-based-addressing.dita"/> for details on specifying URI
references to DITA elements. As with other DITA references, a <xmlatt>conref</xmlatt>
attribute that references a resource without an ID is treated as a reference to the first
topic or map in the document.</p><note>When using the <xmlatt>conref</xmlatt> attribute on an element, the content of that element is
ignored. For example, if a phrase is marked up like
this:<codeblock>&lt;ph conref="#topic/ph">Something&lt;/ph></codeblock> the
word "Something" will be replaced by the content of the referenced
<xmlelement>ph</xmlelement> element.</note></section>
</refbody>
</reference>
ignored <ph rev="review-ella">by processors</ph>. For example, if a phrase is marked up like
this:<codeblock>&lt;ph conref="#topic/ph">Something&lt;/ph></codeblock> the word "Something"
will be replaced by the content of the referenced <xmlelement>ph</xmlelement>
element.</note>
</conbody>
</concept>

10 changes: 5 additions & 5 deletions specification/archSpec/base/theconrefendattribute.dita
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="theconrefendattribute" xml:lang="en-us">
<!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
Expand All @@ -13,7 +13,7 @@
</keywords>
</metadata>
</prolog>
<refbody>
<conbody>
<section id="section-1"><title>Using <xmlatt>conref</xmlatt> together with
<xmlatt>conrefend</xmlatt></title>
<p>The following markup rules apply when using or implementing <xmlatt>conrefend</xmlatt>:<ul>
Expand Down Expand Up @@ -74,5 +74,5 @@
the <xmlatt>conref</xmlatt> attribute itself is not present for fallback, the
<xmlatt>conrefend</xmlatt> attribute is ignored.</p>
</section>
</refbody>
</reference>
</conbody>
</concept>
1 change: 1 addition & 0 deletions specification/dita-2.0-specification-subjectScheme.ditamap
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@
<subjectdef keys="review-aretha"/>
<subjectdef keys="review-chenier"/>
<subjectdef keys="review-dave-alvin"/>
<subjectdef keys="review-ella"/>
<subjectdef keys="2.0"/>
<subjectdef keys="tc-review"/>
<subjectdef keys="rendering">
Expand Down
Loading