Merge pull request #479 from keberlein/18-May-2021

Updates for "Loosen specialization rules"

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

@@ -18,7 +18,7 @@
     </prolog>
     <conbody>
         <p>The DITA architect decides to create a new attribute (<xmlatt>cell-purpose</xmlatt>) and
-            add it to the content model of the following elements:</p>
+            add it to the attribute lists of the following elements:</p>
         <ul>
             <li><xmlelement>entry</xmlelement></li>
             <li><xmlelement>row</xmlelement></li>
@@ -29,13 +29,28 @@
         <p>The new attribute will be specialized from <xmlatt>base</xmlatt>; it will have a small
             set of tokens that can be values for the new attribute.</p>
         <p>The DITA architect decides to integrate the attribute declaration and its assignment to
-            elements into a single expansion module. An alternate approach would be to separate each
+            elements into a single expansion module. An alternate approach would be to put 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>
         <ol>
-            <li>First, the DITA architect creates the attribute domain module for the
-                    <xmlatt>cell-purpose</xmlatt> attribute:
+            <li><draft-comment author="Kristen J Eberlein" time="07 June 2021">
+                    <p>Comments by Eliot Kimber: </p>
+                    <p>[Re defining the attribute]: I don't really see the value in having the
+                        "-expansion" distinction here--whether to use this as a global attribute or
+                        through extension is really up to the doc type shell author. The definer of
+                        the attribute domain may intend for it to be used only on specific element
+                        types but that's not really their choice to make."</p>
+                    <p>[Re the entity to be used in the @specializations attribute]: "Should there
+                        be leading and trailing space in the replacement text?"</p>
+                    <p>[Re adding the attribute to the elements]: "I first thought we shouldn't
+                        allow this specialization-and-integration-in-one kind of module but I
+                        convinced myself it's OK. However, we still need an example of not doing
+                        this, for example, taking an *existing* attribute domain and using a
+                        separate extension module to allow it in specific places, omitting the usual
+                        global integration."</p>
+                </draft-comment>First, the DITA architect creates the attribute domain module for
+                the <xmlatt>cell-purpose</xmlatt> attribute:
                     <filepath>acme-cellPurposeAttExpansion.ent</filepath>.<codeblock>&lt;!-- Define the attribute -->
 &lt;!ENTITY % cellPurposeAtt-d-attribute-expansion
   "cell-purpose  (sale | out-of-stock | new | last-chance | inherit | none)  #IMPLIED"
@@ -53,15 +68,24 @@
                     attribute definition entity ends in <codeph>-expansion</codeph>; this indicates
                     that this is an expansion attribute and should not be included in the
                         <parameterentity>base-attribute-extensions</parameterentity> entity in the
-                    document-type shell.</note><draft-comment author="Kristen J Eberlein"
+                    document-type shell.<draft-comment author="Kristen J Eberlein"
+                        time="07 June 2021">
+                        <p>Comment by Eliot Kimber: "See my comment above: I don't think we should
+                            do this."</p>
+                    </draft-comment></note><draft-comment author="Kristen J Eberlein"
                     time="18 May 2021">
                     <p>Comment by Robert Anderson: "[The note] should clarify that this entity is
                         totally optional -- only useful here because we're adding the same attribute
                         with the same tokens to several elements. If you're only adding one
                         attribute to one element, you wouldn't want this entity."</p>
                 </draft-comment></li>
             <li>The DITA architect updates the <filepath>catalog.xml</filepath> file to include the
-                expansion module.</li>
+                expansion module.<draft-comment author="Kristen J Eberlein" time="07 June 2021">
+                    <p>Comment by Eliot Kimber: "This is something almost everybody *would* do but
+                        it's not actually required since the use of catalogs is not required by DITA
+                        or by the use of DTDs generally, at least in theory (and in actual fact if
+                        you are an Author/Editor user, which doesn't support catalogs)."</p>
+                </draft-comment></li>
             <li>The DITA architect integrates this module into the document-type
                 shell.<codeblock>&lt;!-- ============================================================= -->
 &lt;!--             DOMAIN ATTRIBUTES DECLARATIONS                    -->

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

@@ -23,16 +23,6 @@
    unconstrained document type with an optional <xmlelement>shortdesc</xmlelement> element. Thus,
    the content processing for topic still works when <xmlelement>topic</xmlelement> is constrained
    to require a short description.</p>
-  <p>A constrained document type allows only a subset of the possible instances of the unconstrained
-   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
@@ -41,5 +31,15 @@
    a <xmlelement>shortdesc</xmlelement> element. However, if the task document type also has been
    constrained to require the <xmlelement>shortdesc</xmlelement> element, it is compatible with the
    constrained topic 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; accordingly I
+    removed the following paragraph:</p>
+   <p>"A constrained document type allows only a subset of the possible instances of the
+    unconstrained 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>
+   <p>Does this topic make sense without that paragraph? How do we need to rework it? Does it need
+    to cover anything about</p>
+  </draft-comment>
  </conbody>
 </concept>

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

@@ -17,8 +17,8 @@
 	 <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
+			be validated using most 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

specification/archSpec/base/expansion-module-rules.dita

@@ -20,6 +20,12 @@
                 sentence, maybe at the top: "The generalized form of an expanded element's content
                 model must match that of the unexpanded content model." All of what follows stems
                 from this statement."</p>
+            <p>Comment by Eliot Kimber: "I think this is an expansion of the suggested qualification
+                of expansion I suggested for a much earlier point in the spec. I'm not sure it's
+                necessary to go into this level of detail because the constraints on expansion
+                should be clear based on the "no less constrained" requirement. That said, it's
+                always helpful to have examples. Maybe this is better represented as a set of
+                non-normative examples?"</p>
         </draft-comment>
         <dl>
             <dlentry>
@@ -51,6 +57,11 @@
                             child of &lt;ol>, and then make all following list items optional. It's
                             valid because every list has at least one list item (that specialized
                             thing), but it changes lists to make a required &lt;li> optional."</p>
+                        <p>Comment from Eliot Kimber: "I would say "violate" here, since per
+                            Robert's comment, you can change the ordinality as long as the result is
+                            consistent with the original. If A is only allowed before B you can't
+                            change that but if A and B are in an OR group you can put them into a
+                            sequence by extension."</p>
                     </draft-comment>
                     <div otherprops="examples">
                         <p>For example, a DITA architect wants to add a new specialization of
@@ -72,6 +83,19 @@
                                 alternate title takes its place, which again, we might need to
                                 redefine "ordinality" as "DITA ordinality" to cover
                                 specialization?"</p>
+                            <p>Comment from Eliot: "Using title in section as an example is both
+                                problematic but also very instructive. It's problematic because the
+                                grammar is *less constrained* than the prose of the specification,
+                                so the rule as stated in Kris' text is correct--the *prose* doesn't
+                                allow &lt;title> anywhere except as the first child of &lt;section>,
+                                so the solution proposed is correct, in particular, the requirement
+                                to make a choice between &lt;title> and the &lt;specialization>,
+                                *because of the prose-imposed rule*, a rule not expressed in the
+                                grammars. A better example, or at least a more obvious one, would be
+                                an expansion of an element whose base content model is a sequence
+                                (i.e., prolog). That said, it's probably useful to focus on
+                                &lt;section> for this because so many people don't understand this
+                                subtlety of &lt;section>."</p>
                         </draft-comment>
                     </div>
                 </dd>

specification/archSpec/base/overview-of-expansion-modules.dita

@@ -27,7 +27,7 @@
                             <xmlelement>p</xmlelement>, but it is available only within
                             <xmlelement>section</xmlelement>.</p>
                     <p>The elements must be defined in a separate element domain that declares the
-                        content model and attributes list for the new elements.</p>
+                        content models and attribute lists for the new elements.</p>
                     <!--<draft-comment author="Kristen J Eberlein" time="28 March 2021"><p>In your draft, you mention that the specialization module must not "make the element available gobally." Do you have an example of this? Is it as simple as not having an ENT file that declares the extension entities?</p></draft-comment>-->
                 </dd>
             </dlentry>

specification/archSpec/base/relax-ng-coding-requirements-for-element-configuration-modules.dita

@@ -119,6 +119,21 @@
                                 <p>Need an example of this. And do we really want to recommend that
                                     people do this? When would doing this make sense/be a best
                                     practice?</p>
+                                <p>Comment from Robert Anderson, 17 May 2021: " I think you would
+                                    most likely want to chain them if you're reusing someone else's
+                                    constraint. For example, if someone wants to use the strict task
+                                    from OASIS but also wants to constrain &lt;step>, they could
+                                    import their module to constrain step, which then imports the
+                                    OASIS constraint for taskbody, which imports the core task
+                                    module. I find it hard to imagine chaining more than a couple,
+                                    because every one you add becomes more specific to your
+                                    configuration."</p>
+                                <p>Comment from Eliot Kimber, 18 May 2021: "I would be tempted to
+                                    just drop this discussion entirely. I think it's an edge case
+                                    for the reasons Robert gives. It's also inherent in the way RNG
+                                    works: anyone who understands RNG well enough to do this
+                                    understands it enough to know that they *can* do it--we don't
+                                    have to tell them how to do it (or that it's possible)."</p>
                             </draft-comment>
                         </div>
                     </dd>

specification/archSpec/base/specialization-class-attribute.dita

@@ -50,16 +50,22 @@
     </section>
     <section id="rules">
       <title>Rules</title>
-      <draft-comment author="robander">Question about the following statement.
-      If a topic has no integrated attribute domains in 2.0, the value of @specializations
-      will be empty. Is this really a MUST? Should we clarify to indicate that this must
-      be declared in the grammar, but does not necessarily need to have a value - I know
-      that has caused confusion in the past for a tool that reported errors for empty @domains</draft-comment>
-      <p>The root element of every topic and map <term outputclass="RFC-2119">MUST</term> declare
-        the following attributes:<ul>
-          <li><xmlatt>class</xmlatt></li>
-          <li><xmlatt>specializations</xmlatt></li>
-        </ul></p>
+      <draft-comment author="robander">Question about the following statement. If a topic has no
+        integrated attribute domains in 2.0, the value of @specializations will be empty. Is this
+        really a MUST? Should we clarify to indicate that this must be declared in the grammar, but
+        does not necessarily need to have a value - I know that has caused confusion in the past for
+        a tool that reported errors for empty @domains<p>Response by Eliot Kimber, 18 May 2021:</p><lq>
+          <p>If @specializations is only relevant to attribute specializations then I think it would
+            be sensible to allow it to be omitted, with an omitted @specializations being equivalent
+            to specializations="" (empty or whitespace-only value).</p>
+          <p>The counter to that approach is that you can't easily distinguish between really having
+            no attribute specializations and just forgetting to provide @specializations, but in
+            that case I think you'd get runtime failures if you actually had specializations that
+            weren't declared (i.e., your @props specializations aren't recognized so things don't
+            filter correctly).</p>
+          <p>Seems like an edge case in practice since DITA defines a number of out-of-the box
+            attribute specializations, including now all of the original conditional attributes.</p>
+        </lq></draft-comment>
       <p>Every DITA element (except the <xmlelement>dita</xmlelement> element that is used as the
         root of a ditabase document) <term outputclass="RFC-2119">MUST</term> declare a
           <xmlatt>class</xmlatt> attribute.</p>

specification/archSpec/base/specialization-rules-elements.dita

@@ -18,25 +18,13 @@
       <li>A properly-formed <xmlatt>class</xmlatt> attribute that specifies the specialization
         hierarchy of the element</li>
       <li>A content model that is the same or less inclusive than that of the element from which it
-        was specialized</li>
+        was specialized <ph rev="2.0">after generalization</ph></li>
       <li>A set of attributes that are the same or a subset of those of the element from which it
-        was specialized</li>
+        was specialized<ph rev="2.0">, except for specializations of <xmlatt>base</xmlatt> or
+            <xmlatt>props</xmlatt></ph></li>
       <li>Values or value ranges of attributes that are the same or a subset of those of the element
         from which it was specialized</li>
     </ul>
-    <draft-comment author="Kristen J Eberlein" time="14 May 2021">
-      <p>OK, what verbiage do we want to add here to cover what we permit with expansion
-        modules?</p>
-      <p>Suggestions from Chris Nitchie:</p>
-      <ul>
-        <li>Modify the 2nd bullet point to add "... after generalization. Specializations of
-          elements from the base element's content model are allowed, so long as they are only
-          allowed in the same location in the content model as the elements from which they are
-          specialized."</li>
-        <li>Modify the 3rd bullet point to add ""... except for specializations of @props or
-          @base."</li>
-      </ul>
-    </draft-comment>
     <p>DITA elements are never in a namespace. Only the <xmlatt>DITAArchVersion</xmlatt> attribute
       is in a DITA-defined namespace. All other attributes, except for those defined by the XML
       standard, are in no namespace.</p>