Add a new 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
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 points 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 their translations require special handling:
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)"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.
The proposal is to create an 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's text for short, expanded, and first forms. The abbreviated form element is designed to be extended via specialization to reflect the actual form of abbreviation, for example:
<abbreviated-form conref="acronyms.dita#acronyms/abs"/>
The entry in the acronyms.dita file would be as follows:
<abbreviated-form id="abs"> <expanded>Anti-lock Braking System</expanded> <short>ABS</short> <surface-form>Anti-lock Braking System (ABS)</surface-form> </abbreviated-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 hypertext display with the tool-tip rendition.
| This new element… | Is specialized from this base element… |
|---|---|
| <abbreviated-form> | <keyword> |
| <expanded> | <keyword> |
| <short> | <data> |
| <surface-form> | <keyword> |
The first time an abbreviated form is encountered, the processing tool should use the text in the <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:
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. Consider the following example in English:
<abbreviated-form id="wmd"> <expanded>Weapons of Mass Destruction</expanded> <short>WMD</short> <surface-form>Weapons of Mass Destruction (WMD)</surface-form> </abbreviated-form>
In Spanish, this becomes:
<abbreviated-form id="wmd" xml:lang="es"> <expanded>armas de destrucción masiva</expanded> <short/> <surface-form>armas de destrucción masiva</surface-form> </abbreviated-form>
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:
<abbreviated-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> </abbreviated-form>
Normally the <surface-form> version of the abbreviated form in the above example could not be used at the start of a sentence, because it begins with a lower case letter. It is up to the composition software for the given language to cope with these requirements.
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:
<abbreviated-form id="eu" xml:lang="pl"> <expanded>Unia Europejska</expanded> <short>UE</short> <surface-form>UE (Unia Europejska)</surface-form> </abbreviated-form>
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 <surface-form> element, the first occurrence for the abbreviated form allows the translator to use the following acceptable construct:
W UE (Unia Europejska) jest wiele instytucji…
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> element the first time. 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 <abbreviated-form> element needs to be created, which is a specialization of the <keyword> element. The content model of <abbreviated-form> is:
abbreviated-form = ( expanded, short, surface-form )
Elements expanded and surface-form are specialized from <keyword>.
Element short is specialized from <data>.
The Architectural Specification should include a new topic on abbreviated forms. The title of this section should be "Acronyms and other Abbreviated Forms". The shortdesc element should contain the following content: "Resolution and handling of abbreviated-form text such as acronyms, general abbreviations, and short forms in source and target text within DITA documents"
The first paragraph of the acronym topic should include the following overview: "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 points 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 topic relates to all types of abbreviations, such as acronyms, initialisms, apocope, clipping, elision, syncope, syllabic abbreviation, and portmanteau."
Following paragraphs should be taken from Statement of Requirement, as-is.
This should be followed by a new section titled “Usage Guidelines” or similar, with the following content:
The basis of acronym handling is the <abbreviated-form> element, which is a specialized form of the <keyword> element. The abbreviated form resolution will be via the conref attribute to the abbreviated form's text for short, expanded, and first forms. The abbreviated-form element is designed to be extended via specialization to reflect the actual form of abbreviation, for example:
<abbreviated-form conref="acronyms.dita#acronyms/abs"/>
The entry in the acronyms.dita file would be as follows:
<abbreviated-form id="abs"> <expanded>Anti-lock Braking System</expanded> <short>ABS</short> <surface-form>Anti-lock Braking System (ABS)</surface-form> </abbreviated-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 hypertext display with the tool-tip rendition.
The first time an abbreviated form is encountered, the processing tool should use the text in the <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:
The above section should be followed by a section titled “Translation Issues,” to be taken as-is from Translation Issues.
The above section should be followed by a section titled “Rendition,”,to be taken as-is from Rendition.
The Language Reference should include a new topic for each new element in this proposal:
For each of these elements, the description should state something like "This element is part of the acronym feature. For usage details, please read the Architectural Specification." The rest of the element topic would be similar to other element descriptions, with each section (parents, children, attributes, etc.) filled in appropriately.
We do not believe that the addition of the <abbreviated-form> elements as a specialization of <keyword>, and its child elements <expanded>, <short>, and <surface-form> involves significant work.
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>. The text for both the 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 completely 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.