6.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.
6.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|
a black blade runner
first
see :term:`f i r s t`
and short :term:`abbrr`
|
Abbreviations
- abbrr
- a black blade runner
- first
- see f i r s t
and short abbrr
|
Glossary
========
.. glossary::
abbrr
a black blade runner
some description
a black blade runner
elaborate entry for |abbrr|
f i r s t
see :term:`first`
|
Glossary
- abbrr
a black blade runner
some description
- a black blade runner
- elaborate entry for abbrr
- f i r s t
- see first
|
.. |abbrr| replace:: :term:`abbrr <a black blade runner>`
|
|
6.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>`).
6.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
- ad[efs]
- option: adef_enabled generate
abbrev_defs.inc
- f[glossary]
- option: force_glossary force abbreviation only entries as
:todo: glossary entries
figure 6.1