# 5. Glossary¶

Glossary and abbreviations are generated by sphinx_doc_glossary.py from the common source doc/glossary.src.

## 5.1. As for the style of glossary entries¶

Either use dictionary/encyclopedia style[DICTTERM]

term
a word or group of words designating something, especially in a particular field, as atom in physics, quietism in theology, adze in carpentry, or district leader in politics.

or section style (term assumes the role of a section title)

Term

Words, compound words or multi-word expressions[WPTERM]

[…] that in specific contexts are given specific meanings - these may deviate from the meanings the same words have in other contexts and in everyday language.

Do not mix styles.

Do not write a glossary entry as a single sentence:

This example
is very very bad. Never ever write like this.

Have a look at the google search glossary entries example.

## 5.2. Multiple glossary directives¶

It is possible to have multiple glossaries spread throughout a document. This is fine for hypermedia (HTML, PDF, EPUB). However, if the document is to be printed it is a very bad idea to have glossaries other than abbreviations and glossary, since a reader will not be able to locate them easily.

Both, the list of abbreviations, as well as the glossary are each defined with a glossary directive:

Source ReST markup Rendered output
Abbreviations
=============

.. glossary::

|abbrr|

first
see :term:f i r s t
and short :term:abbrr


Abbreviations

abbrr
first
see f i r s t and short abbrr
Glossary
========

.. glossary::

abbrr

some description

elaborate entry for |abbrr|

f i r s t
see :term:first


Glossary

abbrr

some description

elaborate entry for abbrr
f i r s t
see first
.. |abbrr| replace:: :term:abbrr <a black blade runner>


### 5.2.1. Order of abbreviations and glossary¶

In case of duplicate glossary terms in multiple glossaries, the last entry wins when resolving a reference to the term. Therefore, abbreviations should appear before the glossary. Here is an exact term reference abbrr (:term:abbrr) and an elaborate one abbrr (.. |abbrr| replace:: :term:tstaddr <a black blade runner>).

## 5.3. Combinations of glossary and abbreviation generation¶

Enable features with option –enable FLG,FLG,…:

gl[ossary]
option: glo_enabled generate glossary.inc
gt[erm]
option: glo_term_enabled add term+definition to glossary
ga[bbrev]
option: glo_abbr_enabled add abbr+term/definition to glossary
ab[brevs]
option: abbr_enabled generate abbrevs.inc
option: adef_enabled generate abbrev_defs.inc
f[glossary]
option: force_glossary force abbreviation only entries as :todo: glossary entries

figure 5.1

figure 5.1 Combinations of Glossary and Abbreviation Generation