References, indexes, and glossariesThese elements are very underused in KDE 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 is 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 KDE 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
glossentryalways contains one<glossterm>. It also contains one<glossdef>, or one<glosssee>, or a<glossdef>and a<glossseealso>.Tip
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-, whereword"wordis 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 KDE Documents, it should not take you long to pick up how to do a
glossary.
Example A.14. How to markup a glossary
Say you have in the text of the document the following sentence:
Words is a graphical, wysiwyg word processor, and is part of Calligra.
You want to have the words Words and calligra in the index, and Words, wysiwyg, “word processor” and Calligra 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">Words</glossterm>
<indexterm><primary>Words</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">Calligra</glossterm>.
<indexterm><primary>Calligra</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 is own <glossary>
section. The syntax inside <glossary>
and <glosslist> are otherwise the
same.
<glosslist>
<glossentry id="gloss-kword">
<glossterm>Words</glossterm>
<glossdef><para>The name of the KDE word
processor</para></glossdef>
</glossentry>
<glossentry id="gloss-koffice">
<glossterm>Calligra</glossterm>
<glossdef><para>A collection of office productivity tools, designed
by and for <acronym>KDE</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:
Words is a graphical WYSIWYG word processor, and is part of Calligra..
- Words
The name of the KDE word processor
- Calligra
A collection of office productivity tools, designed by and for KDE, including presentation software, a word processor, a spreadsheet, a PIM, and a vector illustration application.
- word processor
An application for handling text, typically more concerned with formatting visually than a plain text editor.
- WYSIWYG
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.
For KDE Documentation, indexes will in the future be generated
automatically, so many of these elements are not to be used directly
when authoring. At this stage, indexes are not generated, but if you
want to you can mark up words that should be indexed with the <indexterm> element, to save work for later.
<indexterm>Use this to note places in the main text of the document that should have an entry in the index. Do not over use it - not every single occurrence of a word needs to be noted in the index, but every occurrence where that term is significant should be.
indextermshould contain a<primary>, which contains the text that the entry will appear under in the index.Place the
indextermdirectly before the word you want to index, and place the word itself inside the primary element. If the word should also be listed under a secondary heading, place that term inside a secondary element.Example A.15. Index
Say the document contains the following sentence:
Words is a graphical, wysiwyg word processor, and is part of Calligra.
You want Words to have an index entry of it is own, and to also be noted under Calligra in the index.
<para><application>Words</application> <indexterm><primary>Words</primary><secondary>Calligra</secondary></indexterm> is a graphical, <acronym>WYSIWYG</acronym> word processor, and is part of Calligra.</para>The fact that an index entry exists is not normally indicated by a change in appearance.
If you think it should also be added under a third heading in the index, you can use tertiary to indicate this. Most terms you would find in KDE Documentation will only need a primary index heading, so use the others sparingly, if at all.
<tertiary>tertiary
<seealso>seealso
The following elements are used to create the actual index, but they are automatically generated, if required. You should not use them when authoring documents.
<firstterm>Mark up the first occurence of a technically significant term with this element. If you are creating a glossary or an index, the first occurence of a term will probably also warrant being an entry in one or both.
<refsynopsisdivinfo>refsynopsisdivinfo
<refnamediv>refnamediv
<refclass>refclass
<refmeta>refmeta
<refsect1>,<refsect2>and<refsect3>refsect1, refsect2 and refsect3
<refmiscinfo>refmiscinfo
<refsect1info>,<refsect2info>and<refsect3info>refsect1info, refsect2info and refsect3info
<refdescriptor>refdescriptor
<setindex>Not Used in KDE Documentation
<refpurpose>refpurpose
<reference>reference
<refentrytitle>refentrytitle
<refname>refname
<refentry>refentry
<refsynopsisdiv>refsynpsisdiv