diff --git a/specification/archSpec/technicalContent/dita-glossary-topic.dita b/specification/archSpec/technicalContent/dita-glossary-topic.dita index 7f2cac09..2240d95e 100644 --- a/specification/archSpec/technicalContent/dita-glossary-topic.dita +++ b/specification/archSpec/technicalContent/dita-glossary-topic.dita @@ -15,9 +15,8 @@ @@ -39,12 +38,27 @@

The following code sample contains a simple glossentry topic:

<glossentry id="ddl"> <glossterm>data definition language</glossterm> - <glossdef>A language used for defining database schemas</glossdef> + <glossdef>A language used for defining database schemas</glossdef> + <glossBody> + <glossSurfaceForm>data definition language (DDL)</glossSurfaceForm> + <glossAlt> + <glossAcronym>DDL</glossAcronym> + </glossAlt> + <glossBody> + <related-links> + <link href="data_control_language.dita"/> + <link href="data_manipulation_language.dita"/> + <link href="data_query_language.dita"/> + <link href="sql.dita"/> </glossentry> -

This should have a glossbody that specifies an acronym and a - surface term. Also related links.

+

This should have a glossbody that specifies an acronym and a surface term. Also related + links.

+ + Done + + \ No newline at end of file diff --git a/specification/langRef/technicalContent/glossAcronym.dita b/specification/langRef/technicalContent/glossAcronym.dita index 93e5ec77..ce8d68e1 100644 --- a/specification/langRef/technicalContent/glossAcronym.dita +++ b/specification/langRef/technicalContent/glossAcronym.dita @@ -3,10 +3,13 @@ "reference.dtd"> <xmlelement>glossAcronym</xmlelement> - The glossAcronym element defines an acronym for the term - specified in the topic's glossterm 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. + The glossAcronym element defines + a + shortened form for the term specified in the topic's + glossterm + element, such as an + acronym, initialism, or abbreviation. + @@ -21,17 +24,31 @@
Usage information

This element can be used with the abbreviated-form element to - display an expanded version of an acronym the first time that acronym appears in a set of - text. See abbreviated-form for information on how the two elements - interact.

- 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 glossSurfaceForm element, which - will often accompany the glossAcronym. The either + an expanded version of + the + term the first time that + term + appears in a set of + text or the + shortened version defined in this element on subsequent occurrences of the + term. See abbreviated-form for information on how the two + elements interact.

+ A + shortened form of a term in one language might not have an equivalent in + another language. When + shortened + terms are first displayed, some languages will display the expanded form + first followed by the + shortened + form in parenthesis, while other languages do the reverse. For some + terms, + a translation might need to render both the original and the translated version of the + shortened + form. For all of these reasons, DITA allows an author or translator to + control what is presented to a reader by using the glossSurfaceForm + element, which will often accompany the glossAcronym. The abbreviated-form topic contains information on how the glossSurfaceForm and glossAcronym elements affect references to the term. @@ -63,3 +80,4 @@ + \ No newline at end of file diff --git a/specification/langRef/technicalContent/glossAlt.dita b/specification/langRef/technicalContent/glossAlt.dita index ec85706b..26b21f32 100644 --- a/specification/langRef/technicalContent/glossAlt.dita +++ b/specification/langRef/technicalContent/glossAlt.dita @@ -66,7 +66,7 @@ <glossUsage>Do not use; the American continents include other countries.</glossUsage> </glossAlt> <glossAlt> - <glossAbbreviation>the States</glossAbbreviation> + <glossAcronym>the States</glossAcronym> <glossUsage>Informal. Typically used by English speakers outside of the country.</glossUsage> </glossAlt> </glossBody> @@ -75,3 +75,4 @@ + \ No newline at end of file diff --git a/specification/langRef/technicalContent/glossBody.dita b/specification/langRef/technicalContent/glossBody.dita index 27baaf81..0943310b 100644 --- a/specification/langRef/technicalContent/glossBody.dita +++ b/specification/langRef/technicalContent/glossBody.dita @@ -3,8 +3,9 @@ <xmlelement>glossBody</xmlelement> The glossBody element contains information about the term - specified in the topic's glossterm element, such as the part of speech - and variants for the term. + specified in the topic's glossterm element, such as + usage + and variants for the term. glossBody glossentry @@ -23,23 +24,43 @@

- Example -

The following code sample shows how the - glossBody element contains the part of - speech and variant forms for the term:

- <glossentry id="sport-drink"> - <glossterm>Sport drink</glossterm> - <glossdef>A soft drink designed or marketed for consumption in + Example +

The following code sample shows how the glossBody element + provides + guidance about the usage of the term and variant forms for the term:

+ - <glossBody> - <glossPartOfSpeech value="noun"/> - <glossAlt> - <glossSynonym>energy drink</glossSynonym> - </glossAlt> - </glossBody> -</glossentry>
-
+ 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>"?> + + <glossentry id="pin"> + <glossterm>personal identification number</glossterm> + <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.</glossdef> + <glossBody> + <glossSurfaceForm>personal identification number (PIN)</glossSurfaceForm> + <glossUsage>Use in the context of banking and finanacial transactions. For + context of Indian addresses, see <xref href="postal_index_number.dita">. + <glossAlt> + <glossAcronym>PIN</glossAcronym> + <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." + </glossUsage> + </glossAlt> + </glossBody> + +
+ \ No newline at end of file diff --git a/specification/langRef/technicalContent/glossSurfaceForm.dita b/specification/langRef/technicalContent/glossSurfaceForm.dita index 86391894..a13906d4 100644 --- a/specification/langRef/technicalContent/glossSurfaceForm.dita +++ b/specification/langRef/technicalContent/glossSurfaceForm.dita @@ -6,17 +6,7 @@ The glossSurfaceForm element specifies how the term specified by the topic's glossterm 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.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. + text. @@ -33,17 +23,28 @@

The glossSurfaceForm element is most often used for terms that also specify the glossAcronym element. In that context, the glossSurfaceForm 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. 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 - glossSurfaceForm and glossAcronym - would be left blank in translated content.

-

See the abbreviated-form element for a - full description of how the surface form is used together with - acronyms.

+ introduces both the term and + its + shortened form, so that later references to the term can be replaced with + the + shortened + form alone. In some languages, the surface + form that expands the + shortened + form in its first use handles the formatting differently than in + English. For example, in Polish, + an + acronym precedes + its + expansion. In addition, some languages may not have a corresponding + short + form for a term, so the glossSurfaceForm and + glossAcronym would be left blank in translated + content.

+

See the abbreviated-form + element for a full description of how the surface form is used together with + short + forms, such as acronyms.

Specialization hierarchy @@ -63,7 +64,9 @@ the glossary entry topic is referenced from an abbreviated-form element.

<glossentry id="abs"> - <glossterm>Anti-lock Braking System</glossterm> + <glossterm>Anti-lock Braking System</glossterm> + <glossdef>A safety feature on vehicles used to prevent a wheel lock up and + to help operators maintain control of the vehicle.</glossdef> <glossBody> <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm> <glossAlt> @@ -74,3 +77,4 @@ + \ No newline at end of file diff --git a/specification/langRef/technicalContent/glossUsage.dita b/specification/langRef/technicalContent/glossUsage.dita index 6bfa5391..5c561b54 100644 --- a/specification/langRef/technicalContent/glossUsage.dita +++ b/specification/langRef/technicalContent/glossUsage.dita @@ -21,10 +21,7 @@ Specialization hierarchy

The glossUsage element is specialized from note. It is defined in the glossary entry module.

- 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 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? +
@@ -53,3 +50,4 @@ + \ No newline at end of file diff --git a/specification/langRef/technicalContent/glossentry.dita b/specification/langRef/technicalContent/glossentry.dita index 62ff513d..f194b511 100644 --- a/specification/langRef/technicalContent/glossentry.dita +++ b/specification/langRef/technicalContent/glossentry.dita @@ -39,10 +39,16 @@

One possible implementation of a glossary in online processing is to associate a hotspot for mentions of terms in term elements and display the definition on hover or click. A possible implementation in PDF processing is to define a first-use - occurrence form of the term with its acronym and use it in conjunction with - abbreviated-form to render a spell-out version of the term with - its acronym on first use within an output, while rendering the acronym in all subsequent - locations.

+ occurrence form of the term with its + shortened + form and use it in conjunction with + abbreviated-form to render a + spelled-out + version of the term with its + short + form on first use within an output, while rendering the + short + form in all subsequent locations.

Specialization hierarchy @@ -61,27 +67,28 @@ <glossterm>USB flash drive</glossterm> <glossdef>A small portable drive.</glossdef> <glossBody> - <glossPartOfSpeech value="noun"/> + <glossUsage>Do not use this term in upper case (for example, in "USB Flash Drive") because that suggests a trademark.</glossUsage> <glossAlt> <glossAcronym>UFD</glossAcronym> - <glossStatus value="prohibited"/> + <glossUsage>Do not use. This acronym is commonly used + to stand for "unique factorization domain."</glossStatus> </glossAlt> <glossAlt id="memoryStick"> <glossSynonym>memory stick</glossSynonym> - <glossUsage>This is a colloquial term.</glossUsage> + <glossUsage>Do not use. This synonym is a colloquial term.</glossUsage> </glossAlt> <glossAlt> - <glossAbbreviation>stick</glossAbbreviation> - <glossStatus value="prohibited"/> - <glossUsage>This is too colloquial.</glossUsage> - <glossAlternateFor href="#usbfd/memoryStick"/> + <glossAcronymn>stick</glossAcronym> + <glossUsage>Do not use. This short form is too vague.</glossUsage> + </glossAlt> <glossAlt> - <glossAbbreviation>flash</glossAbbreviation> - <glossStatus value="prohibited"/> - <glossUsage>This short form is ambiguous.</glossUsage> + <glossAcronym>flash</glossAcronym> + + <glossUsage>Do not use. This short form is ambiguous.</glossUsage> </glossAlt> </glossBody> </glossentry> @@ -89,3 +96,4 @@ + \ No newline at end of file