Merge pull request #733 from keberlein/proposal-15

Final edits for stage three proposal, #15
oasis-tcs · Aug 8, 2022 · fb80609 · fb80609
2 parents b9159d8 + bc2af0d
commit fb80609
Show file tree

Hide file tree

Showing 20 changed files with 393 additions and 354 deletions.
diff --git a/specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita b/specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="adding-an-attribute-to-certain-table-elements">
+<concept id="adding-an-attribute-to-certain-table-elements" rev="2.0">
   <title>Example: Adding an attribute to certain table elements using
     DTDs</title>
   <shortdesc>In this scenario, a company makes extensive use of complex

diff --git a/specification/archSpec/base/adding-an-element-to-the-section-element.dita b/specification/archSpec/base/adding-an-element-to-the-section-element.dita
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="adding-an-element-to-the-section-element">
+<concept id="adding-an-element-to-the-section-element" rev="2.0">
   <title>Example: Adding an element to the <xmlelement>section</xmlelement>
     element using DTDs</title>
   <shortdesc>In this scenario, a DITA architect wants to modify the content
@@ -36,7 +36,7 @@
         <li>First, the DITA architect creates the element specialization
           module: <filepath>sectionDescDomain.mod</filepath>. This single
             <filepath>.mod</filepath> file defines the parameter entity,
-          content model,  attributes, and value for the
+          content model, attributes, and value for the
             <xmlatt>class</xmlatt> attribute for
             <xmlelement>sectionDesc</xmlelement>.<codeblock>&lt;?xml version="1.0" encoding="UTF-8"?>
 

diff --git a/specification/archSpec/base/aggregating-constraint-and-expansion-modules.dita b/specification/archSpec/base/aggregating-constraint-and-expansion-modules.dita
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="aggregating-constraint-and-expansion-modules">
+<concept id="aggregating-constraint-and-expansion-modules" rev="2.0">
   <title>Example: Aggregating constraint and expansion modules using
     DTDs</title>
   <shortdesc>The DITA architect wants to add some extension modules to the

diff --git a/specification/archSpec/base/configuration.dita b/specification/archSpec/base/configuration.dita
@@ -2,8 +2,10 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept xml:lang="en-us" id="concept_fgy_hbp_wr">
  <title rev="2.0">Document-type configuration</title>
- <shortdesc><ph rev="2.0">Document-type configuration</ph> enables the definition of DITA document
-        types that include only the vocabulary modules that are required for a given set of
-        documents. There is no need to modify the vocabulary modules. <ph rev="2.0">Document-type
-            configurations</ph> are implemented as document-type shells.</shortdesc>
+ <shortdesc><ph rev="2.0">Document-type configuration</ph> enables the
+    definition of DITA document types that include only the vocabulary
+    modules that are required for a given set of documents. There is no
+    need to modify the vocabulary modules. <ph rev="2.0">Document-type
+      configurations</ph> are implemented <ph rev="2.0">using </ph>
+    document-type shells.</shortdesc>
 </concept>
diff --git a/specification/archSpec/base/ditaspecialization.dita b/specification/archSpec/base/ditaspecialization.dita
@@ -2,9 +2,9 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="ditaspecialization" xml:lang="en-us">
   <title>Overview of DITA extension facilities</title>
-  <shortdesc rev="2.0">DITA provides three extension facilities: Document-type configuration,
-    specialization, and element-type configuration. In addition, generalization can be applied to
-    reverse specialization.</shortdesc>
+  <shortdesc rev="2.0">DITA provides three extension facilities:
+    Document-type configuration, specialization, and element-type
+    configuration.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
@@ -23,15 +23,22 @@
       </dlentry>
       <dlentry>
         <dt>Specialization</dt>
-        <dd>Specialization enables the creation of new element types in a way that preserves the
-          ability to interchange those new element types with conforming DITA applications.
-          Specializations are implemented as vocabulary modules, which are integrated into
-          document-type shells.<p>Specializations declare the elements and entities that are unique
-            to a specialization. The separation of the vocabulary and its declarations into modules
-            makes it easy to extend existing modules, because new modules can be added without
-            affecting existing document types. It also makes it easy to assemble elements from
-            different sources into a single document-type shell and to reuse specific parts of the
-            specialization hierarchy in more than one document-type shell.</p></dd>
+        <dd>Specialization enables the creation of new element types in a
+          way that preserves the ability to interchange those new element
+          types with conforming DITA applications. Specializations are
+          implemented as vocabulary modules, which are integrated into
+          document-type shells.<p>Specializations declare the elements and
+            entities that are unique to a specialization. The separation of
+            the vocabulary and its declarations into modules makes it easy
+            to extend existing modules, because new modules can be added
+            without affecting existing document types. It also makes it
+            easy to assemble elements from different sources into a single
+            document-type shell and to reuse specific parts of the
+            specialization hierarchy in more than one document-type
+            shell.</p><p rev="2.0">DITA content that uses specializations
+            can be treated as or converted to unspecialized markup through
+            the process of generalization. The information about the
+            original specialized form can be retained.</p></dd>
       </dlentry>
       <dlentry rev="2.0">
         <dt>Element-type configuration</dt>
@@ -56,11 +63,6 @@
           </dl>
         </dd>
       </dlentry>
-      <dlentry>
-        <dt>Generalization</dt>
-        <dd>Generalization is the process of reversing a specialization. It converts specialized
-          elements or attributes into the original types from which they were derived.</dd>
-      </dlentry>
     </dl>
   </conbody>
 </concept>
diff --git a/specification/archSpec/base/example-constrain-a-domain-using-rng.dita b/specification/archSpec/base/example-constrain-a-domain-using-rng.dita
@@ -1,30 +1,33 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="example_constrain_a_domain_using_rng">
-    <title>Example: Constrain a domain module using RNG</title>
-    <shortdesc>In this scenario, <ph rev="2.0">a DITA architect</ph> wants
-    to use only a subset of the elements defined in the highlighting
-    domain. <ph rev="2.0">They want</ph> to use <xmlelement>b</xmlelement>
-    and <xmlelement>i</xmlelement> but not
+<concept id="example_constrain_a_domain_using_rng" rev="2.0">
+  <title>Example: Constrain a domain module using RNG</title>
+  <shortdesc>In this scenario, <ph rev="2.0">a DITA architect</ph> wants to
+    use only a subset of the elements defined in the highlighting domain.
+      <ph rev="2.0">They want</ph> to use <xmlelement>b</xmlelement> and
+      <xmlelement>i</xmlelement> but not
       <xmlelement>line-through</xmlelement>,
       <xmlelement>overline</xmlelement>, <xmlelement>sup</xmlelement>,
       <xmlelement>sup</xmlelement>, <xmlelement>tt</xmlelement>, or
       <xmlelement>u</xmlelement>. <ph rev="2.0">Their</ph> implementation
     uses RNG for its grammar files.</shortdesc>
-    <prolog>
-        <metadata>
-            <keywords>
-                <indexterm>constraints<indexterm>examples<indexterm>restricting content model for a
-                            domain</indexterm></indexterm></indexterm>
-                <indexterm>examples<indexterm>constraints<indexterm>restricting content model for a
-                            domain</indexterm></indexterm></indexterm>
-            </keywords>
-        </metadata>
-    </prolog>
-    <conbody>
-        <p>When using RNG, domains can be constrained directly in the document-type shells.</p>
-        <ol>
-            <li>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>constraints<indexterm>examples<indexterm>restricting
+              content model for a
+          domain</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm>constraints<indexterm>restricting
+              content model for a
+          domain</indexterm></indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
+  <conbody>
+    <p>When using RNG, domains can be constrained directly in the
+      document-type shells.</p>
+    <ol>
+      <li>
         <p><ph rev="2.0">They open</ph> the document-type shell for topic
           in an XML editor, and then <ph rev="2.0">they modify</ph> the
           "MODULE INCLUSIONS" division to exclude the elements that <ph
@@ -60,9 +63,9 @@
           "Element-type configuration integration" or the "Module
           inclusions" section.</note>
       </li>
-            <li><ph rev="2.0">They make</ph> similar changes to all the
-        other document-type shells in which <ph rev="2.0">they want</ph> to
+      <li><ph rev="2.0">They make</ph> similar changes to all the other
+        document-type shells in which <ph rev="2.0">they want</ph> to
         constrain the highlighting domain.</li>
-        </ol>
-    </conbody>
+    </ol>
+  </conbody>
 </concept>
diff --git a/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita b/specification/archSpec/base/example-rng-constraints-apply-multiple-constraints.dita
@@ -1,16 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept xml:lang="en-us" id="reference_cfb_ck4_5p">
-  <title>Example: Apply multiple constraints to a single document-type shell using RNG</title>
+<concept xml:lang="en-us" id="reference_cfb_ck4_5p" rev="2.0">
+  <title>Example: Apply multiple constraints to a single document-type
+    shell using RNG</title>
   <shortdesc>In this scenario, <ph rev="2.0">the DITA architect</ph> wants
     to apply multiple constraints to a document-type shell.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
-        <indexterm>constraints<indexterm>examples<indexterm>applying multiple
-              constraints</indexterm></indexterm></indexterm>
-        <indexterm>examples<indexterm>constraints<indexterm>applying multiple
-              constraints</indexterm></indexterm></indexterm>
+        <indexterm>constraints<indexterm>examples<indexterm>applying
+              multiple constraints</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm>constraints<indexterm>applying
+              multiple constraints</indexterm></indexterm></indexterm>
       </keywords>
     </metadata>
   </prolog>
@@ -43,20 +44,22 @@
         <strow>
           <stentry>Not applicable</stentry>
           <stentry>Highlighting domain</stentry>
-          <stentry>Reduces the highlighting domain elements to <xmlelement>b</xmlelement> and
-              <xmlelement>i</xmlelement></stentry>
+          <stentry>Reduces the highlighting domain elements to
+              <xmlelement>b</xmlelement> and
+            <xmlelement>i</xmlelement></stentry>
         </strow>
         <strow>
           <stentry>Not applicable</stentry>
           <stentry><xmlelement>ph</xmlelement></stentry>
-          <stentry>Remove the <xmlelement>ph</xmlelement> element, allowing only domain
-            extensions</stentry>
+          <stentry>Remove the <xmlelement>ph</xmlelement> element, allowing
+            only domain extensions</stentry>
         </strow>
       </simpletable>
-      <p>The constraint modules that target the <xmlelement>topic</xmlelement> and
-          <xmlelement>section </xmlelement> elements must be combined, since both elements are
-        defined in <filepath>topicMod.rng</filepath>. The other constraints can be implemented
-        directly in the document-type shell.</p>
+      <p>The constraint modules that target the
+          <xmlelement>topic</xmlelement> and <xmlelement>section
+        </xmlelement> elements must be combined, since both elements are
+        defined in <filepath>topicMod.rng</filepath>. The other constraints
+        can be implemented directly in the document-type shell.</p>
       <ol>
         <li>
           <p>The <ph rev="2.0">DITA architect</ph> creates a constraint
@@ -144,5 +147,4 @@
       </ol>
     </example>
   </conbody>
-
 </concept>
diff --git a/specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita b/specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita
@@ -1,20 +1,21 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept xml:lang="en-us"
-  id="reference_cfb_ck4_5pexample-rng-constraints-redefine-content-model-attributes">
-  <title>Example: Constrain attributes for the <xmlelement>section</xmlelement> element using
-    RNG</title>
+  id="reference_cfb_ck4_5pexample-rng-constraints-redefine-content-model-attributes"
+  rev="2.0">
+  <title>Example: Constrain attributes for the
+      <xmlelement>section</xmlelement> element using RNG</title>
   <shortdesc>In this scenario, <ph rev="2.0">a DITA architect</ph> wants to
     redefine the attributes for the <xmlelement>section</xmlelement>
     element. <ph rev="2.0">They want</ph> to make the <xmlatt>id</xmlatt>
     attribute required.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
-        <indexterm>constraints<indexterm>examples<indexterm>restricting attributes for an
-              element</indexterm></indexterm></indexterm>
-        <indexterm>examples<indexterm>constraints<indexterm>restricting attributes for an
-              element</indexterm></indexterm></indexterm>
+        <indexterm>constraints<indexterm>examples<indexterm>restricting
+              attributes for an element</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm>constraints<indexterm>restricting
+              attributes for an element</indexterm></indexterm></indexterm>
       </keywords>
     </metadata>
   </prolog>

diff --git a/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita b/specification/archSpec/base/example-rng-constraints-redefine-content-model.dita
@@ -1,8 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept xml:lang="en-us" id="example-rng-constraints-redefine-content-model">
-  <title>Example: Redefine the content model for the <xmlelement>topic</xmlelement> element using
-    RNG</title>
+<concept xml:lang="en-us"
+  id="example-rng-constraints-redefine-content-model" rev="2.0">
+  <title>Example: Redefine the content model for the
+      <xmlelement>topic</xmlelement> element using RNG</title>
   <shortdesc>In this scenario, <ph rev="2.0">a DITA architect</ph> for
     Acme, Incorporated wants to redefine the content model for the topic
     document type. <ph rev="2.0">They want</ph> to omit the
@@ -14,10 +15,10 @@
   <prolog>
     <metadata>
       <keywords>
-        <indexterm>constraints<indexterm>examples<indexterm>redefining the content
-            model</indexterm></indexterm></indexterm>
-        <indexterm>examples<indexterm>constraints<indexterm>redefining the content
-            model</indexterm></indexterm></indexterm>
+        <indexterm>constraints<indexterm>examples<indexterm>redefining the
+              content model</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm>constraints<indexterm>redefining the
+              content model</indexterm></indexterm></indexterm>
       </keywords>
     </metadata>
   </prolog>

diff --git a/...ation/archSpec/base/example-rng-constraints-replace-base-element-w-domain-extensions.dita b/...ation/archSpec/base/example-rng-constraints-replace-base-element-w-domain-extensions.dita
@@ -1,18 +1,21 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept xml:lang="en-us" id="reference_cfb_ck4_5p">
-  <title>Example: Replace a base element with the domain extensions using RNG</title>
+<concept xml:lang="en-us" id="reference_cfb_ck4_5p" rev="2.0">
+  <title>Example: Replace a base element with the domain extensions using
+    RNG</title>
   <shortdesc>In this scenario, <ph rev="2.0">the DITA architect</ph> wants
     to remove the <xmlelement>ph</xmlelement> element but allow the
     extensions of <xmlelement>ph</xmlelement> that exist in the highlight,
     programming, software, and user interface domains.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
-        <indexterm>constraints<indexterm>examples<indexterm>replacing base element with domain
-              extensions</indexterm></indexterm></indexterm>
-        <indexterm>examples<indexterm>constraints<indexterm>replacing base element with domain
-              extensions</indexterm></indexterm></indexterm>
+        <indexterm>constraints<indexterm>examples<indexterm>replacing base
+              element with domain
+          extensions</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm>constraints<indexterm>replacing base
+              element with domain
+          extensions</indexterm></indexterm></indexterm>
       </keywords>
     </metadata>
   </prolog>
@@ -40,5 +43,4 @@
       </ol>
     </example>
   </conbody>
-
 </concept>
diff --git a/specification/archSpec/base/examples-constraints-implemented-using-rng.dita b/specification/archSpec/base/examples-constraints-implemented-using-rng.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="examples-constraints-implemented-using-rng">
-    <title>Examples: Constraints implemented using RNG</title>
-    <shortdesc>This section of the specification contains examples of constraints implemented using
-        RNG</shortdesc>
+<concept id="examples-constraints-implemented-using-rng" rev="2.0">
+  <title>Examples: Constraints implemented using RNG</title>
+  <shortdesc>This section of the specification contains examples of
+    constraints implemented using RNG</shortdesc>
 </concept>
diff --git a/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita b/specification/archSpec/base/examples-expansion-implemented-using-dtds.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="examples_expansion_implemented_using_dtds">
-    <title>Examples: Expansion implemented using DTDs</title>
-    <shortdesc>This section of the specification contains examples of
+<concept id="examples_expansion_implemented_using_dtds" rev="2.0">
+  <title>Examples: Expansion implemented using DTDs</title>
+  <shortdesc>This section of the specification contains examples of
     extension modules that are implemented using DTDs.</shortdesc>
 </concept>
diff --git a/specification/archSpec/base/examples-expansion-implemented-using-rng.dita b/specification/archSpec/base/examples-expansion-implemented-using-rng.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="examples_expansion_implemented_using_rng">
-    <title>Examples: Expansion implemented using RNG</title>
-    <shortdesc>This section of the specification contains examples of extension modules implemented
-        using RNG.</shortdesc>
+<concept id="examples_expansion_implemented_using_rng" rev="2.0">
+  <title>Examples: Expansion implemented using RNG</title>
+  <shortdesc>This section of the specification contains examples of
+    extension modules implemented using RNG.</shortdesc>
 </concept>