Merge pull request oasis-tcs#255 from robander/glossfix

Minor cleanup and draft comments for glossary content

specification/langRef/technicalContent/glossAbbreviation.dita

@@ -3,11 +3,9 @@
  "reference.dtd">
 <reference id="glossAbbreviation" xml:lang="en-us">
   <title><xmlelement>glossAbbreviation</xmlelement></title>
-  <abstract>
-    <shortdesc>The <xmlelement>glossAbbreviation</xmlelement> element provides an abbreviation of
-      the term specified in the topic's <xmlelement>glossterm</xmlelement> element. Abbreviations
-      are typically formed by omitting some letters from a longer form. </shortdesc>
-  </abstract>
+  <shortdesc>The <xmlelement>glossAbbreviation</xmlelement> element provides an abbreviation of the
+    term specified in the topic's <xmlelement>glossterm</xmlelement> element. Abbreviations are
+    typically formed by omitting some letters from a longer form.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

specification/langRef/technicalContent/glossAcronym.dita

@@ -6,7 +6,7 @@
   <shortdesc>The <xmlelement>glossAcronym</xmlelement> element defines an acronym for the term
     specified in the topic's <xmlelement>glossterm</xmlelement> element. An acronym typically is
     composed of the initial letters of the components of the full form or from the syllables of the
-    full form to create a pronounceable combination of letters. </shortdesc>
+    full form to create a pronounceable combination of letters.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

specification/langRef/technicalContent/glossPartOfSpeech.dita

@@ -4,9 +4,9 @@
 <reference id="glossPartOfSpeech" xml:lang="en-us">
   <title><xmlelement>glossPartOfSpeech</xmlelement></title>
   <shortdesc>The <xmlelement>glossPartOfSpeech</xmlelement> element identifies the part of speech
-    for the term specified in the topic's <xmlelement>glossterm</xmlelement> element., and any
+    for the term specified in the topic's <xmlelement>glossterm</xmlelement> element, and any
     variant forms of the term also defined within the topic. term and any alternate or variant forms
-    of the term defined within the topic. </shortdesc>
+    of the term defined within the topic.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

specification/langRef/technicalContent/glossProperty.dita

@@ -20,7 +20,7 @@
         attribute and its corresponding value in the <xmlatt>value</xmlatt> attribute. Because any
         number of properties can therefore be defined, implementers may want to control these values
         using subject scheme maps to bind values to these attributes within
-          <xmlelement>glossProperty</xmlelement>. </p>
+          <xmlelement>glossProperty</xmlelement>.</p>
     </section>
     <section id="specialization-hierarchy">
       <title>Specialization hierarchy</title>

specification/langRef/technicalContent/glossScopeNote.dita

@@ -20,8 +20,6 @@
       <title>Specialization hierarchy</title>
       <p>The <xmlelement>glossScopeNote</xmlelement> element is specialized from
           <xmlelement>note</xmlelement>. It is defined in the glossary entry module.</p>
-    </section>
-    <section conkeyref="reuse-note/attributes" id="attributes">
       <p>
         <draft-comment author="dawnstevens">Although I realize the element is specialized from Note,
           I question the need to point out the type and othertype attributes; they don't seem to me
@@ -34,6 +32,16 @@
           meaning for a glossScopeNote to be any specific "type". Its type is a scope note. Do we
           have to document that these attributes are available? </draft-comment>
       </p>
+      <p>
+        <draft-comment author="robander" time="Jan 18 2024">For every attribute that is defined, we
+          need to include it in the attribute list, whether we expect it to be used or not. If we
+          want to modify this (but not remove the attributes), then we need to modify the conref to
+          "note" so that we pull in the attribute list, but then add an exception saying that these
+          attributes will not typically be used, that the type is expected to be a scope
+          note.</draft-comment>
+      </p>
+    </section>
+    <section conkeyref="reuse-note/attributes" id="attributes">
     </section>
     <example id="example" otherprops="examples">
       <title>Example</title>

specification/langRef/technicalContent/glossStatus.dita

@@ -4,7 +4,7 @@
   <title><xmlelement>glossStatus</xmlelement></title>
   <shortdesc>The <xmlelement>glossStatus</xmlelement> element identifies the status of the term
     specified in the topic's <xmlelement>glossterm</xmlelement> element or any of its alternative
-    forms specified within a <xmlelement>glossAlt</xmlelement> element. </shortdesc>
+    forms specified within a <xmlelement>glossAlt</xmlelement> element.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

specification/langRef/technicalContent/glossUsage.dita

@@ -25,6 +25,12 @@
         question the need to point out the type and othertype attributes; they don't seem to me to
         have any meaning in the content of a usage note. A usage note is type usage note, in my
         mind. Why would anyone specify any type or othertype?</draft-comment>
+      <draft-comment author="robander" time="Jan 18, 2024">For every attribute that is defined, we
+        need to include it in the attribute list, whether we expect it to be used or not. If we want
+        to modify this (but not remove the attributes), then we need to modify the conref to "note"
+        so that we pull in the attribute list, but then add an exception saying that these
+        attributes will not typically be used, that the type is expected to be a scope usage
+        note.</draft-comment>
     </section>
     <section conkeyref="reuse-note/attributes" id="attributes"/>
     <example id="example" otherprops="examples">

specification/langRef/technicalContent/glossdef.dita

@@ -3,7 +3,7 @@
 <reference id="glossdef" xml:lang="en-us">
 <title><xmlelement>glossdef</xmlelement></title>
 <shortdesc>The <xmlelement>glossdef</xmlelement> element defines the meaning of the term specified
-    in the topic's <xmlelement>glossterm</xmlelement> element. </shortdesc>
+        in the topic's <xmlelement>glossterm</xmlelement> element.</shortdesc>
 <prolog><metadata>
       <keywords>
         <indexterm>glossaries<indexterm>definitions</indexterm></indexterm>

specification/langRef/technicalContent/glossentry.dita

@@ -35,7 +35,10 @@
         have a different organization in different languages depending on the translation of the
           terms.<draft-comment author="dawnstevens">The phrasing of the first sentence suggests to
           me that we expect the processor to automatically sort the terms alphabetically. Should we
-          rephrase?</draft-comment></p>
+          rephrase?</draft-comment><draft-comment author="robander" time="Jan 18 2024">Agreed, I
+          don't know of tools that do that now and the spec should not imply that it is "expected" –
+          that said it is certainly a valid implementation, so it could be described like the next
+          paragraph, "one possible implementation</draft-comment></p>
       <p>One possible implementation of a glossary in online processing is to associate a hotspot
         for mentions of terms in <xmlelement>term</xmlelement> elements and display the definition
         on hover or click. A possible implementation in PDF processing is to define a first-use

specification/langRef/technicalContent/glossterm.dita

@@ -34,7 +34,7 @@
       <glossAcronym>CSS</glossAcronym>
     </glossAlt>
     <glossAlt>
-      <glossSynonym>web style sheets</glossShortForm>
+      <glossSynonym>web style sheets</glossSynonym>
     </glossAlt>
   </glossBody>
 &lt;/glossentry></codeblock>