DOCBOOK: Firstterm, Glossterm & Glossary

[fred at ludd dot luth dot se]

Hi all,

I am writing my Master Thesis in Computer Science using
DocBook. 
My background in technical writing is not that strong, 
but it is an area that I think is interesting.

My Thesis contains a lot of technical abbreviations and 
I am not sure how to tag these in a good manner.

The examples in DocBook the definitive guide has been 
very helpful but the firstterm, glossterm & glossary 
combination is explained in parts only.

Small example :

EPIC has kept the VLIW idea of a static POE. 
It is also extended with different features to more 
utilize dynamic factors. 
The VLIW parallelism was limited by code that could not be 
100 % proven at compile-time.

(EPIC = Explicitly Parallel Instruction Computing
 VLIW = Very-Large Instruction Word
 POE  = Plan of Execution)

If we concentrate on "VLIW" :

EPIC has kept the  
<firstterm linkend="VLIW">VLIW</firstterm> 
idea of a static POE. 
It is also extended with different features to more 
utilize dynamic factors. 
The <glossterm linkend="VLIW">VLIW</glossterm> 
parallelism was limited by code that could not be 
100 % proven at compile-time.

This would be ok for a person that are familiar with 
what VLIW stands for. When one introduce an abbreviation like
this I have learnt that this format should be used :

EPIC has kept the Very-Large Instruction Word (VLIW) 
idea of a static POE. 

I guess this way may be ok too as long as one is consistent
in the documentation :

EPIC has kept the VLIW (Very-Large Instruction Word) 
idea of a static POE. 

but then you have firstterm-glossterm after each-other.

Also due to the frequent use of similar abbreviations in 
computer texts the source gets cluttered with alot of 
firstterm & glossterm. 
This is OK, but I want to do it right from the beginning.

I also see the possibility to some kind of automation.

Using
<glossentry id="VLIW">
  <glossterm>Very Large Instruction Word</glossterm>
  <acronym>VLIW</acronym>
  <glossdef>
    <para>Some reasonable definition here.</para>
  </glossdef>
</glossentry>

(from docbook/dtd/xml/4.1.2/dbpoolx.mod
<!ELEMENT glossentry (glossterm, acronym?, abbrev?,
                     (%ndxterm.class;)*,
		      revhistory?, (glosssee|glossdef+))> )

The acronym is optional but can be used to trace the 
connection between "VLIW" and "Very-Large Instruction Word"
to produce the "Very-Large Instruction Word (VLIW)"
when firstterm is used.

Ok, now for the questions :

1) What would be the correct way to write VLIW when it
   first occurs ? 

2) How should this be taged ? should <acronym> be used too ? 

3) Is there any "pre-processor" or any thoughts on automatic
   handling of this process ? 
   Even if no tags are used, a "pre-processor" would spot
   the VLIW in the first text and add <firstterm>

Any tips or examples are welcomed.

Thank you

Fredrik Svensson


-----------------------------------------------------------------------
This mail was sent through Ludd's webmail https://webmail.ludd.luth.se/