[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Fw: Revisions to Acronym proposal
Here is the revised Acronym / Glossary proposal, based on yesterday's TC meeting. Thanks - Robert D Anderson IBM Authoring Tools Development Chief Architect, DITA Open Toolkit (507) 253-8787, T/L 553-8787 (Good Monday & Thursday) ----- Forwarded by Robert D Anderson/Rochester/IBM on 01/23/2008 09:23 AM ----- Erik Hennum/Oakland/IB M To "Andrzej Zydron" 01/22/2008 06:20 <azydron@xml-intl.com>, "Gershon L PM Joseph" <gershon@tech-tav.com>, "Ogden, Jeff" <jogden@ptc.com>, "JoAnn Hackos" <joann.hackos@comtech-serv.com>, Kara Warburton/Toronto/IBM, Michael Priestley/Toronto/IBM, Robert D Anderson/Rochester/IBM cc Don Day/Austin/IBM Subject Re: Revisions to Acronym proposal (Document link: Robert D Anderson) Hi, Terminology Enthusiasts: In response to the problems identified in the markup by the Translation Subcommittee meeting on Monday (and as agreed at the full DITA Committee meeting today), I've made the changes listed by Robert below. Please forward the attached HTML document to the wider Subcommittee list and see if the changes fixed the identified problems in the markup. (See attached file: IssueGlossary12026.html) Besides the fixes to the technical specification of the markup and the processing expectations for the markup, the other outstanding item was the correction of errors in the translation discussion. Rather than someone else reviewing the document for errors in the translation discussion and sending the errata to me, it would make more sense for someone on the Subcommittee who already has the knowledge and insight to correct those errors. Toward that end, here's the source: (See attached file: IssueGlossary12026.dita) Hoping that's useful, Erik Hennum ehennum@us.ibm.com Robert D Anderson/Rochester/IBM wrote on 01/21/2008 04:14:09 PM: > As we agreed at today's call, I had a follow-up meeting with Erik > Hennum to discuss the translation group's suggestions. As a result, > there are now several concrete suggestions as changes to the > original proposal (http://lists.oasis-open.org/archives/dita- > translation/200801/msg00003.html). I'll list the specifics below, > and then send a more general note to the main TC list. > > 1. The group suggested that expanded forms should come first. So, > the proposal can remove glossAcronym and glossAbbreviation as > options for the main 'title' of the glossary topic. Instead, the > expanded term will be located first, using the glossterm markup that > is used for every glossary entry. The glossAcronym or > glossAbbreviation are listed after that as alternate versions of the > expanded term. > > 2. The glossFullForm (also called glossExpandedForm) element can be > removed, because the expanded form of the term is already encoded asthe term. > > 3. When authors reference an acronym inline with the <abbreviated- > form> element, the rules will follow those defined by the > translation subcommittee: > - The first instance in one context will pull text from the glossSurfaceForm > - Future instances will pull from the first glossAcronym (similar to > today's discussion, in that we cannot prevent many but users should > only have one) > - The consensus on today's call was that if an acronym is not > available in a target language, the expanded value should be > specified. However, if the acronym is empty because a translator > removed it, the primary term (the expanded form) should be used. > > 4. The existing <glossStatus> element has a new value of "preferred" > in the enumeration. This can be used to indicate that an alternate > form (such as an acronym) is the preferred representation of a term. > This is still not a required element for acronym processing. If a > <term> element is used to reference a glossary entry, the following > rules will be used when retrieving the term: > - As a first choice, the form of the term marked "preferred" will beretrieved > - If no term is marked preferred, or if the preferred term is empty > (possibly because it does not exist in a target language), the > primary term will be retrieved > - NOTE: using <abbreviated-form> will always use the processing > rules defined in #3, regardless of what is marked "preferred" > > 5. As mentioned at the call, the language in the proposal about > acronyms needs to be cleaned up to include all of the translation > issues described in the original proposal.Title: DITA Proposed Feature #12026 and #12038
DITA Proposed Feature #12026 and #12038Build on the DITA 1.1 glossary specialization for more complete support of glossary, linguistic, and semantic applications and also 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. Comparison of original and revised acronym markupThis section contrasts the original and revised markup for the acronym example terms.
Single sourcing for terminology applicationsThis section gives examples of how subsets of the glossentry markup can be used for different applications making use of terms. Usage for acronym resolutionAn adopter interested only in term resolution for acronyms can declare an acronym with a glossentry topic similar to the following example: <glossentry id="abs"> <glossterm>Anti-lock Braking System</glossterm> <glossBody> <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm> <glossAlt> <glossAcronym>ABS</glossAcronym> </glossAlt> </glossBody> </glossentry> The adopter can declare a key for the acronym using the standard DITA 1.2 keyref mechanism: <map> ... <topicref href="maintcar.dita"/> ... <glossref keys="abs" href="antiLockBrake.dita"/> ... key declarations for other referenced acronyms ... </map> The adopter can then refer to the acronym using the standard DITA 1.2 keyref mechanism: <task id="maintcar"> ... <info>The <abbreviated-form keyref="abs"/> will prevent the car from skidding ...</info> ... </task> Processes should resolve the "abs" reference to the <glossSurfaceForm> text in introductory contexts and to the <glossAcronym> text in other contexts. Usage for glossary publishingAn adopter interested only in traditional glossary publishing can explain one sense of a term with a glossentry topic similar to the following example: <glossentry id="abs"> <glossterm>Anti-lock Braking System</glossterm> <glossdef>A brake technology that minimizes skids.</glossdef> <glossBody> <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm> </glossBody> </glossentry> The adopter can then pull together a subset of the defined terms for a deliverable as in the following example: <map> ... <topichead navtitle="glossary"> <topicref href="antiLockBrake.dita"/> ... other terms in the glossary for this deliverable ... </topichead> </map> To produce a traditional glossary, a process should sort the terms included in a deliverable and list the explained senses under each term. Usage for both acronym resolution and glossary publishingAdopters don't have to declare the same acronym in different ways for different purposes but instead can single source 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: <glossentry id="abs"> <glossterm>Anti-lock Braking System</glossterm> <glossdef>A brake technology that minimizes skids.</glossdef> <glossBody> <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm> <glossAlt> <glossAcronym>ABS</glossAcronym> </glossAlt> </glossBody> </glossentry> The glossary can include the explained acronym (as shown in the following example) as well as glossary term that aren't acronyms. In addition, the team can create acronyms that are referenced but not included in the glossary: <map> ... <topicref href="maintcar.dita"/> ... <topichead navtitle="glossary"> <topicref keys="abs" href="antiLockBrake.dita"/> ... other referenced terms in the glossary ... </topichead> ... key declarations for other referenced acronyms that aren't in the glossary ... </map> The adopter can still refer to the acronym with the <abbreviated-form> element as in the following example: <task id="maintcar"> ... <info>The <abbreviated-form keyref="abs"/> will prevent the car from skidding ...</info> ... </task> Processing for term resolution to either the <glossSurfaceForm> or <glossAcronym> text and processing for glossary publishing work as before. Usage for populating a terminology databaseWhile 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: <glossentry id="abs"> <glossterm>Anti-lock Braking System</glossterm> <glossdef>A brake technology that minimizes skids.</glossdef> <glossBody> <glossPartOfSpeech value="noun"/> <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm> <glossAlt> <glossAcronym>ABS</glossAcronym> <glossStatus value="preferred"/> <glossUsage>Recommended because more readers are familiar with the acronym than the term.</glossUsage> </glossAlt> <glossAlt> <glossSynonym>Anti-skid Brakes</glossSynonym> <glossStatus value="restricted"/> <glossUsage>Allowed in legacy content but not in new content.</glossUsage> </glossAlt> </glossBody> </glossentry> 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. Acronym termsThis section discusses the subset of the glossentry vocabulary specific to acronyms. Reference for acronym termsTo 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 Technical Requirements below). Two new domains complement the glossary entry topic to make it easy to refer to acronyms (as shown in the example of acronym resolution):
Rendition of Abbreviated FormsWhen 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." Translation Issues for Abbreviated FormsThe following cases for abbreviated forms must be contemplated when working with documents that require internationalization:
All termsThis section provides a discusses the full glossentry markup available for any terminology application. Longer descriptionDITA 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:
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. Statement of RequirementThe 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. Use Cases
ScopeModerate: adding elements to one specialized topic, providing a map domain for defining keys, and providing an element domain for referring to keys. Technical RequirementsThe full set of elements provided by the expanded glossentry topic includes the following elements:
The following example shows the minimum declaration of a term: <glossentry id="highavail"> <glossterm>High Availability</glossterm> </glossentry> The following example shows a detailed glossary entry specifying the usage for the preferred and alternate terms: <glossentry id="usbfd"> <glossterm>USB flash drive</glossterm> <glossdef>A small portable drive.</glossdef> <glossBody> <glossPartOfSpeech value="noun"/> <glossUsage>Do not provide in upper case (as in "USB Flash Drive") because that suggests a trademark.</glossUsage> <glossAlt> <glossAcronym>UFD</glossAcronym> <glossUsage>Explain the acronym on first occurrence.</glossUsage> </glossAlt> <glossAlt id="memoryStick"> <glossSynonym>memory stick</glossSynonym> <glossUsage>This is a colloquial term.</glossUsage> </glossAlt> <glossAlt> <glossAbbreviation>stick</glossAbbreviation> <glossStatus value="prohibited"/> <glossUsage>This is too colloquial.</glossUsage> <glossAlternateFor href="javascript:void(0);"/> </glossAlt> <glossAlt> <glossAbbreviation>flash</glossAbbreviation> <glossStatus value="prohibited"/> <glossUsage>This short form is ambiguous.</glossUsage> </glossAlt> </glossBody> </glossentry> 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: <map> ... <topicref keys="reliability" href="highavail.dita" linking="none" toc="no" print="no" search="no"/> ... <topicref href="configdb.dita"/> ... </map> <task id="configdb"> <title>Configuring the database.</title> ... <context>To enable <term keyref="reliability"/>, you configure the database</context> ... </task> Two new domains support easy definition and use of keys for glossary entry topics:
Writers can set the linking attribute to 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 keys attribute to pull a glossary topic into a TOC context while defining a key. 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 keyref attribute to refer to a glossentry. Processing inserts text from the glossentry topic only when the referencing <term> element doesn't contain text. As a result, writers can use the <term> element to delimit terms within content while identifying the corresponding glossary entry. That is, the <term> element can provide a context-specific surface form as its content where appropriate. 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.) New or Changed Specification LanguageThe 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. Costs
Benefits
|
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]