Add a new <acronym> element based on an expansion of the extant
DITA <keyword> element to assist in the resolution and handling of acronyms
in source and target text within DITA documents.
Acronyms are ubiquitous in technical documentation. Although there are similarities between acronyms and glossary terms, from the localization and presentation point of view acronyms are a special case. Acronyms need to be expanded in the first encounter within a printed document. In electronic published documents acronym expansions can also be made available in the form of a hyperlink or 'tool tip' mechanism.
The proposal is to create an <acronym> element which would be
a specialized form of the <keyword> element.
The acronym
resolution will be via the "conref" attribute to the acronym text short and
expanded forms, e.g.:
<acronym conref="aconyms.dita#acronyms/abs"/>
The entry in the aconyms.dita file will be:
<acronym id="abs"> <expanded>Anti-lock Braking System (ABS)</expanded> <short>ABS</short> </acronym>
The <expanded> form will be a specialization of the <keyword> element,
while the <short> element will be a spacialization 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.
The first time an acronym is encountered, the processing tool should use the text in
<expanded> element. Subsequent instances should be replaced
by the contents of the <short> element.
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 translator can provide
the expanded form in the <short> element, e.g.:
<acronym id="wmd">
<expanded>Weapons of Mass Destruction</expanded>
<short>WMD</short>
</acronym>
in Spanish becomes:
<acronym id="wmd" xml:lang="es"> <expanded>armas de destrucción masiva</expanded> <short>armas de destrucción masiva</short> </acronym>
Acronyms can cause problems for inflected languages because acronym expansions need
to be presented in the nominative case, without any inflection. This can be achieved
by placing the expansion of the acronym in parentheses immediately following the
acronym in the <expanded> element. For example, the Polish
acronym for the European Union may be:
<acronym id="abs" xml:lang="pl"> <expanded>UE (Unia Europejska)</expanded> <short>UE</short> </acronym>
Using the above construct enables automated handling of the acronym in Polish without causing any problems with grammatical inflection. For example if we were stating that something ocurred within the EU, the inflected form in Polish caused by the use of the locative case would have to be. For the actual acronym itself this is not a problem as acronyms 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 <expanded>,
and therefor the first occurrance for the acronym allows us to use the following acceptable contruct:
W UE (Unia Europejska) jest wiele instytucji...
In some languages, like Spanish, acronym expansion should be written in lower case. This can lead to a grammar error if the first appearence of an acronym happens at the start of a sentence. For example, the acronym for AIDS should be translated as:
<acronym id="aids" xml:lang="es"> <expanded>síndrome de inmuno-deficiencia adquirida (SIDA)</expanded> <short>SIDA</short> </acronym>
The expanded version of this acronym cannot be used at the start of a sentence.
Authors will enter the <acronym> element for every
occurrence of a given acronym.
At compose time, when putting together the publication, the publishing tool will print the full 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.
A new <acronym> element needs to be created which a
specialization of the <keyword> element.
?
Acronyms will be handled in a uniform and consistent manner. The handling of the acronym will be under the control of the composition software. The first occurrence of the acronym can show the fully expanded 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 acronym can be totally under the control of the composition software so that glossary, tooltip and expanded forms can be provided as required to meet the end user requirements.
The addition of the <acronym> element as a specialization of
the <data> element does not require much work.