Merge pull request #732 from keberlein/generate-spec-draft

Implement #647
oasis-tcs · Jul 29, 2022 · b9159d8 · b9159d8
2 parents 7011677 + e01218e
commit b9159d8
Show file tree

Hide file tree

Showing 17 changed files with 242 additions and 67 deletions.
diff --git a/doctypes/dtd/base/map.mod b/doctypes/dtd/base/map.mod
@@ -133,6 +133,9 @@ PUBLIC "-//OASIS//ELEMENTS DITA 2.0 Map//EN"
                           CDATA
                                     #IMPLIED
                keyscope
+                          CDATA
+                                    #IMPLIED
+               subjectrefs
                           CDATA
                                     #IMPLIED"
 >
@@ -283,6 +286,9 @@ PUBLIC "-//OASIS//ELEMENTS DITA 2.0 Map//EN"
                           CDATA
                                     #IMPLIED
                keyscope
+                          CDATA
+                                    #IMPLIED
+               subjectrefs
                           CDATA
                                     #IMPLIED"
 >

diff --git a/doctypes/dtd/base/mapGroup.mod b/doctypes/dtd/base/mapGroup.mod
@@ -176,6 +176,9 @@
                chunk
                           CDATA
                                     #IMPLIED
+               subjectrefs
+                          CDATA
+                                    #IMPLIED
                %univ-atts;"
 >
 <!ELEMENT  keydef %keydef.content;>

diff --git a/doctypes/rng/base/mapGroupDomain.rng b/doctypes/rng/base/mapGroupDomain.rng
@@ -287,6 +287,9 @@ PUBLIC "-//OASIS//ELEMENTS DITA 2.0 Map Group Domain//EN"
         <optional>
           <attribute name="chunk"/>
         </optional>
+        <optional>
+        <attribute name="subjectrefs"/>
+      </optional>
         <ref name="univ-atts"/>
       </define>
       <define name="keydef.element">

diff --git a/doctypes/rng/base/mapMod.rng b/doctypes/rng/base/mapMod.rng
@@ -339,6 +339,9 @@ PUBLIC "-//OASIS//ELEMENTS DITA 2.0 Map//EN"
       <optional>
         <attribute name="chunk"/>
       </optional>
+      <optional>
+        <attribute name="subjectrefs"/>
+      </optional>
     </define>
     <define name="topicref-atts-without-format">
       <optional>
@@ -473,6 +476,9 @@ PUBLIC "-//OASIS//ELEMENTS DITA 2.0 Map//EN"
       <optional>
         <attribute name="chunk"/>
       </optional>
+      <optional>
+        <attribute name="subjectrefs"/>
+      </optional>
     </define>
   </div>
 

diff --git a/specification/archSpec/base/cascading-of-attributes-from-map-to-map.dita b/specification/archSpec/base/cascading-of-attributes-from-map-to-map.dita
@@ -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">,

diff --git a/specification/archSpec/base/example-cascade-map-to-map-elements.dita b/specification/archSpec/base/example-cascade-map-to-map-elements.dita
@@ -17,56 +17,44 @@
             </keywords>
         </metadata>
     </prolog>
-    <conbody>
-        <p>Consider the following code examples:</p>
-        <fig id="figtest2">
-            <title><filepath>Root map</filepath></title>
-            <codeblock id="codeblock_ffk_bq5_nsb">&lt;map>
-  &lt;title>Acme User Guide&lt;/title>
-  &lt;topicref href="acme-defects.ditamap" format="ditamap">
-    &lt;topicmeta>
-      &lt;shortdesc>This map contains information about Acme defects.&lt;/shortdesc>
-    &lt;/topicmeta>
-  &lt;/topicref>
-  &lt;topicref href="installing.ditamap" format="ditamap">
-    &lt;topicmeta>
-      &lt;audience type="installer"/>
-    &lt;/topicmeta>
-  &lt;/topicref>    
-  &lt;mapref href="troubleshooting.ditamap"/>
-  &lt;mapref href="reference.ditamap"/>
-&lt;/map></codeblock>
-        </fig>
-        <fig id="figb">
-            <title><filepath>installing.ditamap</filepath></title>
-            <codeblock id="codeblock_gfk_bq5_nsb">&lt;map>
-  &lt;title>Installation topics&lt;/title>
-  &lt;topicmeta>
-    &lt;audience type="administrator"/>
-  &lt;/topicmeta>
-  &lt;topicref href="install-1.dita"/>
-  &lt;topicref href="install-2.dita"/>
-&lt;/map>
-</codeblock>
-        </fig>
-        <p>When the root map is processed, the following behavior
-        occurs:<ul id="ul_hfk_bq5_nsb">
-        <li>Because the <xmlelement>shortdesc</xmlelement> element does not
-          cascade, it does not apply to the DITA topics that are referenced
-          in <filepath>acme-defects.ditamap</filepath>.</li>
-        <li>Because the <xmlelement>audience</xmlelement> element cascades,
-          the <xmlelement>audience</xmlelement> element in the reference to
-            <filepath>installing.ditamap</filepath> combines with the
-            <xmlelement>audience</xmlelement> element that is specified at
-          the top level of <filepath>installing.ditamap</filepath>. The
-          result is that the <filepath>install-1.dita</filepath> and
-            <filepath>install-2.dita</filepath> topics are processed as
-          though they each contained the following child
-            <xmlelement>topicmeta</xmlelement>
-          element:<codeblock id="codeblock_ifk_bq5_nsb">&lt;topicmeta>
-  &lt;audience type="installer"/>
-  &lt;audience type="administrator"/>
-&lt;/topicmeta></codeblock></li>
-      </ul></p>
-    </conbody>
+  <conbody>
+    <p>Assume the following references in
+      <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"/>
+  <ph rev="2.0">&lt;mapref href="d.ditamap" subjectrefs="puzzles"/></ph>
+&lt;/map></codeblock></p>
+    <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
+        that are referenced by <filepath>a.ditamap</filepath> do not appear
+        in the navigation generated by <filepath>test.ditamap</filepath>,
+        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
+          <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>
+      <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>
diff --git a/...ification/archSpec/base/example-subject-scheme-map-used-to-define-taxonomic-subjects.dita b/...ification/archSpec/base/example-subject-scheme-map-used-to-define-taxonomic-subjects.dita
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="a-subject-scheme-map-used-to-define-taxonomic-subjects">
+    <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 specifying a
+      <xmlatt>subjectrefs</xmlatt> attribute on 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>
diff --git a/specification/archSpec/base/example-subjectrefs-attribute-with-key-scopes.dita b/specification/archSpec/base/example-subjectrefs-attribute-with-key-scopes.dita
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="example-subjectrefs-attribute-with-key-scopes">
+    <title>Example: <xmlatt>subjectrefs</xmlatt> attribute with key
+    scopes</title>
+    <shortdesc></shortdesc>
+  <conbody>
+    <draft-comment author="Kristen J Eberlein" time="29 July 2022">
+      <p>The following is content that Eliot Kimber suggested be included
+        in the DITA 2.0 specification as part of the review of proposal
+        #647. It has not been edited.</p>
+    </draft-comment>
+    <p>A subject scheme map may be included in a map as either a normal sub
+      map or as a peer root map and associated with a key scope on the map
+      reference.</p>
+    <fig>
+      <title>A subject scheme map included as a sub map with a key scope: </title>
+      <codeblock>&lt;map>
+ &lt;title>User assistance for the Acme Widget&lt;/title>
+ &lt;!-- ... -->
+ &lt;mapref keyscope="subjects" href="subjectschemes/subject-scheme-01.ditamap"/>
+ &lt;topicref keyref="install-overview" subjectrefs="subjects.installing">
+   &lt;topicref keyref="install-linux"/>
+   &lt;topicref keyref="install-macosx"/>
+   &lt;topicref keyref="install-windows"/>
+   &lt;topicref keyref="install-troubleshooting" subjectrefs="subjects.troubleshooting"/>
+ &lt;/topicref>
+ &lt;!-- ... --> 
+&lt;/map></codeblock>
+    </fig>
+    <p> The keys defined in referenced subject scheme map are included in
+      the referencing map's key space. References to the subject keys must
+      be scope qualified (i.e., "subjects.installing"). Putting the subject
+      scheme keys in a key scope ensures that the keys defined in the
+      subject scheme do not conflict with any keys defined elsewhere in the
+      referencing map (although the referencing map could still override
+      any keys defined in the subject scheme map).</p>
+    <p>The subject scheme map can also be referenced as a peer-scope root
+      map in a key scope:</p>
+    <codeblock>&lt;map>
+ &lt;title>User assistance for the Acme Widget&lt;/title>
+ &lt;!-- ... -->
+ &lt;mapref keyscope="subjects" scope="peer" href="subjectschemes/subject-scheme-01.ditamap"/>
+ &lt;topicref keyref="install-overview" subjectrefs="subjects.installing">
+   &lt;topicref keyref="install-linux"/>
+   &lt;topicref keyref="install-macosx"/>
+   &lt;topicref keyref="install-windows"/>
+   &lt;topicref keyref="install-troubleshooting" subjectrefs="subjects.troubleshooting"/>
+ &lt;/topicref>
+ &lt;!-- ... --> 
+&lt;/map></codeblock>
+    <p>As a peer map, the keys defined in the subject scheme map are not
+      included in the referencing map's key space but may be resolved using
+      normal cross-deliverable key reference resolution. Processors that
+      support cross-deliverable linking may also choose to resolve
+      references from @"subjectrefs" to keys in peer subject scheme maps,
+      for example to report keys specified on @"subjectrefs" that cannot be
+      found in the peer subject scheme map.</p>
+  </conbody>
+</concept>
diff --git a/specification/archSpec/base/examples-keys.ditamap b/specification/archSpec/base/examples-keys.ditamap
@@ -21,5 +21,7 @@
   <topicref href="example-key-scopes-omnibus-publications.dita"/>
   <topicref href="example-keys-scope-defining-precedence.dita"/>
   <topicref href="example-scoped-key-name-conflicts.dita"/>
+    <topicref href="example-subjectrefs-attribute-with-key-scopes.dita"
+      rev="2.0"/>
  </topicref>
 </map>
diff --git a/specification/archSpec/base/subject-scheme-maps.ditamap b/specification/archSpec/base/subject-scheme-maps.ditamap
@@ -7,13 +7,12 @@
   <topicref href="controlled-values-for-attributes.dita"/>
   <topicref href="binding-controlled-values-to-attribute.dita"/>
   <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="subjectrefs-attribute.dita" rev="2.0"/>
   <topicref href="examples-subjectScheme-maps.dita">
+      <topicref
+        href="example-subject-scheme-map-used-to-define-taxonomic-subjects.dita"
+        rev="2.0"/>
    <topicref href="example-subjectScheme-filtering.dita"/>
-      <!--<topicref href="example-subjectScheme-extension.dita"/>-->
-      <!--<topicref href="example-subjectScheme-extension-upwards.dita"/>-->
    <topicref href="example-subjectScheme-values-for-deliveryTarget.dita"/>
   </topicref>
  </topicref>

diff --git a/specification/archSpec/base/subjectSchema.dita b/specification/archSpec/base/subjectSchema.dita
@@ -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.<!-- 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 >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

diff --git a/specification/archSpec/base/subjectrefs-attribute.dita b/specification/archSpec/base/subjectrefs-attribute.dita
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="subjectrefs-attribute">
+  <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. When specified
+      on a topic reference, the <xmlatt>subjectrefs</xmlatt> attribute
+      associates the referenced resource with subjects that are defined in
+      subject scheme maps.</p>
+    <p>The DITA 2.0 specification does not indicate processing expectations
+      for the <xmlatt>subjectrefs</xmlatt> attribute. The DITA Technical
+      Committee expects to specify such expectations in the future.</p>
+  </conbody>
+</concept>
diff --git a/specification/common/conref-file.dita b/specification/common/conref-file.dita
@@ -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">

diff --git a/specification/dita-2.0-key-definitions-cover-pages.ditamap b/specification/dita-2.0-key-definitions-cover-pages.ditamap
@@ -13,14 +13,14 @@
       <!-- Also used in the "Citation format" section.-->
       <topicmeta>
         <keywords>
-          <keyword>Working Draft 27</keyword>
+          <keyword>Working Draft 28</keyword>
         </keywords>
       </topicmeta>
     </keydef>
     <keydef keys="stage-date">
       <topicmeta>
         <keywords>
-          <keyword>20 June 2022</keyword>
+          <keyword>29 July 2022</keyword>
         </keywords>
       </topicmeta>
     </keydef>