This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Firstterm, Glossterm & Glossary
- To: docbook at lists dot oasis-open dot org
- Subject: DOCBOOK: Firstterm, Glossterm & Glossary
- From: fred at ludd dot luth dot se
- Date: Thu, 14 Jun 2001 09:55:44 +0200 (CEST)
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/