Skip to content

Commit

Permalink
Updates for proposal oasis-tcs#647
Browse files Browse the repository at this point in the history
  • Loading branch information
@keberlein
keberlein committed Jun 6, 2022
1 parent ba2c460 commit 2b13632
Show file tree
Hide file tree
Showing 11 changed files with 148 additions and 28 deletions.
1 change: 1 addition & 0 deletions specification/archSpec/base/cascading-of-attributes-from-map-to-map.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
<li><xmlatt>translate</xmlatt></li>
<li><xmlatt>processing-role</xmlatt></li>
<li><xmlatt>cascade</xmlatt></li>
<li rev="2.0"><xmlatt>subjectrefs</xmlatt></li>
</ul>
<p>As with values that cascade within a map, the cascading is additive
if the attribute permits multiple values<ph rev="review-k">,
Expand Down
13 changes: 4 additions & 9 deletions specification/archSpec/base/cascading-of-roles-in-specialized-maps.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@
</prolog>
<conbody>
<!--IGNORE may-must-should word-->
<draft-comment author="Kristen J Eberlein" audience="spec-editors" time="04 July 2019">
<p>We need to look at the instances of "should" in this topic. Can they be recast? Do we need
to introduce RFC-2119 language?</p>
<draft-comment author="Kristen J Eberlein" time="04 June 2022">
<p>Proposal #670, championed by Robert Anderson, will rework this
content.</p>
</draft-comment>
<p>The semantic role reflects the <xmlatt>class</xmlatt> hierarchy of
the referencing <xmlelement>topicref</xmlelement> element<ph
Expand All @@ -36,12 +36,7 @@
role of "topic"), or when a <xmlelement>mapref</xmlelement> element references a DITA map (giving
it the role of "DITA map").</p>
<!--IGNORE may-must-should word-->
<draft-comment author="rodaande" time="8 Feb 2022">The following paragraph includes the
statement: "the non-default behavior should be clearly specified"<p>We do not say how or
where. For mapgroup, I believe it is only specified here in this topic. I think either we
need this as part of every mapgroup element definition, in "Processing expectations", or we
need a clear table here listing every element where this behavior does not
apply.</p></draft-comment>
<!--<draft-comment author="rodaande" time="8 Feb 2022">The following paragraph includes the statement: "the non-default behavior should be clearly specified"<p>We do not say how or where. For mapgroup, I believe it is only specified here in this topic. I think either we need this as part of every mapgroup element definition, in "Processing expectations", or we need a clear table here listing every element where this behavior does not apply.</p></draft-comment>-->
<p>Unless otherwise instructed, a specialized <xmlelement>topicref</xmlelement> element that
references a map supplies a role for the referenced content. This means that, in effect, the
<xmlatt>class</xmlatt> attribute of the referencing element cascades to top-level topicref
Expand Down
71 changes: 71 additions & 0 deletions ...ication/archSpec/base/example-a-subject-scheme-map-used-to-define-taxonomic-subjects.dita
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept
id="example-a-subject-scheme-map-used-to-define-taxonomic-subjects"
rev="2.0">
<title>Example: A subject scheme map used to define taxonomic
subjects</title>
<shortdesc>A subject scheme map can be used to define taxonomic subjects.
Once defined, the subjects can be referenced by applying a
<xmlatt>subjectrefs</xmlatt> attribute to a
<xmlelement>topicref</xmlelement> element.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm>examples<indexterm>subject scheme
maps<indexterm>defining taxonomic
subjects</indexterm></indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>The following subject scheme map defines a set of subjects that are
used to classify content:</p>
<codeblock>&lt;subjectScheme>
&lt;subjectdef keys="content-types">
&lt;subjectdef keys="conceptual-material"/>
&lt;subjectdef keys="reference"/>
&lt;subjectdef keys="tutorial"/>
&lt;/subjectdef>
&lt;subjectdef keys="operating-systems">
&lt;subjectdef keys="linux"/>
&lt;subjectdef keys="macosx"/>
&lt;subjectdef keys="windows"/>
&lt;/subjectdef>
&lt;subjectdef keys="user-tasks">
&lt;subjectdef keys="administering"/>
&lt;subjectdef keys="developing"/>
&lt;subjectdef keys="installing"/>
&lt;subjectdef keys="troubleshooting"/>
&lt;/subjectdef>
&lt;/subjectScheme></codeblock>
<p>The keys assigned to the subject definitions can be referenced by
specifying the <xmlatt>subjectrefs</xmlatt> attribute on topic
references in a navigation map:</p>
<codeblock>&lt;map>
&lt;title>User assistance for the Acme Widget&lt;/title>
&lt;!-- ... -->
&lt;topicref keyref="install-overview" <b>subjectrefs="installing"</b>>
&lt;topicref keyref="install-linux"/>
&lt;topicref keyref="install-macosx"/>
&lt;topicref keyref="install-windows"/>
&lt;topicref keyref="install-troubleshooting" <b>subjectrefs="troubleshooting"</b>/>
&lt;/topicref>
&lt;!-- ... -->
&lt;/map></codeblock>
<p>Because the <xmlatt>subjectrefs</xmlatt> attribute cascades, the
effective value of the above markup is the same as the following
markup:</p>
<codeblock>&lt;map>
&lt;title>User assistance for the Acme Widget&lt;/title>
&lt;!-- ... -->
&lt;topicref keyref="install-overview" subjectrefs="installing">
&lt;topicref keyref="install-linux" subjectrefs="installing"/>
&lt;topicref keyref="install-macosx" subjectrefs="installing"/>
&lt;topicref keyref="install-windows" subjectrefs="installing"/>
&lt;topicref keyref="install-troubleshooting" subjectrefs="installing troubleshooting"/>
&lt;/topicref>
&lt;!-- ... -->
&lt;/map></codeblock>
</conbody>
</concept>
37 changes: 25 additions & 12 deletions specification/archSpec/base/example-cascade-map-to-map-attributes.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,13 @@
</prolog>
<conbody>
<p>Assume the following references in
<filepath>test.ditamap</filepath>:<codeblock id="codeblock_sx1_fp5_nsb">&lt;map>
<filepath>test.ditamap</filepath>:<codeblock>&lt;map>
&lt;topicref href="a.ditamap" format="ditamap" toc="no"/>
&lt;mapref href="b.ditamap" audience="developer"/>
&lt;mapref href="c.ditamap#branch2" platform="myPlatform"/>
&lt;mapref href="b.ditamap" audience="developer"/>
&lt;mapref href="c.ditamap#branch2" platform="myPlatform"/>
<ph rev="2.0">&lt;mapref> href="d.ditamap" subjectrefs="puzzles"/></ph>
&lt;/map></codeblock></p>
<ul id="ul_vx1_fp5_nsb">
<ul>
<li>The map <filepath>a.ditamap</filepath> is treated as if
<codeph>toc="no"</codeph> is specified on the root
<xmlelement>map</xmlelement> element. This means that the topics
Expand All @@ -29,15 +30,27 @@
except for branches within the map that explicitly set
<codeph>toc="yes"</codeph>.</li>
<li>The map <filepath>b.ditamap</filepath> is treated as if
<codeph>audience="developer"</codeph> is set on the root <xmlelement>map</xmlelement>
element. If the <xmlatt>audience</xmlatt> attribute is already set on the root
<xmlelement>map</xmlelement> element within <filepath>b.ditamap</filepath>, the value
"developer" is added to any existing values.</li>
<codeph>audience="developer"</codeph> is set on the root
<xmlelement>map</xmlelement> element. If the
<xmlatt>audience</xmlatt> attribute is already set on the root
<xmlelement>map</xmlelement> element within
<filepath>b.ditamap</filepath>, the value
<keyword>developer</keyword> is added to any existing
values.</li>
<li>The element with <codeph>id="branch2"</codeph> within the map
<filepath>c.ditamap</filepath> is treated as if <codeph>platform="myPlatform"</codeph> is
specified on that element. If the <xmlatt>platform</xmlatt> attribute is already specified
on the element with <codeph>id="branch"</codeph>, the value<keyword>myPlatform</keyword> is
added to existing values.</li>
<filepath>c.ditamap</filepath> is treated as if
<codeph>platform="myPlatform"</codeph> is specified on that
element. If the <xmlatt>platform</xmlatt> attribute is already
specified on the element with <codeph>id="branch"</codeph>, the
value<keyword>myPlatform</keyword> is added to existing
values.</li>
<li rev="2.0">The map <filepath>d.ditamap</filepath> is treated as if
<codeph>subjectrefs="puzzles"</codeph> is set on the root
<xmlelement>map</xmlelement> element. If the
<xmlatt>subjectrefs</xmlatt> attribute is already set on the root
<xmlelement>map</xmlelement> element within
<filepath>d.ditamap</filepath>, the value
<keyword>puzzles</keyword> is added to any existing values.</li>
</ul>
</conbody>
</concept>
4 changes: 4 additions & 0 deletions specification/archSpec/base/example-cascading-topicref-roles.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@
</metadata>
</prolog>
<conbody>
<draft-comment author="Kristen J Eberlein" time="04 June 2022">
<p>Proposal #670, championed by Robert Anderson, will rework this
content.</p>
</draft-comment>
<p>Consider the scenario of a <xmlelement>chapter</xmlelement> element from the Book map
specialization that references a DITA map. This scenario could take several forms:<dl
id="dl_ohc_nq5_nsb">
Expand Down
4 changes: 4 additions & 0 deletions specification/archSpec/base/processing-cascading-attributes-in-a-map.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@
<shortdesc>Certain rules apply to processors when they process cascading attributes in a
map.</shortdesc>
<conbody>
<draft-comment author="Kristen J Eberlein" time="04 June 2022">
<p>Robert Anderson has an open action item to rework the ordered
list.</p>
</draft-comment>
<p>When determining the value of an attribute, processors <term
outputclass="RFC-2119">MUST</term> evaluate each attribute on each
individual element in a specific order<ph rev="review-k">. This</ph>
Expand Down
5 changes: 4 additions & 1 deletion specification/archSpec/base/subject-scheme-maps.ditamap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,11 @@
<topicref href="processing-controlled-attribute-values.dita"/>
<!--<topicref href="extending-a-subject-scheme.dita"/>-->
<!--<topicref href="scaling-controlled-values-to-define-a-taxonomy.dita"/>-->
<topicref href="classification-maps.dita"/>
<!--<topicref href="classification-maps.dita"/>-->
<topicref href="the-subjectrefs-attribute.dita"/>
<topicref href="examples-subjectScheme-maps.dita">
<topicref
href="example-a-subject-scheme-map-used-to-define-taxonomic-subjects.dita"/>
<topicref href="example-subjectScheme-filtering.dita"/>
<!--<topicref href="example-subjectScheme-extension.dita"/>-->
<!--<topicref href="example-subjectScheme-extension-upwards.dita"/>-->
Expand Down
10 changes: 4 additions & 6 deletions specification/archSpec/base/subjectSchema.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,10 @@
value that is not one of the controlled values. </ph>Controlled
values can also be used to <ph rev="review-d">select </ph>content for
filtering and flagging at build time.</p>
<p ><term>Subject definitions</term> are classifications and
sub-classifications that compose a tree. Subject definitions provide semantics that can
be used in conjunction with taxonomies and ontologies. In conjunction with the
classification domain, subject definitions can be used for retrieval and traversal of
the content at run time when used with information viewing applications that provide
such functionality.</p>
<p><term>Subject definitions</term> are classifications and
sub-classifications that compose a tree. Subject definitions provide
semantics that can be used in conjunction with taxonomies and
ontologies.</p>
<p >Key references to controlled values are resolved to a key
definition using the same precedence rules as apply to any other key. However, once a
key is resolved to a controlled value, that key reference does not typically result in
Expand Down
22 changes: 22 additions & 0 deletions specification/archSpec/base/the-subjectrefs-attribute.dita
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="the-subjectrefs-attribute" rev="2.0">
<title>The <xmlatt>subjectrefs</xmlatt> attribute</title>
<shortdesc>The <xmlatt>subjectrefs</xmlatt> attribute specifies one or
more keys that are defined by a subject definition in a subject scheme
map. Multiple values are separated by white space.</shortdesc>
<prolog>
<metadata>
<keywords>
<indexterm><xmlatt>subjectrefs</xmlatt><indexterm>overview</indexterm></indexterm>
</keywords>
</metadata>
</prolog>
<conbody>
<p>The <xmlatt>subjectrefs</xmlatt> attribute cascades. It can be used
on a <xmlelement>topicref</xmlelement> element to associate the
referenced topic with a subject defined in a subject scheme map.</p>
<p>The <xmlatt>subjectrefs</xmlatt> attribute has no meaning if it is
specified on a key definition that does not reference a resource.</p>
</conbody>
</concept>
1 change: 1 addition & 0 deletions specification/common/conref-file.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ to alert more birds to the presence of your bird feeder.&lt;/shortdesc&gt;
<xmlatt>translate</xmlatt></li>
<li><xmlatt>processing-role</xmlatt></li>
<li ><xmlatt>cascade</xmlatt></li>
<li rev="2.0"><xmlatt>subjectrefs</xmlatt></li>
</ul>
<dl>
<dlentry id="deliveryTarget">
Expand Down
8 changes: 8 additions & 0 deletions specification/resources/DITA2.0-spec.ditaval
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,5 +121,13 @@
<endflag>
<alt-text>◄</alt-text>
</endflag>-->
</revprop>
<revprop action="flag" color="blue" val="2.0">
<!-- <startflag>
<alt-text>►</alt-text>
</startflag>
<endflag>
<alt-text>◄</alt-text>
</endflag>-->
</revprop>
</val>

0 comments on commit 2b13632

Please sign in to comment.