RE: [docbook-apps] acronyms, abbreviations, definitions

["Rowland, Larry" <larry.rowland@hp.com>]

The glossentry element includes acronym and abbrev as valid children.  This is where it might be best to link the expansion of the acronym or abbreviation to the acronym or abbreviation (the expansion is in the glossterm).  A fairly simple extension of the transforms allowed us to have the acronym elements link to the appropriate glossentry automatically (we had glossterm.auto.link and glossentry.show.acronym set).

Getting expansion on hover or similar is slightly trickier, but not a major stretch (the match to the glossentry is already being made by the extended glossterm auto link code) by adding a title attribute with the content of the glossterm to the anchor element around the acronym in the output (at least in HTML).

The advantage of storing it centrally in the glossary is that the expansion doesn't have to be added to every instance of the acronym (while convention says it only needs to be expanded at "first occurrence," in electronic media, determining the "first occurrence" for a reader can be difficult so we frequently used an acronym tag the first time an acronym was used in a topic).  It also provides a mechanism for explaining what the expanded acronym means, since expansion is not always sufficient to explain why it matters.

Regards,
Larry Rowland

-----Original Message-----
From: Cramer, David W (David) [mailto:dcramer@motive.com] 
Sent: Wednesday, November 10, 2010 7:12 AM
To: n@n-faktor.net; docbook-apps@lists.oasis-open.org
Subject: RE: [docbook-apps] acronyms, abbreviations, definitions

Hi Nathalie,
I once started to implement an acronym expanding xslt with the idea that I could write <acronym>TLA</acronym> and have the first occurrence automatically be expanded to "TLA (Three Letter Acronym)". Things were going fine till I hit "GNU" and ended up with GNU (GNU (GNU (...) is not Unix) is not Unix) ;-)

You might check out the Glossary database feature: http://www.sagehill.net/docbookxsl/GlossDatabase.html

Then you could do <glossterm>UN</glossterm> and have the xslts automatically add a glossentry defining "United Nations"

David

> -----Original Message-----
> From: Nathalie Sequeira [mailto:n@n-faktor.net]
> Sent: Wednesday, November 10, 2010 1:00 AM
> To: docbook-apps@lists.oasis-open.org
> Subject: Re: [docbook-apps] acronyms, abbreviations, definitions
> 
> Hello again,
> since no one has replied: should I be asking this question somewhere
> else?
> 
> I have also searched the archives, but have not found any relevant
> info.
> One thread in Nov.2006 dealt with the usefulness of acronyms
> (personally, I really need these to meet accessibility requirements!),
> but unfortunately did not mention how to include their expansions in
> docBook.
> 
> So thanks for any pointers on how to go about finding a solution to
> this!
> Nathalie
> 
> 
> Nathalie Sequeira wrote:
> > Hello list!
> >
> > 1. I'm  a bit insecure on how to mark up inline acronyms &
> > abbbreviations in docBook.
> > Coming from XHTML, I was expecting an attribute that can contain
> their
> > written-out counterparts, somewhat like
> > <abbr title="United Nations">UN</abbr>
> > but cannot find a similar mechanism in the docBook 5 online
> reference.
> >
> > Is there any "standard" way of including this essential information?
> > Or should we do something like
> > <abbreviation>UN<phrase>United Nations</phrase></abbreviation>
> > and let XSL transformation deal with the <phrase/> (or is another
> > element semantically more adequate?), either setting it in
> parentheses
> > inline, creating a linked list of glossary terms at the end of the
> > text (e.g. for PDF output) or transforming into HTML attributes in
> > HTML output?
> >
> > 2. Is there an element that is suited for inline definitions (I
> > haven't found any obvious choice and am quite lost on how to get this
> > done...)?
> >
> > Thanks for any thoughts on this!
> > Nathalie Sequeira
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> > For additional commands, e-mail: docbook-apps-help@lists.oasis-
> open.org
> >
> >
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org


---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org