Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated examples in glossary element topics that remain #261

Open
wants to merge 1 commit into
base: DITA-2.0
Choose a base branch
from
Open

Updated examples in glossary element topics that remain #261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 20 additions & 6 deletions specification/archSpec/technicalContent/dita-glossary-topic.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,8 @@
<ul>
<li>They ensure that a team of writers can use the same
terminology.</li>
<li>They make it possible to create glossaries that can be use to
provide readers with definitions of terms and explanations about
acronyms.</li>
<li>They make it possible to create glossaries that can be used to provide readers with
definitions of terms and explanations about acronyms.</li>
</ul>
</section>
<!--<section><title>The purpose of the glossary entry topic</title><p>Defining terminology in a glossary ensures that a team of writers uses the same term for the same concept. A glossary added to a book or available online in conjunction with other subject matter provides the reader with definitions of unfamiliar terms and expands acronyms.</p></section>-->
Expand All @@ -39,12 +38,27 @@
<p>The following code sample contains a simple glossentry topic:</p>
<codeblock>&lt;glossentry id="ddl">
&lt;glossterm>data definition language&lt;/glossterm>
&lt;glossdef>A language used for defining database schemas&lt;/glossdef>
&lt;glossdef>A language used for defining database schemas&lt;/glossdef><?oxy_insert_start author="dawnstevens" timestamp="20240507T073646-0600"?>
&lt;glossBody>
&lt;glossSurfaceForm>data definition language (DDL)&lt;/glossSurfaceForm>
&lt;glossAlt>
&lt;glossAcronym>DDL&lt;/glossAcronym>
&lt;/glossAlt>
&lt;glossBody>
&lt;related-links>
&lt;link href="data_control_language.dita"/>
&lt;link href="data_manipulation_language.dita"/>
&lt;link href="data_query_language.dita"/>
&lt;link href="sql.dita"/><?oxy_insert_end?>
&lt;/glossentry></codeblock>
<draft-comment author="Kristen J Eberlein" time="07 October 2022">
<p>This should have a glossbody that specifies an acronym and a
surface term. Also related links.</p>
<p>This should have a glossbody that specifies an acronym and a surface term. Also related
links.</p>
</draft-comment>
<?oxy_insert_start author="dawnstevens" timestamp="20240507T073655-0600"?>
<draft-comment author="dawnstevens">Done</draft-comment>
<?oxy_insert_end?>
</example>
</conbody>
</concept>
<?oxy_options track_changes="on"?>
48 changes: 33 additions & 15 deletions specification/langRef/technicalContent/glossAcronym.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,13 @@
"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
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>
<shortdesc>The <xmlelement>glossAcronym</xmlelement> element defines
<?oxy_delete author="dawnstevens" timestamp="20240507T073807-0600" content="an acronym "?><?oxy_insert_start author="dawnstevens" timestamp="20240507T073807-0600"?>a
shortened form <?oxy_insert_end?>for the term specified in the topic's
<xmlelement>glossterm</xmlelement>
element<?oxy_insert_start author="dawnstevens" timestamp="20240507T073814-0600"?>, such as an
acronym, initialism, or abbreviation<?oxy_insert_end?>.
<?oxy_delete author="dawnstevens" timestamp="20240507T073834-0600" content="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>
<prolog>
<metadata>
<keywords>
Expand All @@ -21,17 +24,31 @@
<section id="usage-information">
<title>Usage information</title>
<p>This element can be used with the <xmlelement>abbreviated-form</xmlelement> element to
display an expanded version of an acronym the first time that acronym appears in a set of
text. See <xref href="abbreviated-form.dita"
><xmlelement>abbreviated-form</xmlelement></xref> for information on how the two elements
interact.</p>
<note>An acronym in one language might not have an equivalent in another language. When
acronyms are first displayed, some languages will display the expanded form first followed
by the acronym in parenthesis, while other languages do the reverse. For some acronyms, a
translation might need to render both the original and the translated version of the
acronym. For all of these reasons, DITA allows an author or translator to control what is
presented to a reader by using the <xmlelement>glossSurfaceForm</xmlelement> element, which
will often accompany the <xmlelement>glossAcronym</xmlelement>. The <xref
display <?oxy_insert_start author="dawnstevens" timestamp="20240507T073947-0600"?>either
<?oxy_insert_end?>an expanded version of
<?oxy_delete author="dawnstevens" timestamp="20240507T073903-0600" content="an acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T073903-0600"?>the
term<?oxy_insert_end?> the first time that
<?oxy_delete author="dawnstevens" timestamp="20240507T073907-0600" content="acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T073907-0600"?>term<?oxy_insert_end?>
appears in a set of
text<?oxy_insert_start author="dawnstevens" timestamp="20240507T073951-0600"?> or the
shortened version defined in this element on subsequent occurrences of the
term<?oxy_insert_end?>. See <xref href="abbreviated-form.dita"
><xmlelement>abbreviated-form</xmlelement></xref> for information on how the two
elements interact.</p>
<note>A<?oxy_delete author="dawnstevens" timestamp="20240507T074049-0600" content="n acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074049-0600"?>
shortened form of a term<?oxy_insert_end?> in one language might not have an equivalent in
another language. When
<?oxy_delete author="dawnstevens" timestamp="20240507T074104-0600" content="acronyms"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074104-0600"?>shortened
terms<?oxy_insert_end?> are first displayed, some languages will display the expanded form
first followed by the
<?oxy_delete author="dawnstevens" timestamp="20240507T074112-0600" content="acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074112-0600"?>shortened
form<?oxy_insert_end?> in parenthesis, while other languages do the reverse. For some
<?oxy_delete author="dawnstevens" timestamp="20240507T074122-0600" content="acronyms"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074122-0600"?>terms<?oxy_insert_end?>,
a translation might need to render both the original and the translated version of the
<?oxy_delete author="dawnstevens" timestamp="20240507T074126-0600" content="acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074126-0600"?>shortened
form<?oxy_insert_end?>. For all of these reasons, DITA allows an author or translator to
control what is presented to a reader by using the <xmlelement>glossSurfaceForm</xmlelement>
element, which will often accompany the <xmlelement>glossAcronym</xmlelement>. The <xref
href="abbreviated-form.dita"><xmlelement>abbreviated-form</xmlelement></xref> topic
contains information on how the <xmlelement>glossSurfaceForm</xmlelement> and
<xmlelement>glossAcronym</xmlelement> elements affect references to the term.</note>
Expand Down Expand Up @@ -63,3 +80,4 @@
</example>
</refbody>
</reference>
<?oxy_options track_changes="on"?>
3 changes: 2 additions & 1 deletion specification/langRef/technicalContent/glossAlt.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@
&lt;glossUsage>Do not use; the American continents include other countries.&lt;/glossUsage>
<b>&lt;/glossAlt>
&lt;glossAlt></b>
&lt;glossAbbreviation>the States&lt;/glossAbbreviation>
&lt;glossA<?oxy_delete author="dawnstevens" timestamp="20240507T074506-0600" content="bbreviation"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074506-0600"?>cronym<?oxy_insert_end?>>the States&lt;/glossA<?oxy_delete author="dawnstevens" timestamp="20240507T074511-0600" content="bbreviation"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074511-0600"?>cronym<?oxy_insert_end?>>
&lt;glossUsage>Informal. Typically used by English speakers outside of the country.&lt;/glossUsage>
<b>&lt;/glossAlt></b>
&lt;/glossBody><b>
Expand All @@ -75,3 +75,4 @@
</example>
</refbody>
</reference>
<?oxy_options track_changes="on"?>
57 changes: 39 additions & 18 deletions specification/langRef/technicalContent/glossBody.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
<reference id="glossBody" xml:lang="en-us">
<title><xmlelement>glossBody</xmlelement></title>
<shortdesc>The <xmlelement>glossBody</xmlelement> element contains information about the term
specified in the topic's <xmlelement>glossterm</xmlelement> element, such as the part of speech
and variants for the term.</shortdesc>
specified in the topic's <xmlelement>glossterm</xmlelement> element, such as
<?oxy_delete author="dawnstevens" timestamp="20240507T074606-0600" content="the part of speech and "?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074606-0600"?>usage
and <?oxy_insert_end?>variants for the term.</shortdesc>
<prolog><metadata>
<keywords><indexterm><xmlelement>glossBody</xmlelement></indexterm>
<indexterm>glossentry
Expand All @@ -23,23 +24,43 @@
<p conkeyref="reuse-attributes/only-universal"/>
</section>
<example id="example" otherprops="examples">
<title>Example</title>
<p>The following code sample shows how the
<xmlelement>glossBody</xmlelement> element contains the part of
speech and variant forms for the term:</p>
<codeblock>&lt;glossentry id="sport-drink">
&lt;glossterm>Sport drink&lt;/glossterm>
&lt;glossdef>A soft drink designed or marketed for consumption in
<title>Example</title>
<p>The following code sample shows how the <xmlelement>glossBody</xmlelement> element
<?oxy_delete author="dawnstevens" timestamp="20240507T074641-0600" content="contains the part of speech"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T074641-0600"?>provides
guidance about the usage of the term<?oxy_insert_end?> and variant forms for the term:</p>
<?oxy_delete author="dawnstevens" timestamp="20240507T074807-0600" content="&lt;codeblock&gt;&amp;lt;glossentry id=&quot;sport-drink&quot;&gt;
&amp;lt;glossterm&gt;Sport drink&amp;lt;/glossterm&gt;
&amp;lt;glossdef&gt;A soft drink designed or marketed for consumption in
conjunction with sporting activity or strenuous exercise, and which
typically contains electrolytes such as sodium, potassium, and
chloride, and a high percentage of sugar to restore energy.&lt;/glossdef>
<b>&lt;glossBody></b>
&lt;glossPartOfSpeech value="noun"/>
&lt;glossAlt>
&lt;glossSynonym>energy drink&lt;/glossSynonym>
&lt;/glossAlt>
<b>&lt;/glossBody></b>
&lt;/glossentry></codeblock>
</example>
chloride, and a high percentage of sugar to restore energy.&amp;lt;/glossdef&gt;
&lt;b&gt;&amp;lt;glossBody&gt;&lt;/b&gt;
&amp;lt;glossPartOfSpeech value=&quot;noun&quot;/&gt;
&amp;lt;glossAlt&gt;
&amp;lt;glossSynonym&gt;energy drink&amp;lt;/glossSynonym&gt;
&amp;lt;/glossAlt&gt;
&lt;b&gt;&amp;lt;/glossBody&gt;&lt;/b&gt;
&amp;lt;/glossentry&gt;&lt;/codeblock&gt;"?>
<?oxy_insert_start author="dawnstevens" timestamp="20240507T074811-0600"?>
<codeblock>&lt;glossentry id="pin">
&lt;glossterm>personal identification number&lt;/glossterm>
&lt;glossdef>A numerical code issued with a payment card that is required
to be entered to complete various finanancial transactions. The core
purpose of this code is to provide an additional layer of security
to the electronic transaction process.&lt;/glossdef>
<b>&lt;glossBody></b>
&lt;glossSurfaceForm>personal identification number (PIN)&lt;/glossSurfaceForm>
&lt;glossUsage>Use in the context of banking and finanacial transactions. For
context of Indian addresses, see &lt;xref href="postal_index_number.dita">.
&lt;glossAlt>
&lt;glossAcronym>PIN&lt;/glossAcronym>
&lt;glossUsage>Do not use the acronym followed by the word "number." It is
redundant as the 'N' in the acronym stands for the word "number."
&lt;/glossUsage>
&lt;/glossAlt>
<b>&lt;/glossBody></b></codeblock>
<?oxy_insert_end?>
</example>
</refbody>
</reference>
<?oxy_options track_changes="on"?>
50 changes: 27 additions & 23 deletions specification/langRef/technicalContent/glossSurfaceForm.dita
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,7 @@
<shortdesc>The <xmlelement>glossSurfaceForm</xmlelement> element specifies how the term specified
by the topic's <xmlelement>glossterm</xmlelement> element should appear in the text. The surface
form is suitable to introduce the term in new contexts or as the first occurrence in
text.<draft-comment author="dawnstevens">I learned a lot more than I really wanted to about
the surface form in linguistics to suggest this short description, as opposed to what was
there: "an unambiguous presentation of the term that might combine multiple forms." Surface
forms are " the way a linguistic unit (such as a word, phrase, or sentence) appears when it is
actually spoken or written, as opposed to its underlying or abstract form." Surface forms may
take into account phonology (to provide stress, intonation, and accent), test and plurals (the
surface form of "go" is "goes" in 3rd person singular), and derivational (to change roots of
words in various contexts), contextual (I'm might be a surface form of I am in informal
speech). Ultimately, in my experience the only thing this is really used for is first-use
occurrence of acronyms so they are spelled out. I wonder if we should use that use case only
in this definition, rather than a more comprehensive scope. </draft-comment></shortdesc>
text.<?oxy_delete author="dawnstevens" timestamp="20240507T080555-0600" content="&lt;draft-comment author=&quot;dawnstevens&quot;&gt;I learned a lot more than I really wanted to about the surface form in linguistics to suggest this short description, as opposed to what was there: &quot;an unambiguous presentation of the term that might combine multiple forms.&quot; Surface forms are &quot; the way a linguistic unit (such as a word, phrase, or sentence) appears when it is actually spoken or written, as opposed to its underlying or abstract form.&quot; Surface forms may take into account phonology (to provide stress, intonation, and accent), test and plurals (the surface form of &quot;go&quot; is &quot;goes&quot; in 3rd person singular), and derivational (to change roots of words in various contexts), contextual (I&apos;m might be a surface form of I am in informal speech). Ultimately, in my experience the only thing this is really used for is first-use occurrence of acronyms so they are spelled out. I wonder if we should use that use case only in this definition, rather than a more comprehensive scope. &lt;/draft-comment&gt;"?></shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -33,17 +23,28 @@
<p>The <xmlelement>glossSurfaceForm</xmlelement> element is most often used for terms that
also specify the <xmlelement>glossAcronym</xmlelement> element. In that context, the
<xmlelement>glossSurfaceForm</xmlelement> element contains the term in a manner that
introduces both the term and the acronym, so that later references to the term can be
replaced with the acronym alone. <note id="note_nkh_yqp_c1c">In some languages, the surface
form that expands the acronym in its first use handles the formatting differently than in
English. For example, in Polish, the acronym precedes the expansion. In addition, some
languages may not have a corresponding acronym for a term, so the
<xmlelement>glossSurfaceForm</xmlelement> and <xmlelement>glossAcronym</xmlelement>
would be left blank in translated content.</note></p>
<p>See the <xref href="abbreviated-form.dita"
><xmlelement>abbreviated-form</xmlelement></xref> element for a
full description of how the surface form is used together with
acronyms.</p>
introduces both the term and
<?oxy_delete author="dawnstevens" timestamp="20240507T080628-0600" content="the acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080628-0600"?>its
shortened form<?oxy_insert_end?>, so that later references to the term can be replaced with
the
<?oxy_delete author="dawnstevens" timestamp="20240507T080634-0600" content="acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080636-0600"?>shortened
form<?oxy_insert_end?> alone. <note id="note_nkh_yqp_c1c">In some languages, the surface
form that expands the
<?oxy_delete author="dawnstevens" timestamp="20240507T080645-0600" content="acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080645-0600"?>shortened
form<?oxy_insert_end?> in its first use handles the formatting differently than in
English. For example, in Polish,
<?oxy_delete author="dawnstevens" timestamp="20240507T080703-0600" content="the"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080703-0600"?>an<?oxy_insert_end?>
acronym precedes
<?oxy_delete author="dawnstevens" timestamp="20240507T080706-0600" content="the"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080706-0600"?>its<?oxy_insert_end?>
expansion. In addition, some languages may not have a corresponding
<?oxy_delete author="dawnstevens" timestamp="20240507T080709-0600" content="acronym"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080709-0600"?>short
form<?oxy_insert_end?> for a term, so the <xmlelement>glossSurfaceForm</xmlelement> and
<xmlelement>glossAcronym</xmlelement> would be left blank in translated
content.</note></p>
<p>See the <xref href="abbreviated-form.dita"><xmlelement>abbreviated-form</xmlelement></xref>
element for a full description of how the surface form is used together with
<?oxy_delete author="dawnstevens" timestamp="20240507T080718-0600" content="acronyms"?><?oxy_insert_start author="dawnstevens" timestamp="20240507T080718-0600"?>short
forms, such as acronyms<?oxy_insert_end?>.</p>
</section>
<section id="specialization-hierarchy">
<title>Specialization hierarchy</title>
Expand All @@ -63,7 +64,9 @@
the glossary entry topic is referenced from an <xmlelement>abbreviated-form</xmlelement>
element.</p>
<codeblock>&lt;glossentry id="abs">
&lt;glossterm>Anti-lock Braking System&lt;/glossterm>
&lt;glossterm>Anti-lock Braking System&lt;/glossterm><?oxy_insert_start author="dawnstevens" timestamp="20240507T080756-0600"?>
&lt;glossdef>A safety feature on vehicles used to prevent a wheel lock up and
to help operators maintain control of the vehicle.&lt;/glossdef><?oxy_insert_end?>
&lt;glossBody>
<b>&lt;glossSurfaceForm>Anti-lock Braking System (ABS)&lt;/glossSurfaceForm></b>
&lt;glossAlt>
Expand All @@ -74,3 +77,4 @@
</example>
</refbody>
</reference>
<?oxy_options track_changes="on"?>
Loading