DITA Proposed Feature # 12038 - <abbreviated-form> Element

Add a new <abbreviated-form> element based on an expansion of the extant DITA <keyword> element to assist in the resolution and handling of abbreviated form text such as acronyms, general abbreviations and short forms in source and target text within DITA documents.

Note from Robert Anderson: The acronym element should be based off of the <keyword> element. The <data> element itself is treated as metadata, and by default all processors are expected to ignore this element for display. Keyword, on the other hand, is an inline phrase. The acronym element will contain 2 or 3 children, depending on final implementation details. One child should also be a keyword element; the content of this element will be displayed by bare-bones DITA implementations that do not add specific support for acronym. The other one or two elements should be specialized from <data>, which means they will be hidden in published output until a processor adds support for <acronym>. NOTE: this means that the acronym proposal depends on the existing DITA 1.2 proposal for nesting keywords. It also depends on adding support for <data> within <keyword>, which can either be part of this proposal or part of the nested keywords proposal.

Longer description

Abbreviated forms such as acronyms are ubiquitous in technical documentation. Although there are similarities between abbreviated forms and glossary terms, from the localization and presentation point of view abbreviated forms are a special case. Abbreviated forms need to be expanded in the first encounter within a printed document. In electronic published documents abbreviated form expansions can also be made available in the form of a hyperlink or 'tool tip' mechanism. In addition the abbreviated form expanded text should be available for automatic inclusion in glossary entries for the publication.

This proposal relates to all types of abbreviations, such as acronyms, initialisms, apocope, clipping, elision, syncope, syllabic abbreviation, and portmanteau.

Abbreviated Forms and translation

Abbreviated forms and their translations can require special handling:

Some abbreviated forms are never translated, especially those that are intended for a knowledgeable, technical audience, and those that refer to standardized international concepts, such as “xml".
Some abbreviated forms represent a brand name for which the original expanded form is no longer used or is secondary to the abbreviated forms.
abbreviated forms such as xml, jpg, html, and so on are typically used in their original form, that is, they may be quoted in lower case, and they are not translated.
Abbreviated forms that have equivalent expressions in other languages are typically translated. United Nations (UN) and Weapons of Mass Destruction (WMD) have equivalents in other languages besides English. For instance, the French translation of “UN” is “ONU”.
Some abbreviated forms are translated for clarity and also referred to in their original untranslated form. For instance, OASIS may be translated so that readers understand its significance in their native language but the original acronym would be retained in the translation to facilitate electronic search.
The first occurrence of an abbreviated form in the target language may require a different formulation than the first occurrence of an abbreviated form in the source language, depending on the target audience and the grammatical features of the target language. For instance, if the first occurrence of an abbreviated form in English is followed by its full form in parentheses, the translated version may require the expanded form followed by the abbreviated form in parentheses. It might also be necessary to include the English and a 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)

or in a publication concerning OASIS:

OASIS (ang. Organization for the Advancement of Structured Information Systems - organizacja dla propagowania strukturalnych systemów infomracyjnych)

In the first example the translator assumes that the reader will not require a translation of the English abbreviated form. In the second example the translator assumes that the reader may not understand the English expanded form and adds the translation.

The Proposal

The proposal is to create an <abbreviated-form> element which would be a specialized form of the <keyword> element. The abbreviated form resolution will be via the "conref" attribute to the abbreviated form text short, expanded and first forms. The abbreviated form element is designed to be extended via specialization to reflect the actual form of abbreviation e.g.:

<acronym class="abbreviate-form" conref="acronyms.dita#acronyms/abs"/>

The entry in the acronyms.dita file will be as follows. Note that the ID only needs to be unique to the file, and does not need to match the acronym, so translations of the following example will continue to use id="abs":

<abbreviate-form id="abs">
   <expanded>Anti-lock Braking System</expanded>
   <short>ABS</short>
   <surface-form>Anti-lock Braking System (ABS)</surface-form>
</abbreviate-form>

The <expanded> form will be a specialization of the <keyword> element, while the <short> element will be a specialization of the <data> element. This means that the expanded term is a normal phrase, while the short form is metadata that is hidden when processes do not know what to do with it. Translation processes should treat this data specialization as a subflow element for the purposes of translation. The <surface-form> element represents how the acronym should be displayed on the first occurrence of the acronym, or for hyper text display the tool-tip rendition.

<abbreviate-form>  ==> specialize from keyword
  <expanded/>  ==> specialize from keyword
  <short/>  ==> specialize from data
  <surface-form/>  ==> specialize from keyword
</abbreviate-form>

The first time an abbreviated form is encountered, the processing tool should use the text in <surface-form> element. Subsequent instances should be replaced by the contents of the <short> element. The <expanded> form is designed to be used in glossaries. These three elements therefore allow the full needs of acronym handling to be met:

First occurrence rendition
Subsequent short form rendition
Glossary entry

July 10 and July 17: We discussed adding a third element to the acronym proposal, which has not yet been incorporated into this proposal. The acronym element would then include one element to hold the expanded version, one element to hold the short version, and one element to hold text to be displayed. The presentation element can be used to place the expanded term first or second as needed by the language and context. This impacts the capitalization and grammatical inflection problems, as noted below.

Translation Issues

The following cases must be contemplated when working with documents that require internationalization:

If there is no short form for the target language, then the <short> element will be empty to signify that no short form exists for this language. The <surface-form> must always contain the text that will be displayed for the first occurrence.

<abbreviate-form id="wmd">
   <expanded>Weapons of Mass Destruction</expanded>
   <short>WMD</short>
   <surface-form>Weapons of Mass Destruction (WMD)</surface-form>
</abbreviate-form>

in Spanish becomes:

<abbreviate-form id="wmd" xml:lang="es">
   <expanded>armas de destrucción masiva</expanded>
   <short/>
   <surface-form>armas de destrucción masiva</surface-form>
</abbreviate-form>

In some languages, like Spanish, abbreviated-form expansion should be written in lower case. This can lead to a grammar error if the first appearance of an abbreviated form happens at the start of a sentence. The same problem can arise with the indefinite article in English 'a' 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:

<abbreviate-form id="aids" xml:lang="es">
   <expanded>síndrome de inmuno-deficiencia adquirida</expanded>
   <short>SIDA</short>
   <surface-form>síndrome de inmuno-deficiencia adquirida (SIDA)</surface-form>
</abbreviate-form>

Normally the <surface-form> version of the abbreviated in the above example could not be used at the start of a sentence as it begins with a lower case letter. It is up to the composition software for the given langauge to cope with these requirements.

Comment 16 July: How do we resolve this problem? Would there be a definite article?

Abbreviated forms can cause problems primarily for inflected languages because abbreviated form expansion needs to be presented in the nominative case, without any inflection. This can be achieved by placing the expansion of the abbreviated form in parentheses immediately following the acronym in the <expanded> element. For example, the Polish acronym for the European Union may be:

<abbreviate-form id="eu" xml:lang="pl">
   <expanded>Unia Europejska</expanded>
   <short>UE</short>
   <surface-form>UE (Unia Europejska)</surface-form>
</abbreviate-form>

Using the above construct enables automated handling of the abbreviated form in Polish without causing any problems with grammatical inflection. For example if we were stating that something occurred within the EU, the inflected form in Polish caused by the use of the locative case would have to be. For the actual abbreviated form itself this is not a problem as abbreviated forms are not inflected. For example the phrase 'In the European Union (EU) there are many institutions...':

 W Unii Europejskiej (UE) jest wiele instytucji...

Whereas allowing the translator to control how the text is displayed in the <surface-form>, and therefore the first occurrence for the abbreviated form allows us to use the following acceptable construct:

W UE (Unia Europejska) jest wiele instytucji...

Comment 16 July: Can we add an additional element to represent the "surface form" of the expansion. This could be an element such as <acro_presentation>. In this way, the translator could best represent the way in which the acronym expansion is presented in the text to avoid inflection and capitalization problems. This third element was originally proposed on July 10 as the solution for the ordering problem of whether to place the short or expanded form first.

Comment 14 August - A.Zydron: I have introduced the <surface-form> to handle this.

Use Case

Authors will enter the <abbreviated-form> element for every occurrence of a given acronym.

At compose time, when putting together the publication, the publishing tool will print the <surface-form> the first time around. The ABS acronym used in previous examples would be rendered as:

The Anti-lock Brake System (ABS) system will prevent the car from
skidding in adverse weather conditions.

Subsequent instances will then be rendered as:

The ABS system will provide the driver with feedback via the brake pedal.

Technical Requirements

A new <abbreviated-form> element needs to be created which a specialization of the <keyword> element. In addition the following specializations of the element need to be created, which provide a more detailed reflection of the actual abbreviated form in use:

acronym, e.g. <acronym class="abbreviated-form" conref="acronyms.dita#acronyms/tla"/>
abbreviation, e.g. <abbreviation class="abbreviated-form" conref="acronyms.dita#acronyms/abbrev"/>
short-form, e.g. <short-form class="abbreviated-form" conref="acronyms.dita#acronyms/short"/>

Costs

Benefits

Abbreviated forms will be handled in a uniform and consistent manner. The handling of the abbreviated form will be under the control of the composition software. The first occurrence of the abbreviated form can show the <surface-form> form. The text for both source and target languages will be consistent as it will be resolved via the "conref" attribute from a single source.

The resolution of the abbreviated form can be totally 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.

Time required

We do not believe that the addition of the <abbreviated-form> element as a specialization of the <keyword>, and the subsequent specialization of <acronym>, <abbreviation> and <short-form> elements requires much work.