These 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.
Use this inline to identify words in the text that are explained further in a
<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.)
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.
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.
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.
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.
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
wordis the term that is being explained.
Contains the actual definitions of the terms
You can use this to save duplicating entries in the glossary. Instead of a
<glossdef>you can put
<glosssee>with the id of another
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 shouldn't take you long to pick up how to do a
Example A.13. 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
section. The syntax inside
<glosslist> are otherwise the
<glosslist> <glossentry id="gloss-kword"> <glossterm>KWord</glossterm> <glossdef><para>The name of the KDE 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>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:
The name of the KDE word processor
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.
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.
Use this to note places in the main text of the document that should have an entry in the index. Don't 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.
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.14. Index
Say the document contains the following sentence:
KWord is a graphical, wysiwyg word processor, and is part of KOffice.
You want KWord to have an index entry of it's own, and to also be noted under KOffice in the index.
<para><application>KWord</application> <indexterm><primary>KWord</primary><secondary>KOffice</secondary></indexterm> is a graphical, <acronym>WYSIWYG</acronym> word processor, and is part of KOffice.</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.
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.
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.
refsect1, refsect2 and refsect3
refsect1info, refsect2info and refsect3info
Not Used in KDE Documentation