Difference between revisions of "Documentation Primer/Manual/DocBook Reference/Reference"

Latest revision as of 11:48, 9 September 2012

Other languages:

English

[edit] References, indexes, and glossaries

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.

[edit] Making a glossary

<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 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 glossentry always 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-word", where 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 KDE Documents, it shouldn't take you long to pick up how to do a glossary.

Example: 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 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:

KWord is a graphical WYSIWYG word processor, and is part of KOffice.

KWord

The name of the KDE word processor

KOffice

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.

[edit] Making an Index

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. 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.

indexterm should contain a <primary>, which contains the text that the entry will appear under in the index.

Place the indexterm directly 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: 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.

<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.

• <index>

• <indexdiv>

• <indexentry>

• <primaryie>

• <secondaryie>

• <see>

• <seealsoie>

• <seeie>

• <tertiaryie>

[edit] Other Reference Sections

<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

• ← Making Callouts
• ↑ Back to Menu ↑
• Tags we do not use →