docbook-apps

Back to discussions
Expand all | Collapse all

acronyms, abbreviations, definitions

  • 1.  acronyms, abbreviations, definitions

    Posted 11-03-2010 07:40
    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
    UN
    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



  • 2.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-10-2010 07:00
    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
    > UN
    > 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
    >
    >




  • 3.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-10-2010 07:36
    On Wed, 10 Nov 2010 07:59:54 +0100
    Nathalie Sequeira <n@n-faktor.net> wrote:

    > Hello again,
    > since no one has replied: should I be asking this question somewhere
    > else?

    No, you're quite right here.

    <book xmlns="http://docbook.org/ns/docbook">

    <chapter>


    <para>NASA <phrase condition="exp">National Aeronautics
    and Space Administration. </phrase>
    </para>

    </chapter>
    </book>


    Your usage was perfectly good. You'll have to add a customisation layer
    to process acronym as you want it.


    Since docbook has no 'proper' expansion of an acronym, I've used the
    universal phrase with a condition?

    http://www.docbook.org/tdg/en/html/acronym.html

    Perhaps you might like to submit a feature request, for the expansion
    of acronym to include it's 'spelling out'?
    http://sourceforge.net/tracker/?group_id=21935&atid=373750

    It is IMHO a valid addition.



    HTH

    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 4.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-11-2010 07:45
    rfe 3107140 submitted.




    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 5.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-11-2010 10:59
    Hello Dave,

    thank you for the reassuring feedback :)
    > Since docbook has no 'proper' expansion of an acronym, I've used the
    > universal phrase with a condition?
    >
    After pondering this a bit, I do understand why you'd qualify the
    phrase with an attribute:
    it's not just any old phrase, but a phrase that serves a specific
    function, i.e. to expand the acronym/abbreviation.

    However, I do not understand why mark it with a "condition"? It would
    seem more logical to me to attribute it a "role", no?

    > Perhaps you might like to submit a feature request, for the expansion
    > of acronym to include it's 'spelling out'?
    > http://sourceforge.net/tracker/?group_id=21935&atid=373750
    >
    > It is IMHO a valid addition.
    >
    Thanks for submitting this already!
    I will try my luck in requesting the same for <abbrev> too, since the
    improvement in accessibility can be considerable in screen reader output
    for both.

    Nathalie



  • 6.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-11-2010 18:01
    On Thu, 11 Nov 2010 11:59:07 +0100
    Nathalie Sequeira <n@n-faktor.net> wrote:

    > Hello Dave,
    >
    > thank you for the reassuring feedback :)
    > > Since docbook has no 'proper' expansion of an acronym, I've used the
    > > universal phrase with a condition?
    > >
    > After pondering this a bit, I do understand why you'd qualify the
    > phrase with an attribute:
    > it's not just any old phrase, but a phrase that serves a specific
    > function, i.e. to expand the acronym/abbreviation.
    >
    > However, I do not understand why mark it with a "condition"? It would
    > seem more logical to me to attribute it a "role", no?

    Yes, it could be role. I chose condition since that seemed right
    to me. YMMV

    but you do need it for the customization layer, To process these
    as you want them, hopefully until the Docbook committee agree
    it is a worthwhile addition.







    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 7.  RE: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-10-2010 14:12
    Hi Nathalie,
    I once started to implement an acronym expanding xslt with the idea that I could write TLA 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


  • 8.  RE: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-10-2010 22:19
    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


  • 9.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-11-2010 07:37
    On Wed, 10 Nov 2010 22:18:45 +0000
    "Rowland, Larry" <larry.rowland@hp.com> wrote:

    > 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).


    try it, with your eyes closed. This doesn't work Larry.
    Go through the motions compared with the inline acronym expansion.
    The expansion needs to be with the acronym, so that a tts
    app can read the acronym and its expansion together.





    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 10.  RE: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-16-2010 19:39
    Actually, if you read the entire message, I was not suggesting that the
    rendered document have the content in a different location, I was suggesting
    that there was already markup available to represent the binding of the
    expansion to the acronym or abbreviation. I am well aware that the rendered
    content has to have the expansion information attached to the element itself.

    I still feel that centrally locating the association is preferable in a
    modern document that is potentially delivered via the Web with entry points
    that may be based on search results or other non-narrative paths through a
    document. Centrally locating the associated expansion reduces redundant
    coding.

    Regards,
    Larry


    Original Message


  • 11.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-17-2010 07:46
    On Tue, 16 Nov 2010 19:38:51 +0000
    "Rowland, Larry" <larry.rowland@hp.com> wrote:

    > Actually, if you read the entire message, I was not suggesting that
    > the rendered document have the content in a different location, I was
    > suggesting that there was already markup available to represent the
    > binding of the expansion to the acronym or abbreviation. I am well
    > aware that the rendered content has to have the expansion information
    > attached to the element itself.
    >
    > I still feel that centrally locating the association is preferable in
    > a modern document that is potentially delivered via the Web with
    > entry points that may be based on search results or other
    > non-narrative paths through a document. Centrally locating the
    > associated expansion reduces redundant coding.


    But this isn't a glossary entry Larry? It's semantically wrong IMHO.
    DaveP

    > > 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).
    >
    >
    > try it, with your eyes closed. This doesn't work Larry.
    > Go through the motions compared with the inline acronym expansion.
    > The expansion needs to be with the acronym, so that a tts
    > app can read the acronym and its expansion together.
    >
    >
    >
    >
    >



    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 12.  RE: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-17-2010 13:07
    > On Tue, 16 Nov 2010 19:38:51 +0000
    > "Rowland, Larry" <larry.rowland@hp.com> wrote:
    >
    > > Actually, if you read the entire message, I was not suggesting that
    > > the rendered document have the content in a different location, I was
    > > suggesting that there was already markup available to represent the
    > > binding of the expansion to the acronym or abbreviation. I am well
    > > aware that the rendered content has to have the expansion information
    > > attached to the element itself.
    > >
    > > I still feel that centrally locating the association is preferable in
    > > a modern document that is potentially delivered via the Web with
    > > entry points that may be based on search results or other
    > > non-narrative paths through a document. Centrally locating the
    > > associated expansion reduces redundant coding.
    >
    >
    > But this isn't a glossary entry Larry? It's semantically wrong IMHO.
    > DaveP

    Really? You come across "<glossterm>TLA</glossterm>" in a document and don't know what "TLA" means...so you look to the glossary and find <glossentry><glossterm>TLA</glossterm><glosssee>Three Letter Acronym</glosssee></glossentry> (and then to a separate entry for "Three Letter Acronym" which defines it). What could be more semantically pure than that? Larry is just suggesting that the OP do some stylesheet customization to leverage the existing DocBook markup and meet usability needs. There's probably room for enhancements to the schema (an otherterm attribute on acronym and abbrev?), but there's something to work with now including a nifty feature for maintaining a centralized glossary.

    David



  • 13.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-17-2010 16:02
    On Wed, 17 Nov 2010 07:07:01 -0600
    "Cramer, David W (David)" <dcramer@motive.com> wrote:

    > > But this isn't a glossary entry Larry? It's semantically wrong IMHO.
    > > DaveP
    >
    > Really? You come across
    > "<glossterm>TLA</glossterm>" in a document and
    > don't know what "TLA" means...

    OK, I'll play dumb.
    I want to use acronym, with an expansion, in a para David.
    The fact that it's an acronym in a glossary is of little use to me
    and any blind user having the text read to him/her?

    OK. RFE submitted.





    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 14.  RE: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-17-2010 16:32
    > > > But this isn't a glossary entry Larry? It's semantically wrong
    > IMHO.
    > > > DaveP
    > >
    > > Really? You come across
    > > "<glossterm>TLA</glossterm>" in a document and
    > > don't know what "TLA" means...
    >
    > OK, I'll play dumb.
    > I want to use acronym, with an expansion, in a para David.
    > The fact that it's an acronym in a glossary is of little use to me
    > and any blind user having the text read to him/her?
    >
    > OK. RFE submitted.

    My understanding of Larry's suggestion is that the OP customize the stylesheets so that acronyms and abbreviations (only the first instance in a book or the first instance in a chunk in html) contain the appropriate stuff in the result. The data regarding the expanded form is stored in the master glossary. The stylesheets do the work of looking it up and supplying the appropriate markup in the output. In pdf, the stylesheets expand the first occurrence of "<glossterm linkend="tla.glossary"><abbrev>TLA</abbrev></glossterm>" to "TLA (Three Letter Abbreviation)" (maybe with a hyperlink to the glossary for online users) and add the term to the <glossary>. In chunked html, the stylesheets do whatever is going to make screen readers happy or is going to meet your needs for a given context (e.g. tooltip definitions for sighted users). The main suggestion is that instead of storing the expanded form in each abbrev/acronym in the source, you store it in one place. Ideally, in your authoring environment you would also provide a convenient way for writers to add entries from the master glossary.

    So I don't think there's really any disagreement. This is more a suggestion of how to manage the information on the source side, not anything about the details of what you should do on the output side.

    David



  • 15.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-18-2010 07:43
    On Wed, 17 Nov 2010 10:31:32 -0600
    "Cramer, David W (David)" <dcramer@motive.com> wrote:
    nd any blind user having the text read to him/her?
    > >
    > > OK. RFE submitted.
    >
    > My understanding of Larry's suggestion is that the OP customize the
    > stylesheets so that acronyms and abbreviations (only the first
    > instance in a book or the first instance in a chunk in html) contain
    > the appropriate stuff in the result. The data regarding the expanded
    > form is stored in the master glossary. The stylesheets do the work of
    > looking it up and supplying the appropriate markup in the output. In
    > pdf, the stylesheets expand the first occurrence of "<glossterm
    > linkend="tla.glossary"><abbrev>TLA</abbrev></glossterm>" to "TLA
    > (Three Letter Abbreviation)" (maybe with a hyperlink to the glossary
    > for online users) and add the term to the <glossary>. In chunked
    > html, the stylesheets do whatever is going to make screen readers
    > happy or is going to meet your needs for a given context (e.g.
    > tooltip definitions for sighted users). The main suggestion is that
    > instead of storing the expanded form in each abbrev/acronym in the
    > source, you store it in one place. Ideally, in your authoring
    > environment you would also provide a convenient way for writers to
    > add entries from the master glossary.
    >
    > So I don't think there's really any disagreement. This is more a
    > suggestion of how to manage the information on the source side, not
    > anything about the details of what you should do on the output side.
    >
    > David


    I think there is. A screen reading app will not be looking for
    glossentries David. A reader app comprehends acronyms and will read out
    the full one if the text is there.
    Hence my RFE to have acronym and a child (with expansion) as a primary
    inline.

    I do however agree that those subsequent to the first use (as is common)
    may use an alternative to expansion for each occurrence, though I'd need
    to take advice as to how that should be marked up (in the resulting html
    for instance). PDF is a different ball game for a screen reader.






    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 16.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-11-2010 14:47
    Hi Larry,

    > 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.
    >
    At first I found the prospective offered by the glossary database
    feature rather enticing, exactly because of the repetitiveness (during
    the production phase) of adding the extended version - ideally to each
    - instance of an abbreviation/acronym.

    So the idea of having an external glossary that is run over a text in
    which the acronyms/abbreviations are also marked as glossterms (which,
    when explanation is necessary, can also be linked to a "real" glossary -
    slick!), and xslt'ing the lot into nicely formed, fully functional
    XHTML-Elements would be something that could greatly enhance the reading
    experience of online versions, while in PDF/print versions, just the
    classical glossary could be output...

    However, the question arises for me how viable this is when dealing with
    a very large text base.
    (in my case I'm working on a growing online library with currently 1600
    texts - from short articles to whole books - dealing with diverse
    aspects of "disability" on a variety of levels).
    - I'd be afraid that the glossary itself would soon grow to dimensions
    that are not so easily to be edited anymore.
    - And, as I understood it, the text is processed in loops for each
    single glossary term (even if 3/4 of them are not relevant for the text
    in question). Since our HTML-versions are cached, this would not happen
    every time the pages are loaded, but still... wouldn't that create an
    enormous processing overhead?

    Asked the other way around, how large is the text base you apply this
    technique to?

    Also, I'm not sure about how your output looks:
    > 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).
    Do I understand rightly that you are adding the expansion as a title to
    the element?
    I hate to say so, but I am just currently being made aware of the fact
    that "title" does not work reliably on links in screen readers.
    Apart from the fact that the expansion is no longer attributed to the
    acronym itself, but rather becomes additional information about the
    content being linked to...
    So what may look the same for sighted people is a completely different
    (and possibly invisible) creature for screen reader output.
    This mechanism should thus actually insert the glossterm into acronym to
    make it fully functional (perhaps only creating the glossary link when
    there is, in fact, an additional explanation...).

    Thanks for the interesting input :)
    Nathalie


  • 17.  RE: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-16-2010 20:16
    Hello Nathalie,

    A couple of things:

    1) You don't have to have a single glossary database for all your documents.
    It is quite reasonable to break it up into glossaries that are topic-appropriate.

    2) Title was what the W3C consortium recommend at one time for the expansion. I have
    not kept up with it for a while, since dropping out of the accessibility police in
    the writing group I worked with. If you want to have other behavior, such as
    expanding it inline, it is a matter of slightly different coding to make it work.
    I have noticed that there is a lot of variability in what screen readers actually
    do with the same source markup and find that somewhat frustrating. It is similar
    to the CSS wars among browsers in the early days of CSS (when we had to use a
    JavaScript to load the appropriate CSS file based on the platform and browser
    being used (and even version of browser in some cases). There is some chatter on
    the Web that indicates using acronym vs. abbr can lead to different behavior for
    the title.

    3) If you are worried about the size of a glossary database, the same thing can be
    done with a glossary section in a book (or other document). The downside is that
    you have to repeat the glossterm in each document it is used in, but the upside is
    you can customize the glossary appropriately in a manner appropriate to a specific
    context. I wrote a simple script to extract terms from a master glossary and
    add them to a glossary which was then made part of the book itself, rather than
    using the glossary database (specifically to avoid problems with render time and
    creeping changes in a glossary -- you don't always want the most current version
    of glossary entries every time a document is built).

    4) The expansion was added to the acronym element, as recommended by W3C for
    expansion of acronyms. A title on the anchor element (the a) would be associated
    with the link destination rather than with the acronym.

    As a friend of mine frequently says, "I admire your problem."

    Good luck solving it.

    Best Regards,
    Larry Rowland


    Original Message


  • 18.  Re: [docbook-apps] acronyms, abbreviations, definitions

    Posted 11-11-2010 11:18
    Hello David,

    > I once started to implement an acronym expanding xslt with the idea that I could write TLA 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) ;-)
    >
    That of course is not what one would want to happen - what an example :)

    > You might check out the Glossary database feature: http://www.sagehill.net/docbookxsl/GlossDatabase.html
    >
    Thanks for pointing me at this - the mechanism may be a good (or even
    improved) substitute for the XHTML , especially if we try to
    assist people with cognitive disabilities in understanding texts - in
    German (the language our project is dealing most with), there's a
    science of its own determining what are "hard" words; these could be
    dealt with in this way, increasing the accessibility of texts not
    translated into "easy language"...

    Nathalie


Related Content