An adopter interested only in term resolution for acronyms can declare an acronym with a glossentry topic similar to the following example:
The adopter can declare a key for the acronym using the standard DITA 1.2 keyref mechanism:
The adopter can then refer to the acronym using the standard DITA 1.2 keyref mechanism:
Processes should resolve the abs
reference
to the <glossSurfaceForm> text in introductory contexts and to
the <glossAcronym> text in other contexts.
Note that the keyref value does not need to match the acronym. In fact, using a more qualified value for the keyref will reduce conflicts in situations where the same acronym may resolve in many ways. For example, an information set could use “cars.abs” as the key for Anti-lock Braking System, and “ship.abs” to refer to the American Bureau of Shipping.
An adopter interested only in traditional glossary publishing can explain one sense of a term with a glossentry topic similar to the following example:
The adopter can then pull together a subset of the defined terms for a deliverable as in the following example:
To produce a traditional glossary, a process should sort the terms included in a deliverable and list the explained senses under each term.
Adopters need not declare the same acronym in different ways for different purposes but instead can establish a declaration of acronym terms for multiple purposes. An adopter who needs both to refer to an acronym and list the acronym in a published glossary would provide an explanation of the acronym as in the following example:
The glossary can include the expanded acronym (as shown in the following example) as well as glossary term that are not acronyms. In addition, the team can create acronyms that are referenced but not included in the glossary:
The adopter can still refer to the acronym with the <abbreviated-form> element as in the following example:
Processing for term resolution to either the <glossSurfaceForm> or <glossAcronym> text and processing for glossary publishing work as before.
While a number of text analysis tools exist, the challenge for adopters is populating the terminology database that enables use of such tools. Published glossaries provide a practical source for terminology to populate such terminology databases.
An adopter whose requirements include not only acronym resolution and glossary publishing requirements but populating a terminology database can create glossentry topics similar to the following:
As illustrated by these example, adopters can scale up for more sophisticated applications as their requirements change by taking advantage of optional elements to provide additional detail about the term.
To use the glossentry topic for acronym resolution, the writer takes advantage of the following elements
The <glossentry> topic provides additional subelements
that are optional but available to scale up for single sourcing for
additional purposes such as glossary publishing of the acronym (see
Two new domains complement the glossary entry topic to make it easy to refer to acronyms (as shown in the example of acronym resolution):
When the writer provides a keyref to a glossentry topic that contains a <glossSurfaceForm> element, a process should emit the surface form in introductory contexts where the term might be unfamiliar to the reader or in other contexts where a precise term is appropriate.
For instance, a process composing a book deliverable should emit the surface form on the first reference to the glossentry topic within the book or for every reference within a copyright or a warranty-related warning. A process generating an online page should emit the surface form as a hover tooltip on every instance of the term. A glossary publishing process should emit the surface form for the term.
When the writer uses the <abbreviated-form> element to refer to a glossentry topic, processing resolves the term reference to the text of the <glossSurfaceForm> element in introductory contexts and to text of the <glossAcronym> element in other contexts.
For
instance, if the topic with the keyref to the abs
key provided
the first appearance of the ABS term within a book, the sentence could
be rendered as follows:
The Anti-lock Brake System (ABS)
will prevent the car from skidding in adverse weather conditions.
If the ABS term had appeared previously within the book, the same sentence could instead be rendered as follows:
The ABS will prevent
the car from skidding in adverse weather conditions.
The following cases for abbreviated forms must be contemplated when working with documents that require translation:
The source and target languages may have different forms for a term. One language may lack an abbreviation or acronym that's recognized in the other, or the preferred term may be an abbreviation or acronym in one language but the expanded form in another.
Translation workbenches don't allow the translator to change markup during translation. That's necessary for the translation workbench to apply to any markup language without building in an awareness of specific markup vocabularies. For that reason, the text of an acronym and surface form may be provided in the source language but omitted or translated to the same text in a target language while preserving the markup structure.
The following example illustrates this approach for the English source topic:
Term resolution processing uses the supplied text from the <glossAcronym> and <glossSurfaceForm> elements in the same way as the source English text.
Term resolution processing should always ignore empty elements. If the <glossAcronym> and <glossSurfaceForm> elements are empty, an <abbreviated-form> reference should resolve to the <glossterm> text. Thus, if allowed by the translation workbench, the translator could take advantage of standard processing by omitting the text translation for both the <glossAcronym> and <glossSurfaceForm> elements. The result of processing an empty element should be the same as if the translator had copied the <glossterm> text into the empty element.
However, translation processing systems may not permit the translator to leave an element empty and will generate an error message that the translation is incomplete. In that case, the translator must duplicate the <glossterm> in the <glossAcronym> and <glossSurfaceForm> elements.
In some languages, like Spanish, abbreviated-form expansion should be written in lower case. This can lead to a grammatical error if the first appearance of an abbreviated form occurs at the beginning of a sentence. The same problem may arise with the indefinite article in English 'a' or 'an' depending on whether the text to be inserted begins with a vowel. It is up to the composition/display software to handle this. For example, the acronym for AIDS should be translated as:
Normally the
Abbreviated forms can cause problems for inflected languages because abbreviated form expansion needs to be presented in the nominative case, without any inflection. This can be achieved with a surface form that provides the full form in parentheses immediately following the acronym. For example, the Polish acronym for the European Union is:
Using the above construct enables automated
handling of the abbreviated form in Polish without causing any problems
with grammatical inflection. For example, when stating that something
occurred within the EU, the inflected form in Polish caused by the
use of the locative case would have to be used. For the actual abbreviated
form itself this is not a problem, since abbreviated forms are not
inflected. Consider, for example, the phrase In the European Union
(EU) there are many institutions…
:
W Unii Europejskiej
(UE) jest wiele instytucji…
However, by allowing the translator
to control how the text is displayed via the
W UE (Unia Europejska)
jest wiele instytucji…
DITA 1.1 introduce a simple glossary specialization to meet basic needs for publication as part of bookmap.
The DITA 1.1 glossary specialization, however, is too simple to support many common glossary applications. For instance, many content publishers need to distinguish an abbreviation from the full term. In addition, a more complete representation of terminology can support processing such as the following:
Key terminology standards include
Key semantic standards include
To enable these applications, DITA 1.2 allows additional detail about the term and additional methods for referring to terms that can deliver either abbreviated or surface forms of the term.
The following requirements apply to glossary terms generally:
In addition, abbreviated forms and their translations require special handling:
For example, the surface form for an abbreviated form in English might consist of the abbreviated form followed by its expanded form in parentheses. By contrast, the translated version might consist of the expanded form followed by the abbreviated form in parentheses. The translated version might also include the English and the translation.
For example, in a Polish book on Java Web programming, the first reference to JSP may appear as follows:
JSP (ang. Java Server Pages)
Another example from a publication concerning OASIS:
OASIS (ang. Organization for the Advancement of Structured Information Standards—organizacja dla propagowania strukturalnych standardów infomracyjnych)
In the first example, the translator assumes the reader will not require a translation of the English abbreviated form. In the second example, the translator assumes the reader may not understand the English expanded form and therefore adds the translation.
Moderate: adding elements to one specialized topic, providing a map domain for defining keys, and providing an element domain for referring to keys.
The full set of elements provided by the expanded glossentry topic includes the following elements:
conceptto denote the meaning of a term. For the DITA community, however,
concepthas a strong association with the core DITA concept topic type. To avoid confusion, this proposal denotes the meaning of a term with
subject(which has appropriate connotations by way of
subject classificationand the Dublin Core subject property).
Linuxmight explain that the term doesn't apply to UNIX products and give some examples of Linux products that are included as well as UNIX products that are excluded.
The following example shows the minimum declaration of a term:
The following example shows a detailed glossary entry specifying the usage for the preferred and alternate terms:
Using the standard keyref mechanism, the writer can assign a key to the declaration topic and refer to the key to insert the preferred term. The benefit in using a reference is that the preferred term can be maintained in one place:
Two new domains support easy definition and use of keys for glossary entry topics:
novalue and the
nonevalue. The <glossref> element is always empty.
Writers can set the target
value on the <glossref> element to enable linking
from the use to the glossary term. The <glossref> element is only
a convenience. Writers can always use the standard capabilities of
the keyref mechanism. For instance, writers can use the <topicref>
element with a
When the writer uses the <abbreviated-form> element to refer to a glossentry topic, the process performs the following checks in the attempt to find an abbreviated or surface form with text for the reference, skipping all subsequent checks once the text has been found:
Writers
can also use the <term> element with a
For authoring convenience, a <glossgroup> topic can contain multiple <glossentry> topics:
Relationships between the subjects of terms (such as the hypernym or kind-of relationship and the holonym or part-of relationships specified by WordNet) can be specified for glossary topics by a subject scheme map. (Please see the Proposal 12031 for Controlled Values.)
The Language Reference for the glossentry topic should be revised to reflect the contents of this proposal including translation considerations and their impact on the use of abbreviations.
Implementation of the DTD and Schema changes for the glossentry topic, of the map domain for the <glossref> element, of the topic domain for the <abbreviated-form> element, and of the glossgroup topic.
Implementation of special processing to emit the surface form when appropriate.
In particular, abbreviated forms can be handled in a uniform and consistent manner by putting resolution of the abbreviated form under the control of the composition software so that glossary, tooltip, and first forms can be provided as required to meet the end-user requirements.