Merge pull request #459 from keberlein/14-May-2021

Edited config and coding req chapters prior to distributing stage 3 #15

specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita

@@ -33,9 +33,6 @@
             each <codeph>&lt;!ATTLIST</codeph> declaration in its own separate expansion module,
             thus allowing DITA architects who construct document-type shells to decide the elements
             to which to apply the attribute.</p>
-        <draft-comment author="Kristen J Eberlein" time="03 May 2021">
-            <p>Tested and verified that this works as written.</p>
-        </draft-comment>
         <ol>
             <li>First, the DITA architect creates the attribute domain module for the
                     <xmlatt>cell-purpose</xmlatt> attribute:

specification/archSpec/base/coding-requirements.dita

@@ -2,7 +2,7 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept xml:lang="en-us" id="coding-practices">
  <title>Coding practices for DITA grammar files</title>
- <shortdesc>This section collects all of the rules for creating modular DTD, RELAX NG, or XML Schema
-  grammar files to represent DITA document types, specializations, and constraints.</shortdesc>
- <!--<conbody><draft-comment author="robander" time="16 February 2015">For the "specialization" sections - should make sure the shortdescs for nested topics are consistent. 2 use "implementation (coding) requirements" and one uses "coding requirements". Also, I don't think this ensures backwards compatibility, at least with regards to non-OASIS specializations, or am I missing something?</draft-comment></conbody>-->
+ <shortdesc>This section collects all of the rules for creating modular DTD or RELAX NG-based
+  grammar files that represent DITA document types, specializations, constraints, <ph>and expansion
+   modules</ph>.</shortdesc>
 </concept>

specification/archSpec/base/configuration-specialization-and-constraints.dita

@@ -5,7 +5,7 @@
       expansion</ph>
   </title>
   <shortdesc rev="2.0">The extension facilities of DITA allow document-type shells, vocabulary
-    modules, and element-configuration modules (constraints and expansion) to be combined to create
-    specific DITA document types. Vocabulary modules also can be specialized to meet requirements
-    that are not satisfied by existing markup. </shortdesc>
+        modules, and element-configuration modules (constraint and expansion) to be combined to
+        create specific DITA document types. Vocabulary modules also can be specialized to meet
+        requirements that are not satisfied by existing markup. </shortdesc>
 </concept>

specification/archSpec/base/configuration.dita

@@ -2,8 +2,8 @@
 <!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>Document-type configuration 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. Configurations 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 as document-type shells.</shortdesc>
 </concept>

specification/archSpec/base/constraint-rules.dita

@@ -22,7 +22,7 @@
      <p>The content model and attributes of an element can be constrained by only one constraint
       module. If two constraint modules exist that constrain the content model or attributes for a
       specific element, those two modules must be replaced with a new constraint module that
-      reflects the aggregation of the two original constraint modules.</p>
+      reflects the aggregation of the two original modules.</p>
     </dd>
    </dlentry>
    <dlentry>
@@ -32,9 +32,9 @@
       be omitted from the domain extension group or parameter entity. In such a case, there is no
       separate constraint declaration, because the content model is configured directly in the
       document-type shell.</p>
-     <p >A domain module can be constrained by only one constraint module. This
-      means that all restrictions for the extension elements that are defined in the domain must be
-      contained within that one constraint module.</p>
+     <p>A domain module can be constrained by only one constraint module. This means that all
+      restrictions for the extension elements that are defined in the domain must be contained
+      within that one constraint module.</p>
     </dd>
    </dlentry>
    <dlentry>

specification/archSpec/base/constraints-overview.dita

@@ -2,10 +2,10 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept xml:lang="en-us" id="concept_sv4_2gm_vp">
  <title>Overview of constraints</title>
- <shortdesc >Constraint modules enable information architects to restrict the
-  content models or attributes of OASIS-defined DITA grammars. A constraint is a simplification of
-  an XML grammar such that any instance that conforms to the constrained grammar also will conform
-  to the original grammar.<!-- The reverse is not true.--></shortdesc>
+ <shortdesc>Constraint modules enable information architects to restrict the content models or
+  attributes of DITA elements. A constraint is a simplification of an XML grammar such that any
+  instance that conforms to the constrained grammar also will conform to the original
+  grammar.<!-- The reverse is not true.--></shortdesc>
  <prolog>
   <metadata>
    <keywords>
@@ -45,11 +45,13 @@
     <dt>Restrict the elements that are available in a domain</dt>
     <dd>
      <p>Constraint modules can restrict the set of extension elements that are provided in a domain.
-       <ph >They also can restrict the content models for the extension
-       elements.</ph></p>
+      They also can restrict the content models for the extension elements.</p>
      <p otherprops="examples">For example, a constraint on the programming domain can reduce the
       list of included extension elements to <xmlelement>codeph</xmlelement> and
        <xmlelement>codeblock</xmlelement>.</p>
+     <note rev="2.0">For DITA implementations that use RNG-based grammar file, restricting the set of
+      extension elements that are provided in a domain can be handled simply by document-type
+      configuration.</note>
     </dd>
    </dlentry>
    <dlentry>

specification/archSpec/base/constraints-processing-interoperability.dita

@@ -27,6 +27,12 @@
    document type. Thus, for a processor to determine whether a document instance is compatible with
    another document type, the document instance <term outputclass="RFC-2119" 
     >MUST</term> declare any constraints on the document type. </p>
+  <draft-comment author="Kristen J Eberlein" time="14 May 2021">
+   <p>For DITA 2.0, we've removed the requirement to add tokens for constraints. So, I think we need
+    to remove this normative statement. Do we want to replace it with anything? Another statement
+    about constraints and interoperability? This reminds we that we might want to stress for folks
+    that we have removed the entire concept of strong and weak constraints ...</p>
+  </draft-comment>
   <p otherprops="examples">For example, an unconstrained task is compatible with an unconstrained
    topic, because the <xmlelement>task</xmlelement> element can be generalized to
     <xmlelement>topic</xmlelement>. However, if the topic is constrained to require the

specification/archSpec/base/ditaspecialization.dita

@@ -16,40 +16,40 @@
     <dl>
       <dlentry>
         <dt rev="2.0">Document-type configuration</dt>
-        <dd>Document-type configuration 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. Configurations are implemented as document-type
-          shells.</dd>
+        <dd><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.</dd>
       </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 are 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>
+          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>
       </dlentry>
       <dlentry rev="2.0">
         <dt>Element-type configuration</dt>
         <dd>
           <p>Element-type configuration enables DITA architects to modify the content models and
             attribute lists for individual elements, without modifying the vocabulary modules in
             which the elements are defined.</p>
-          <p>There are two types of element configuration: Constraints and expansion. Both
-            constraints and expansions are implemented as modules that are integrated into
-            document-type shells:</p>
+          <p>There are two types of element configuration: Constraint and expansion. Both constraint
+            and expansion are implemented as modules that are integrated into document-type
+            shells:</p>
           <dl>
             <dlentry>
-              <dt>Constraints</dt>
+              <dt>Constraint</dt>
               <dd>Constraint modules enables the restriction of content models and attribute lists
                 for individual elements.</dd>
             </dlentry>
             <dlentry>
-              <dt>Expansions</dt>
+              <dt>Expansion</dt>
               <dd>Expansion modules enable the expansion of content models and attribute lists for
                 individual elements.</dd>
             </dlentry>

specification/archSpec/base/document-type-shells-equivalence.dita

@@ -14,7 +14,7 @@
   <conbody>
     <p>A DITA document type is defined by the following:</p>
     <ul>
-      <li>The set of vocabulary and <ph rev="2.0">element-configuration modules (constraints and
+      <li>The set of vocabulary and <ph rev="2.0">element-configuration modules (constraint and
           expansion)</ph> that are integrated by the document type shell </li>
       <li>The values of the <xmlatt>class</xmlatt> attributes of all the elements in the
         document</li>
@@ -31,9 +31,9 @@
       <li>It has a distinct system identifier.</li>
       <li>If it has a public identifier, the public identifier is unique.</li>
     </ul>
-    <note>The public or system identifier that is associated with a given document-type shell is
-      not, by itself, necessarily distinguishing. This is because two different people or groups
-      might use the same modules and constraints to assemble equivalent document type shells, while
-      giving them different names or public identifiers. </note>
+    <note>The public or system identifier that is associated with a given document-type shell is not
+      necessarily distinguishing. Two different people or groups might use the same modules and
+      constraints to assemble equivalent document type shells, while giving them different names or
+      public identifiers. </note>
   </conbody>
 </concept>

specification/archSpec/base/document-type-shells.dita

@@ -14,49 +14,47 @@
 		</metadata>
 	</prolog> 
   <conbody> 
-	 <p>A DITA document must either have an associated document-type definition
-		or all required attributes must be made explicit in the document instances.
-		Most DITA documents have an associated document-type shell. DITA documents that
-		reference a document-type shell can be validated using standard XML processors.
-		Such validation enables processors to read the XML grammar files and determine
-		default values for the <xmlatt>specializations</xmlatt> and <xmlatt>class</xmlatt>
-		attributes. 
-	 </p> 
+	 <p>A DITA document either must have an associated document-type definition or all required
+			attributes must be made explicit in the document instances. Most DITA documents have an
+			associated document-type shell. DITA documents that reference a document-type shell can
+			be validated using standard XML processors. Such validation enables processors to read
+			the XML grammar files and determine default values for the
+				<xmlatt>specializations</xmlatt> and <xmlatt>class</xmlatt> attributes. </p> 
 	 <p>The following figure illustrates the relationship between a DTD-based DITA document, its
 			document-type shell, the vocabulary modules that it uses, <ph rev="2.0">and the
-				element-configuration modules (constraints and expansions) that it integrates</ph>.
+				element-configuration modules (constraint and expansion) that it integrates</ph>.
 			Similar structure applies to DITA documents that use other XML grammars. </p> 
-	 <fig id="fig_A20B8879F2D94F41B6B732A546C8D772"> 
-		<title>Document type shell</title> 
-		<image href="../../images/instances-modules-declarations-01.png"
-		 placement="break" id="image_1EB5D8D620784EBA9C6D5F250A8C321B" scale="70"
-		 > 
-		  <alt>Diagram showing a typical architecture of a DITA document type shell. At the top left a
-					DITA document file named <filepath>myTopic.dita</filepath> refers to a document
-					type of 'myTopic'. An arrow from this file points to a document-type shell file
-					named <filepath>myTopic.dtd</filepath>. Arrows point to several other modules. A
-					constraint module is named <filepath>strictMyTopicConstraint.mod</filepath>.
-					Structural modules are named <filepath>mytopic.ent</filepath>,
-						<filepath>mytopic.mod</filepath>, <filepath>topic.ent</filepath>, and
-						<filepath>topic.mod</filepath>. Domain modules are named
-						<filepath>myPhraseDomain.ent</filepath>,
+	 <fig>
+			<title>Document type shell</title>
+			<image href="../../images/instances-modules-declarations-01.png" placement="break"
+				scale="70">
+				<alt>Diagram showing a typical architecture of a DITA document type shell. At the
+					top left a DITA document file named <filepath>myTopic.dita</filepath> refers to
+					a document type of 'myTopic'. An arrow from this file points to a document-type
+					shell file named <filepath>myTopic.dtd</filepath>. Arrows point to several other
+					modules. A constraint module is named
+						<filepath>strictMyTopicConstraint.mod</filepath>. Structural modules are
+					named <filepath>mytopic.ent</filepath>, <filepath>mytopic.mod</filepath>,
+						<filepath>topic.ent</filepath>, and <filepath>topic.mod</filepath>. Domain
+					modules are named <filepath>myPhraseDomain.ent</filepath>,
 						<filepath>myPhraseDomain.mod</filepath>,
 						<filepath>highlightDomain.ent</filepath>,
 						<filepath>highlightDomain.mod</filepath>,
 						<filepath>programmingDomain.ent</filepath>, and
 						<filepath>programmingDomain.mod</filepath>. The structural and domain
-					modules are grouped together and labeled vocabulary modules. </alt> 
-		</image> 
-	 </fig>
+					modules are grouped together and labeled vocabulary modules. </alt>
+			</image>
+		</fig>
 		<draft-comment author="Kristen J Eberlein" time="28 March 2021">
 			<p>The illustration needs to be updated to include expansion modules.</p>
 		</draft-comment> 
 	 <p>The DITA specification contains a starter set of document-type shells. These document-type
 			shells are commented and can be used as templates for creating custom document-type
-			shells. While the OASIS-provided document-type shells can be used without any
-			modification, creating custom document-type shells is a best practice. If the
-			document-type shells need to be modified in the future, for example, to include a
-			specialization or integrate a constraint, the existing DITA documents will not need to
-			be modified to reference a new document-type shell. </p> 
+			shells.</p>
+		<p>While the OASIS-provided document-type shells can be used without any modification,
+			creating custom document-type shells is a best practice. If the document-type shells
+			need to be modified in the future, for example, to include a specialization or integrate
+			a constraint, the existing DITA documents will not need to be modified to reference a
+			new document-type shell. </p> 
   </conbody> 
 </concept> 

specification/archSpec/base/dtd-coding-overview.dita

@@ -49,11 +49,11 @@
      <p>Every element in a DITA DTD defines its content model using an entity. <ph rev="2.0">This
        enables element configuration.</ph></p>
      <example>For example, rather than directly setting what is allowed in
-       <xmlelement>ph</xmlelement>, that element sets its content model to
-       <codeph>%ph.content;</codeph>; that entity defines the actual content model. <ph rev="2.0">A
-       constraint module can redefine the <codeph>%ph.content;</codeph> model to remove selected
-       elements, or an expansion module can redefine the <codeph>%ph.content;</codeph> module to add
-       elements.</ph>.</example>
+              <xmlelement>ph</xmlelement>, that element sets its content model to
+              <codeph>%ph.content;</codeph>; that entity defines the actual content model. <ph
+              rev="2.0">A constraint module can redefine the <codeph>%ph.content;</codeph> model to
+              remove selected elements, or an expansion module can redefine the
+                <codeph>%ph.content;</codeph> module to add elements</ph>.</example>
     </dd>
    </dlentry>
    <dlentry>

specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita

@@ -45,13 +45,6 @@
                             expansion attribute and should not be included in the
                                 <parameterentity>base-attribute-extensions</parameterentity> entity
                             in the document-type shell.</p>
-                        <draft-comment author="Kristen J Eberlein" time="08 April 2021">
-                            <p>Should we call this
-                                    <codeph><varname>tagname</varname>.attributes</codeph> parameter
-                                entity? Or would
-                                    <codeph><varname>Domain</varname>.attributes</codeph> parameter
-                                entity be more appropriate?</p>
-                        </draft-comment>
                     </dd>
                 </dlentry>
                 <dlentry>