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

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
ad[efs]
option: adef_enabled generate abbrev_defs.inc
f[glossary]
option: force_glossary force abbreviation only entries as :todo: glossary entries

figure 5.1

digraph glossary { rankdir=LR; // (progn (forward-symbol-tag) (symbol-tag-region nil nil nil 'activate) (delete-region (region-beginning) (region-end)) (shell-command "x1.sh sphinx_doc_glossary-001.csv" t)) legend [shape=plaintext,label=< <!-- |:here:| --> <table border="0" cellborder="1" cellspacing="0"> <tr><td valign="top" align="left" bgcolor="#cccccc">Column<br align="left" /></td><td valign="top" align="left" bgcolor="#cccccc">Description<br align="left" /></td></tr> <tr><td valign="top" align="left">Dflt<br align="left" /></td><td valign="top" align="left">* = default setting for sphinx_doc_glossary.py</td></tr> <tr><td valign="top" align="left">Glo Term?<br align="left" /></td><td valign="top" align="left">+ =&gt; glossary contains expanded term entry<br align="left" />- =&gt; glossary does not contain expanded term entry<br align="left" /></td></tr> <tr><td valign="top" align="left">Glo Abbr?<br align="left" /></td><td valign="top" align="left">+ =&gt; glossary contains abbreviation entry<br align="left" />- =&gt; glossary does not contains abbreviation entry<br align="left" /></td></tr> <tr><td valign="top" align="left">Glossary Entries<br align="left" /></td><td valign="top" align="left">Entries generated for glossary<br align="left" /></td></tr> <tr><td valign="top" align="left">Abbreviation Entry<br align="left" /></td><td valign="top" align="left">Entry generated for list of abbreviations<br align="left" /></td></tr> <tr><td valign="top" align="left">Abbreviation Subst<br align="left" /></td><td valign="top" align="left">Subst definition for abbreviation<br align="left" /></td></tr> </table> <!-- |:here:| --> >] // (progn (forward-symbol-tag) (symbol-tag-region nil nil nil 'activate) (delete-region (region-beginning) (region-end)) (shell-command "x1.sh sphinx_doc_glossary-000.csv" t)) combinations [shape=plaintext,label=< <!-- |:here:| --> <table border="0" cellborder="1" cellspacing="0"> <tr><td valign="top" align="left" bgcolor="#cccccc">Dflt</td><td valign="top" align="left" bgcolor="#cccccc">Glo Term?<br align="left" /></td><td valign="top" align="left" bgcolor="#cccccc">Glo Abbr?<br align="left" /></td><td valign="top" align="left" bgcolor="#cccccc">Glossary Entries<br align="left" /></td><td valign="top" align="left" bgcolor="#cccccc">Abbreviation Entry<br align="left" /></td><td valign="top" align="left" bgcolor="#cccccc">Abbreviation Subst<br align="left" /></td></tr> <tr><td valign="top" align="left"> </td><td valign="top" align="left">+<br align="left" /></td><td valign="top" align="left">+<br align="left" /></td><td valign="top" align="left">abbrr<br align="left" /> see :term:`a black blade runner`<br align="left" /><br align="left" />a black blade runner<br align="left" /> some description<br align="left" /></td><td valign="top" align="left">abbrr<br align="left" /> :term:`a black blade runner`<br align="left" /></td><td valign="top" align="left">.. |abbrr| replace:: :term:`abbrr &lt;a black blade runner&gt;`<br align="left" /></td></tr> <tr><td valign="top" align="left">*</td><td valign="top" align="left">+<br align="left" /></td><td valign="top" align="left">-<br align="left" /></td><td valign="top" align="left">a black blade runner<br align="left" /> some description<br align="left" /></td><td valign="top" align="left">abbrr<br align="left" /> :term:`a black blade runner`<br align="left" /></td><td valign="top" align="left">.. |abbrr| replace:: :term:`abbrr &lt;a black blade runner&gt;`<br align="left" /></td></tr> <tr><td valign="top" align="left"> </td><td valign="top" align="left">-<br align="left" /></td><td valign="top" align="left">+<br align="left" /></td><td valign="top" align="left">abbrr<br align="left" /> a black blade runner<br align="left" /><br align="left" /> Some description<br align="left" /></td><td valign="top" align="left">|abbrr|<br align="left" /> a black blade runner<br align="left" /></td><td valign="top" align="left">.. |abbrr| replace:: :term:`abbrr`<br align="left" /></td></tr> <tr><td valign="top" align="left"> </td><td valign="top" align="left">-<br align="left" /></td><td valign="top" align="left">-<br align="left" /></td><td valign="top" align="left"><br align="left" /></td><td valign="top" align="left">abbrr<br align="left" /> a black blade runner<br align="left" /></td><td valign="top" align="left">.. |abbrr| replace:: :term:`abbrr`<br align="left" /></td></tr> </table> <!-- |:here:| --> >] }

figure 5.1 Combinations of Glossary and Abbreviation Generation

5.3.1. Object diagrams

figure 5.2 Generated output files for glossary terms enabled

figure 5.3 Generated output files for glossary terms disabled

5.3.2. Class diagram

figure 5.4 Glossary class

5.3.3. Activity diagrams

figure 5.5 Glossary parser activity diagram

figure 5.6 Activity diagram for parsing a file

5.3.4. State diagram

figure 5.7 Glossary parser state diagram