RE: [dita] Groups - Issue #12038 - Proposal: Acronyms and other Abbrevia

Sorry for the extra e-mail earlier. The earlier attempt to send this comment got away from me before I'd added any content.

What follows assumes that we continue with the inline content conref based approach to acronym processing that has been proposed. I'm not advocating that and in fact think that a key reference based approach and/or an approach that builds upon the glossary work is worth investigating.

During today's DITA TC call I agreed to write something about matching acronym content to allow processing to determine when an acronym is being used repeatedly. I suggest if the content of the <short> element from two <abbreviated-form> blocks matches, that the blocks be considered as referencing the same acronym.

To keep the division between the DITA specification and styling clean, once we’ve defined know how matching is done, processing can figure out what is or isn't a first use in a particular context and do the “right thing”. In the DITA specification we don't need to define what is or isn’t a first use or what the right thing to do is, although we could include something about this that is clearly marked as an example or a suggestion.

Here is an example:

If I have a topic, myAcronyms.dita, that contains the following:

<title>My Reusable Acronyms</title>

<body>

<p>

<abbreviated-form id="abs">

<expanded>Anti-lock Braking System</expanded>

<surface-form>Anti-lock Braking System (ABS)</surface-form>

</abbreviated-form>

</p>

</body>

</topic>

And a topic that uses the acronym:

<title>Troubleshooting your <abbreviated-form conref="myAcronyms.dita#myAcronyms/abs"/></title>

<shortdesc>Read this section to learn how to diagnose and troubleshoot your GM

<abbreviated-form conref="myAcronyms.dita#myAcronyms/abs"/>.

</shortdesc>

. . .

</topic>

Once the conref in the troubleshootingABS topic is resolved you have:

<title>Troubleshooting your

<abbreviated-form>

<expanded>Anti-lock Braking System</expanded>

<surface-form>Anti-lock Braking System (ABS)</surface-form>

</abbreviated-form>

</title>

<shortdesc>Read this section to learn how to diagnose and troubleshoot your GM

<abbreviated-form>

<expanded>Anti-lock Braking System</expanded>

<surface-form>Anti-lock Braking System (ABS)</surface-form>

</abbreviated-form>

.</shortdesc>

. . .

</topic>

Because the id attribute on the conref target is gone after the conref is resolved, a processor seeing this input stream needs to be able to match something else from each <abbreviated-form> occurrence to see if it is the same abbreviation. My suggestion is to match on the contents of the <short> element. In this example the content from the <short> element in both cases is “ABS” and so these are references to the same acronym. And of course the content has to match because they were both conrefed from the same place using the same id.

-Jeff

> -----Original Message-----

> From: gljoseph@yahoo.com [mailto:gljoseph@yahoo.com]

> Sent: Sunday, December 09, 2007 3:08 AM

> To: dita@lists.oasis-open.org

> Subject: [dita] Groups - Issue #12038 - Proposal: Acronyms and other

> Abbreviated Forms (IssueNumbe12038.html) uploaded

> Hi all,

> Here is the HTML version of Issue #12038 - Proposal: Acronyms and other

> Abbreviated Forms.

> Gershon

> -- Mr. Gershon Joseph*

> The document named Issue #12038 - Proposal: Acronyms and other Abbreviated

> Forms (IssueNumbe12038.html) has been submitted by Mr. Gershon Joseph* to

> the OASIS Darwin Information Typing Architecture (DITA) TC document

> repository.

> Document Description:

> HTML format of proposal for Issue #12038 - Acronyms and other Abbreviated

> Forms

> View Document Details:

> http://www.oasis-

> open.org/apps/org/workgroup/dita/document.php?document_id=26361

> Download Document:

> http://www.oasis-

> open.org/apps/org/workgroup/dita/download.php/26361/IssueNumbe12038.html

> PLEASE NOTE: If the above links do not work for you, your email

> application

> may be breaking the link into two pieces. You may be able to copy and

> paste

> the entire link address into the address field of your web browser.

> -OASIS Open Administration

dita message