oasis-tcs · bburns-hp · Jan 12, 2023 · Jan 13, 2023 · Jan 18, 2023 · Jan 19, 2023
diff --git a/specification/langRef/technicalContent/abbreviated-form.dita b/specification/langRef/technicalContent/abbreviated-form.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="abbreviated-form" xml:lang="en-us">
 <title><xmlelement>abbreviated-form</xmlelement></title>
-<shortdesc>The <xmlelement>abbreviated-form</xmlelement> element represents a reference to a term
-    that might appear in an abbreviated form (often an acronym).</shortdesc>
+<shortdesc>Abbreviated form represents a shorter reference to a term (often an acronym).</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossAbbreviation.dita b/specification/langRef/technicalContent/glossAbbreviation.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossAbbreviation" xml:lang="en-us">
   <title><xmlelement>glossAbbreviation</xmlelement></title>
-  <shortdesc>The <xmlelement>glossAbbreviation</xmlelement> element provides an abbreviated form of
-    the term that is contained in a <xmlelement>glossterm</xmlelement> element.</shortdesc>
+  <shortdesc>The glossary abbreviation provides an abbreviated form of the term that is contained in a glossary term.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossAcronym.dita b/specification/langRef/technicalContent/glossAcronym.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossAcronym" xml:lang="en-us">
   <title><xmlelement>glossAcronym</xmlelement></title>
-  <shortdesc>The <xmlelement>glossAcronym</xmlelement> element defines an acronym for the term that
-    is defined in the <xmlelement>glossterm</xmlelement> element.</shortdesc>
+  <shortdesc>The glossary acronym defines an acronym for a glossary term .</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossAlt.dita b/specification/langRef/technicalContent/glossAlt.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossAlt" xml:lang="en-us">
   <title><xmlelement>glossAlt</xmlelement></title>
-  <shortdesc>The <xmlelement>glossAlt</xmlelement> element contains a variant term for the preferred
-    term that is defined in the <xmlelement>glossterm</xmlelement> element.</shortdesc>
+  <shortdesc>The glossary alternative contains a variant term for the preferred term that is defined in a glossary term.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossAlternateFor.dita b/specification/langRef/technicalContent/glossAlternateFor.dita
@@ -3,11 +3,9 @@
  "reference.dtd">
 <reference id="glossAlternateFor" xml:lang="en-us">
 <title><xmlelement>glossAlternateFor</xmlelement></title>
-<shortdesc>The <xmlelement>glossAlternateFor</xmlelement> element indicates when a variant term has
-    a relationship to another variant term in addition to the preferred term.<draft-comment
-      author="robander" time="20 may 2021">Does it "indicate when a variant term has a relationship"
-      or does it specify that there is a relationship with a specific other
-    term?</draft-comment></shortdesc>
+<shortdesc>The <xmlelement>glossAlternateFor</xmlelement> element indicates when a variant term has a relationship to another variant term as well as the preferred term.<draft-comment
+      author="robander" time="20 may 2021"
+      >Does it "indicate when a variant term has a relationship" or does it specify that there is a relationship with a specific other term?</draft-comment></shortdesc>
 <prolog><metadata>
 <keywords><indexterm><xmlelement>glossAlternateFor</xmlelement></indexterm>
     <indexterm>glossaries<indexterm>variant terms</indexterm></indexterm>
@@ -17,13 +15,7 @@
 <refbody>
     <section id="usage-information">
       <title>Usage information</title>
-      <p>The <xmlelement>glossAlternateFor</xmlelement> element is available inside the
-          <xmlelement>glossAlt</xmlelement> element, which is a container that provides a variant
-        for the primary <xmlelement>glossentry</xmlelement> term. In some cases, the variant might
-        also be an alternate for another term. In the example below, the abbreviation "stick" is a
-        variant of the primary term (USB flash drive). The
-          <xmlelement>glossAlternateFor</xmlelement> element indicates that "stick" is also a
-        variant of the synonym "memory stick".</p>
+      <p>The <xmlelement>glossAlternateFor</xmlelement> element is available inside the <xmlelement>glossAlt</xmlelement> element, which is a container that provides a variant for the primary <xmlelement>glossentry</xmlelement> term. In some cases, the variant might also be an alternate for another term. In the example below, the term "stick" is a variant of the primary term (USB flash drive). The <xmlelement>glossAlternateFor</xmlelement> element indicates that "stick" is also a variant of the synonym "memory stick".</p>
       <draft-comment author="robander" time="20 may 2021">There is a dependency here between the
         usage description and an example that is not actaully given in this topic; that seems risky
         and we should probably move or reuse the example here.</draft-comment>

diff --git a/specification/langRef/technicalContent/glossBody.dita b/specification/langRef/technicalContent/glossBody.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossBody" xml:lang="en-us">
 <title><xmlelement>glossBody</xmlelement></title>
-<shortdesc>The <xmlelement>glossBody</xmlelement> element is used to provide details about a
-      glossary term, such as part of speech or additional forms of the term.</shortdesc>
+<shortdesc>The glossary body provides details about a glossary term, such as part of speech or additional forms of the term.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm><xmlelement>glossBody</xmlelement></indexterm>
             <indexterm>glossentry
@@ -13,10 +12,7 @@
 <refbody>
       <section id="specialization-hierarchy">
          <title>Specialization hierarchy</title>
-         <p>The <xmlelement>glossBody</xmlelement> element is specialized from
-               <xmlelement>conbody</xmlelement>; it is defined in the glossary entry module. The
-               <xmlelement>conbody</xmlelement> element is specialized from
-               <xmlelement>body</xmlelement>; it is defined in the concept module.</p>
+         <p>The <xmlelement>glossBody</xmlelement> element is specialized from <xmlelement>conbody</xmlelement>. It is defined in the glossary entry module. The <xmlelement>conbody</xmlelement> element is specialized from <xmlelement>body</xmlelement>. It is defined in the concept module.</p>
       </section>
       <section id="attributes">
          <title>Attributes</title>

diff --git a/specification/langRef/technicalContent/glossProperty.dita b/specification/langRef/technicalContent/glossProperty.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossProperty" xml:lang="en-us">
 <title><xmlelement>glossProperty</xmlelement></title>
-<shortdesc>The <xmlelement>glossProperty</xmlelement> element specifies additional details about the
-    preferred term or its subject, such as the gender of a noun.</shortdesc>
+<shortdesc>The glossary property provides additional details about the preferred term or its subject, such as the gender of a noun.</shortdesc>
 <prolog><metadata>
 <keywords>
         <indexterm>glossaries<indexterm>extension points</indexterm></indexterm>

diff --git a/specification/langRef/technicalContent/glossScopeNote.dita b/specification/langRef/technicalContent/glossScopeNote.dita
@@ -3,13 +3,9 @@
  "reference.dtd">
 <reference id="glossScopeNote" xml:lang="en-us">
   <title><xmlelement>glossScopeNote</xmlelement></title>
-  <shortdesc>The <xmlelement>glossScopeNote</xmlelement> element contains a clarification of the
-    subject that is designated by the <xmlelement>glossterm</xmlelement>, such as examples of
-    included or excluded companies or products. For instance, a scope note for "Linux" might explain
-    that the term does not apply to UNIX products; it might give examples of Linux products that are
-    included as well as UNIX products that are excluded.<draft-comment author="robander"
-      time="20 may 2021">I think we really need to clarify "the subject that is designated by the
-      glossterm"</draft-comment></shortdesc>
+  <shortdesc>The <xmlelement>glossScopeNote</xmlelement> element clarifies the sense of the <xmlelement>glossterm</xmlelement>, such as inclusions, exclusions, or restrictions of that sense. For instance, a scope note for "Linux" might explain that the term does not apply to UNIX products. It might give examples of Linux products that are included as well as UNIX products that are excluded.<draft-comment
+      author="robander" time="20 may 2021"
+      >I think we really need to clarify "the subject that is designated by the glossterm"</draft-comment></shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossShortForm.dita b/specification/langRef/technicalContent/glossShortForm.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossShortForm" xml:lang="en-us">
 <title><xmlelement>glossShortForm</xmlelement></title>
-<shortdesc>The <xmlelement>glossShortForm</xmlelement> element provides a shorter alternative to the
-    primary term that is specified in the <xmlelement>glossterm</xmlelement> element.</shortdesc>
+<shortdesc>The glossary short form provides a shorter alternative to the primary glossary term.</shortdesc>
 <prolog><metadata>
 <keywords>
         <indexterm>glossaries<indexterm>short forms of a term</indexterm></indexterm>

diff --git a/specification/langRef/technicalContent/glossStatus.dita b/specification/langRef/technicalContent/glossStatus.dita
@@ -3,10 +3,7 @@
  "reference.dtd">
 <reference id="glossStatus" xml:lang="en-us">
   <title><xmlelement>glossStatus</xmlelement></title>
-  <shortdesc>The <xmlelement>glossStatus</xmlelement> element identifies the usage status of a
-    preferred or alternate term. If the status is not specified, the
-      <xmlelement>glossterm</xmlelement> provides a preferred term and an alternate term provides an
-    allowed term.</shortdesc>
+  <shortdesc>The glossary status identifies the usage status of a preferred or alternate term. If the status is not specified, the <xmlelement>glossterm</xmlelement> provides a preferred term, and <xmlelement>glossAlt</xmlelement>provides an allowed term.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossSurfaceForm.dita b/specification/langRef/technicalContent/glossSurfaceForm.dita
@@ -3,9 +3,7 @@
  "reference.dtd">
 <reference id="glossSurfaceForm" xml:lang="en-us">
   <title><xmlelement>glossSurfaceForm</xmlelement></title>
-  <shortdesc>The <xmlelement>glossSurfaceForm</xmlelement> element specifies an unambiguous
-    presentation of the <xmlelement>glossterm</xmlelement> that might combine multiple forms. The
-    surface form is suitable to introduce the term in new contexts.</shortdesc>
+  <shortdesc>The glossary surface form provides an unambiguous presentation of the <xmlelement>glossterm</xmlelement> that might combine multiple forms. The surface form is suitable to introduce the term in new contexts.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossSymbol.dita b/specification/langRef/technicalContent/glossSymbol.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossSymbol" xml:lang="en-us">
 <title><xmlelement>glossSymbol</xmlelement></title>
-<shortdesc>The <xmlelement>glossSymbol</xmlelement> element identifies a standard image that is
-    associated with the subject of the <xmlelement>glossterm</xmlelement> element.</shortdesc>
+<shortdesc>The glossary symbol identifies a standard image that is associated with the subject of the <xmlelement>glossterm</xmlelement> element.</shortdesc>
 <prolog><metadata>
 <keywords>
         <indexterm>glossaries<indexterm>images</indexterm></indexterm>

diff --git a/specification/langRef/technicalContent/glossSynonym.dita b/specification/langRef/technicalContent/glossSynonym.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossSynonym" xml:lang="en-us">
 <title><xmlelement>glossSynonym</xmlelement></title>
-<shortdesc>The <xmlelement>glossSynonym</xmlelement> element provides a term that is a synonym of
-the primary value in the <xmlelement>glossterm</xmlelement> element.</shortdesc>
+<shortdesc>The glossary synonym provides a term that is equivalent in meaning to the primary value in the <xmlelement>glossterm</xmlelement> element.</shortdesc>
 <prolog><metadata>
 <keywords>
             <indexterm>glossaries<indexterm>synonyms</indexterm></indexterm>

diff --git a/specification/langRef/technicalContent/glossUsage.dita b/specification/langRef/technicalContent/glossUsage.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossUsage" xml:lang="en-us">
   <title><xmlelement>glossUsage</xmlelement></title>
-  <shortdesc>The <xmlelement>glossUsage</xmlelement> element provides information about the correct
-    use of a term, such as where or how it can be used.</shortdesc>
+  <shortdesc>Glossary usage provides information about the correct use of a term, such as where or how it can be used.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossdef.dita b/specification/langRef/technicalContent/glossdef.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossdef" xml:lang="en-us">
 <title><xmlelement>glossdef</xmlelement></title>
-<shortdesc>The <xmlelement>glossdef</xmlelement> element specifies the definition of one sense of a
-            term.</shortdesc>
+<shortdesc>The gloss definition describes one sense of a term.</shortdesc>
 <prolog><metadata>
       <keywords>
         <indexterm>glossaries<indexterm>definitions</indexterm></indexterm>

diff --git a/specification/langRef/technicalContent/glossentry.dita b/specification/langRef/technicalContent/glossentry.dita
@@ -3,9 +3,7 @@
  "reference.dtd">
 <reference id="glossentry" xml:lang="en-us">
   <title><xmlelement>glossentry</xmlelement></title>
-  <shortdesc>The <xmlelement>glossentry</xmlelement> element defines a single sense of a glossary
-    term. Glossary entries for different term senses can be reused independently of one
-    another.</shortdesc>
+  <shortdesc>The glossary entry contains information for a single sense of a glossary term. Glossary entries for different term senses can be reused independently of one another.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
@@ -19,21 +17,14 @@
   <refbody>
     <section id="processing-expectations">
       <title>Processing expectations</title>
-      <p>The recommended (but not required) book processing is to sort and group glossary entries
-        based on the localized term so a back-of-the-book glossary can contain a collated list of
-        terms with the definitions of the individual senses of each term indented under the term.
-        The glossary can have a different organization in different languages depending on the
-        translation of the terms.</p>
+      <p>The recommended book processing is to sort and group glossary entries based on the localized term. This processing makes it possible that a back-of-the-book glossary can contain a collated list of terms along with definitions of each sense of each term indented under the term. The glossary can have a different organization in different languages depending on the translation of the terms.</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.</p>
     </section>
     <section id="specialization-hierarchy">
       <title>Specialization hierarchy</title>
-      <p>The <xmlelement>glossentry</xmlelement> element is specialized from
-          <xmlelement>concept</xmlelement>; it is defined in the glossary entry module. The
-          <xmlelement>concept</xmlelement> element is specialized from
-          <xmlelement>topic</xmlelement>; it is defined in the concept module.</p>
+      <p>The <xmlelement>glossentry</xmlelement> element is specialized from <xmlelement>concept</xmlelement>. It is defined in the glossary entry module. The <xmlelement>concept</xmlelement> element is specialized from <xmlelement>topic</xmlelement>. It is defined in the concept module.</p>
     </section>
     <section conkeyref="reuse-topic/attributes" id="attributes"/>
     <example id="example" otherprops="examples">

diff --git a/specification/langRef/technicalContent/glossgroup.dita b/specification/langRef/technicalContent/glossgroup.dita
@@ -3,8 +3,7 @@
  "reference.dtd">
 <reference id="glossgroup" xml:lang="en-us">
   <title><xmlelement>glossgroup</xmlelement></title>
-  <shortdesc>The <xmlelement>glossgroup</xmlelement> is a specialized topic that can contain
-    multiple <xmlelement>glossentry</xmlelement> topics within a single document.</shortdesc>
+  <shortdesc>Glossary group is a specialized topic that can contain multiple <xmlelement>glossentry</xmlelement> topics within a single document.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/specification/langRef/technicalContent/glossref.dita b/specification/langRef/technicalContent/glossref.dita
@@ -3,12 +3,7 @@
  "reference.dtd">
 <reference id="glossref" xml:lang="en-us">
 <title><xmlelement>glossref</xmlelement></title>
-<shortdesc>The <xmlelement>glossref</xmlelement> element is a convenience element in maps for
-creating a reference to a glossary topic. It has a required <xmlatt>keys</xmlatt> attribute, which
-forces the author to create a key by which inline terms can reference their definition. For example,
-when <xmlelement>glossentry</xmlelement> topics are used to define acronyms, this reminds authors to
-create a key which <xmlelement>abbreviated-form</xmlelement> elements can use to reference the short
-and expanded versions of that acronym.</shortdesc>
+<shortdesc>Glossarry reference is a convenience element in maps for creating a reference to a glossary topic. It has a required <xmlatt>keys</xmlatt> attribute, which forces the author to create a key by which inline terms can reference their definition. For example, when <xmlelement>glossentry</xmlelement> topics are used to define acronyms, this reminds authors to create a key which <xmlelement>abbreviated-form</xmlelement> elements can use to reference the short and expanded versions of that acronym.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm><xmlelement>glossref</xmlelement></indexterm>
         <indexterm>glossary-related

diff --git a/specification/langRef/technicalContent/glossterm.dita b/specification/langRef/technicalContent/glossterm.dita
@@ -3,11 +3,9 @@
  "reference.dtd">
 <reference id="glossterm" xml:lang="en-us">
 <title><xmlelement>glossterm</xmlelement></title>
-<shortdesc>The <xmlelement>glossterm</xmlelement> element specifies the preferred term that is
-            associated with a definition of a sense. If the same term has multiple senses, create a
-            separate <xmlelement>glossentry</xmlelement> topic for each sense.<draft-comment
-                  author="robander" time="20 may 2021">associated with a definition of a "sense"? I
-                  think we need to clear that up.</draft-comment></shortdesc>
+<shortdesc>The glossary term indicates the preferred term that is associated with a definition of a sense. If the same term has multiple senses, each should be a separate glossary entry.<draft-comment
+                  author="robander" time="20 may 2021"
+                  >associated with a definition of a "sense"? I think we need to clear that up.</draft-comment></shortdesc>
 <prolog><metadata>
 <keywords>
             <indexterm>glossaries<indexterm>terms</indexterm></indexterm><indexterm>glossentry elements<indexterm><xmlelement>glossterm</xmlelement></indexterm></indexterm>