These elements are very underused in TDE Documentation up to this point, and we will probably make an effort to implement them more fully at some point. In the meantime, you may use them if you wish, so they are explained here.
<glossterm>
Use this inline to identify words in the text that are explained further
in a <glossary>
or <glosslist>
. When it's placed inside a
<glossentry>
it contains the term that
glossary entry is defining (see the example below to see this in
action.)
<glossary>
Put this where you have the glossary appearing. This is usually at the end of the document, perhaps last before the credits section, or before an index. A glossary will become a separate section in the book.
<glosslist>
Use this if the glossary is fairly short and simple. It can
appear anywhere a normal list could appear. For TDE Documentation, a proper
glossary is preferred, so keep use of <glosslist>
to a minimum, where your glossary
would only contain a small handful of entries. Use your own judgement
which is most appropriate. You might use a glosslist for example, to
explain a list of terms which only appear in one section, but are very
important to understanding that section and occur several times there,
so you want the explanations to appear close to the text.
<glossdiv>
Divides a glossary into several smaller sections. A good use of this in a very large glossary could be to break it up into separate sections for each letter in the alphabet.
<glossentry
id="">
Contains the actual entries in the glossary or glosslist, where you
explain the terms you have marked up with glossterm in the text. You
should give these an id
, so they
can be linked to from the text, and crossreferenced between glossary
entries.
A glossentry
always contains one
<glossterm>
. It also contains one <glossdef>
,
or one <glosssee>
, or a <glossdef>
and a <glossseealso>
.
I would suggest a consistent naming scheme, so glossary entries are easy
to reference without having to go look them up all the time. For
example, I use the form id="gloss-
,
where word
"word
is the term that is being
explained.
<glossdef>
Contains the actual definitions of the terms
<glosssee
otherterm="">
You can use this to save duplicating entries in the glossary. Instead
of a <glossdef>
you can put <glosssee>
with the id of
another <glossentry>
.
<glossseealso
otherterm="">
This is very similar to <glosssee>
,
but instead of replacing the <glossdef>
it is in addition to
it.
If you compare a glossary entry to a variable list entry, you'll see the
structure is quite similar, with a glossterm
taking the place of the term
, and a glossdef
taking the place of the listitem
. Since variable lists get heavy use
in TDE Documents, it shouldn't take you long to pick up how to do a
glossary.
Example 17.1. How to markup a glossary
Say you have in the text of the document the following sentence:
KWord is a graphical, wysiwyg word processor, and is part of KOffice.
You want to have the words KWord and koffice in the index, and KWord, wysiwyg, “word processor” and KOffice explained in a glossary.
Many of these terms also need to be marked up with other tags, such as application, and acronym.
The eventual markup would look like this:
<para><glossterm linkend="gloss-kword">KWord</glossterm>
<indexterm><primary>KWord</primary></indexterm> is a
graphical <glossterm linkend
="gloss-wysiwyg"><acronym>WYSIWYG</acronym></glossterm>
<glossterm linkend="gloss-word-processor">word
processor</glossterm>, and is part of <glossterm
linkend="gloss-koffice">KOffice</glossterm>.
<indexterm><primary>KOffice</primary></indexterm></para>
The next part is shown here as a <glosslist>
, and if there were really only this
many entries in it, that could be entirely appropriate. In reality, if
you are going to make a glossary, it would have many more entries and so
would warrant it's own <glossary>
section. The syntax inside <glossary>
and <glosslist>
are otherwise the
same.
<glosslist>
<glossentry id="gloss-kword">
<glossterm>KWord</glossterm>
<glossdef><para>The name of the TDE word
processor</para></glossdef>
</glossentry>
<glossentry id="gloss-koffice">
<glossterm>KOffice</glossterm>
<glossdef><para>A collection of office productivity tools, designed
by and for <acronym>TDE</acronym>, including presentation software,
a word processor, a spreadsheet, a <acronym>PIM</acronym>, and a
vector illustration application.</para></glossdef>
</glossentry>
<glossentry id="gloss-word-processor">
<glossterm>word processor</glossterm>
<glossdef><para>An application for handling text, typically more
concerned with formatting visually than a plain text
editor.</para></glossdef>
</glossentry>
<glossentry id="gloss-wysiwyg">
<glossterm>WYSIWYG</glossterm>
<glossdef><para>Stands for <quote>What You See Is What You
Get</quote>, indicating that you can visually format the presentation of
your data onscreen, and when you print the document, it will look exactly as you
see on the screen.</para></glossdef>
</glossentry>
</glosslist>
And the result of all this would be as follows:
KWord is a graphical WYSIWYG word processor, and is part of KOffice..
The name of the TDE word processor
A collection of office productivity tools, designed by and for TDE, including presentation software, a word processor, a spreadsheet, a PIM, and a vector illustration application.
An application for handling text, typically more concerned with formatting visually than a plain text editor.
Stands for “What You See Is What You Get”, indicating that you can visually format the presentation of your data onscreen, and when you print the document, it will look exactly as you see on the screen.
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team