docbook-apps

I've always been tagging all of my acronyms and abbreviations with the
proper DocBook elements, simply because it seemed to me that it was standard
practice to do so when I first got started.

Now, however, I'm beginning to wonder why I keep doing this. When I'm
writing the type of technical documentation that I do (which is mainly
hardware manuals), I tend to use *a lot* of acronyms and abbreviations, and
I'm beginning to think that tagging them all is just adding unnecessary
work, since I never do anything special with these elements when
formatting/transforming my documents.

So, my question is this: should I bother using elements such as these that I
don't really need? It would seem that

The CPU runs at 2.0 <abbrev>GHz</abbrev>

is superfluous if I don't ever use Acronym and Abbrev for anything.

- Colin

Suppose you (or a later editor) wanted to create a glossary
explaining all the acronyms in your document, wouldn't it be nice to
use a little XSLT to pull out all the acronyms and organize them in
alphabetical sequence and add all the appropriate glossary text such
as (minimal)


<glossdiv><title>waiting for something
here</title>
.
.
.
<glossentry
id="CPU"><glossterm></glossterm>
 
<acronym>CPU</acronym>
<glossdef>
 
<para>waiting for some explanation of CPU
here</para>
</glossdef>

</glossentry>

.
.
.
</glossdiv>


Elements can be very useful in future processing of a document,
even if they seem irrelevant now.


Ron




I've always been tagging all of my
acronyms and abbreviations with the proper DocBook elements, simply
because it seemed to me that it was standard practice to do so when I
first got started.


Now, however, I'm beginning to wonder why I keep doing this. 
When I'm writing the type of technical documentation that I do (which
is mainly hardware manuals), I tend to use *a lot* of acronyms and
abbreviations, and I'm beginning to think that tagging them all is
just adding unnecessary work, since I never do anything special with
these elements when formatting/transforming my documents.


So, my question is this: should I bother using elements such as these
that I don't really need?  It would seem that


    The <acronym>CPU</acronym> runs at 2.0
<abbrev>GHz</abbrev>


is superfluous if I don't ever use Acronym and Abbrev for
anything.


- Colin





Ron Catterall, Phd, DSc       email: ron@catterall.net

Prolongacion de Hidalgo 140http://catterall.net/

San Felipe del Aguatel:
+52 951 520 1821

Oaxaca      68020Mexicofax:
+1 530 348 8309

A couple of other things that are possible (depending on your
transforms):

- link from acronyms and abbreviations to the glossary
- provide hover text in appropriate environments to explain the acronym
or abbreviation to the user
- provide the expansion text of acronyms and abbreviations that is
recommended by accessibility groups

Your mileage may vary, depending on the sophistication of the production
environment you are publishing with.

Larry Rowland

________________________________

From: Ron Catterall [mailto:ron@catterall.net]
Sent: Wednesday, November 08, 2006 6:11 AM
To: Colin Shapiro
Cc: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Acronyms and Abbreviations


Suppose you (or a later editor) wanted to create a glossary explaining
all the acronyms in your document, wouldn't it be nice to use a little
XSLT to pull out all the acronyms and organize them in alphabetical
sequence and add all the appropriate glossary text such as (minimal)

<glossdiv>
.
.
.
<glossentry id="CPU"><glossterm></glossterm>
CPU
<glossdef>
<para>waiting for some explanation of CPU here</para>
</glossdef>
</glossentry>
.
.
.
</glossdiv>

Elements can be very useful in future processing of a document, even if
they seem irrelevant now.

Ron



I've always been tagging all of my acronyms and abbreviations
with the proper DocBook elements, simply because it seemed to me that it
was standard practice to do so when I first got started.

Now, however, I'm beginning to wonder why I keep doing this.
When I'm writing the type of technical documentation that I do (which is
mainly hardware manuals), I tend to use *a lot* of acronyms and
abbreviations, and I'm beginning to think that tagging them all is just
adding unnecessary work, since I never do anything special with these
elements when formatting/transforming my documents.

So, my question is this: should I bother using elements such as
these that I don't really need? It would seem that

The CPU runs at 2.0 <abbrev>GHz</abbrev>

is superfluous if I don't ever use Acronym and Abbrev for
anything.

- Colin



--
Ron Catterall, Phd, DSc email: ron@catterall.net
Prolongacion de Hidalgo 140
http://catterall.net/
San Felipe del Agua tel: +52 951
520 1821
Oaxaca 68020 Mexico fax: +1 530 348 8309
--------------------------------------------------------------------- To
unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org For
additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

You can always go back and insert the markup if you need it later.

On 11/7/06, Colin Shapiro <cmshapiro@gmail.com> wrote:
<snip/>


--
http://chris.chiasson.name/