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

@startuml /' o1 '/
skinparam padding 1
package "glo term enabled" as GLO_TERM_ENA_ABBR_ANY_OUTER <<Frame>> {
object "glossary.src" as GLO_SRC {
␣␣␣abbr <https://en.wikipedia.org/> | A Bold Blade Runner
␣␣␣␣␣Based on the normal blade runner
␣␣␣␣␣as seen on Google as <U+0060>NBR<U+0060>_.
␣␣␣␣␣.. _<U+0060>NBR<U+0060>: https://google.com
¶
␣␣␣Simple Entry <https://en.wikipedia.org/>
␣␣␣␣␣Simply the best
␣␣␣␣␣and brightest.
}
package "glossary" as GLO_TERM_ENA_ABBR_ANY_INNER <<Frame>> {
object "glossary.inc\nterm enabled, abbr disabled" as GLO_ENA_TERM_DIS_ABBR_GL {
.. glossary::
␣␣␣:sorted:
¶
␣␣␣A Bold Blade Runner
␣␣␣␣␣Based on the normal blade runner
␣␣␣␣␣as seen on Google as <U+0060>NBR<U+0060>_.
¶
␣␣␣Simple Entry
␣␣␣␣␣Simply the best
␣␣␣␣␣and brightest.
}
object "glossary.inc\nterm enabled, abbr enabled" as GLO_ENA_TERM_ENA_ABBR_GL {
.. glossary::
␣␣␣:sorted:
¶
␣␣␣abbr
␣␣␣␣␣see :term:<U+0060>A Bold Blade Runner<U+0060>
¶
␣␣␣A Bold Blade Runner
␣␣␣␣␣Based on the normal blade runner
␣␣␣␣␣as seen on Google as <U+0060>NBR<U+0060>_.
¶
␣␣␣Simple Entry
␣␣␣␣␣Simply the best
␣␣␣␣␣and brightest.
}
}
object "abbrevs.inc" as GLO_TERM_ENA_ABBR_ANY_AI {
.. glossary::
␣␣␣:sorted:
¶
␣␣␣abbr
␣␣␣␣␣:term:<U+0060>A Bold Blade Runner<U+0060>
}
object "abbrev_defs.inc" as GLO_TERM_ENA_ABBR_ANY_AD {
.. |abbr| replace:: :term:<U+0060>abbr <A Bold Blade Runner><U+0060>
.. _<U+0060>abbr<U+0060>: https://en.wikipedia.org/
.. _<U+0060>NBR<U+0060>: https://google.com
}
GLO_TERM_ENA_ABBR_ANY_AI ..> GLO_TERM_ENA_ABBR_ANY_AD : <<uses>>
GLO_TERM_ENA_ABBR_ANY_INNER ..> GLO_TERM_ENA_ABBR_ANY_AD : <<uses>>
GLO_SRC <|.. GLO_TERM_ENA_ABBR_ANY_INNER
GLO_SRC <|.. GLO_TERM_ENA_ABBR_ANY_AI
GLO_SRC <|.. GLO_TERM_ENA_ABBR_ANY_AD
}
@enduml

figure 5.2 Generated output files for glossary terms enabled

@startuml /' o2 '/
skinparam padding 1
package "glo term disabled" <<Frame>> {
hide empty
object "glossary.src" as GLO_SRC {
␣␣␣abbr <https://en.wikipedia.org/> | A Bold Blade Runner
␣␣␣␣␣Based on the normal blade runner
␣␣␣␣␣as seen on Google as <U+0060>NBR<U+0060>_.
␣␣␣␣␣.. _<U+0060>NBR<U+0060>: https://google.com
¶
␣␣␣Simple Entry <https://en.wikipedia.org/>
␣␣␣␣␣Simply the best
␣␣␣␣␣and brightest.
}
package "glo abbr enabled" as GLO_TERM_DIS_ABBR_ENA_PKG <<Frame>> {
object "glossary.inc" as GLO_TERM_DIS_ABBR_ENA_GL {
.. glossary::
␣␣␣:sorted:
¶
␣␣␣abbr
␣␣␣␣␣A Bold Blade Runner
¶
␣␣␣␣␣Based on the normal blade runner
␣␣␣␣␣as seen on Google as <U+0060>NBR<U+0060>_.
}
object "abbrevs.inc" as GLO_TERM_DIS_ABBR_ENA_AI {
.. glossary::
␣␣␣:sorted:
¶
␣␣␣|abbr|
␣␣␣␣␣A Bold Blade Runner
}
}
package "no glossary" as GLO_TERM_DIS_ABBR_DIS_PKG <<Frame>> {
object "abbrevs.inc" as GLO_TERM_DIS_ABBR_DIS_AI {
.. glossary::
␣␣␣:sorted:
¶
␣␣␣abbr
␣␣␣␣␣A Bold Blade Runner
}
}
object "abbrev_defs.inc" as GLO_TERM_DIS_ABBR_ANY_AD {
.. |abbr| replace:: :term:<U+0060>abbr<U+0060>
.. _<U+0060>abbr<U+0060>: https://en.wikipedia.org/
.. _<U+0060>NBR<U+0060>: https://google.com
}
GLO_TERM_DIS_ABBR_ENA_PKG ..> GLO_TERM_DIS_ABBR_ANY_AD : <<uses>>
GLO_TERM_DIS_ABBR_DIS_PKG ..> GLO_TERM_DIS_ABBR_ANY_AD : <<uses>>
GLO_SRC <|.. GLO_TERM_DIS_ABBR_ENA_PKG
GLO_SRC <|.. GLO_TERM_DIS_ABBR_DIS_PKG
GLO_SRC <|.. GLO_TERM_DIS_ABBR_ANY_AD
}
@enduml

figure 5.3 Generated output files for glossary terms disabled

5.3.2. Class diagram

@startuml /' c0 '/
skinparam padding 1
class Glossary {
                 glo_enabled
                 glo_term_enabled
                 glo_abbr_enabled
                 abbr_enabled
                 adef_enabled
                 force_glossary
                 suffix
                 glo_header
                 glo_preamble
                 glo_entry_indent
                 glo_def_indent
                 glo_footer
                 abbr_header
                 abbr_preamble
                 abbr_entry_indent
                 abbr_def_indent
                 abbr_footer
                 source
                 glossary
                 abbrevs
                 abbrev_defs
    enable(self, flags)
    preamble(self, preamble)
    process_definition(self, combined_term, combined_definition)
    parse_definitions(self, line_iterator, glo_is_marked=None, ctx=None)
    dump_defs(self, definitions, indent, preamble, header, footer, out=None)
    dump(self, abbr_out=None, glo_out=None, adef_out=None, doc_dir=None)
}
@enduml

figure 5.4 Glossary class

5.3.3. Activity diagrams

@startuml /' a0 '/
skinparam padding 1
    partition "sphinx_doc_glossary" {
    start
    :setup;
    while (for each file argument) is (do)
        :parse definitions|
    endwhile ( )
    :dump definitions|
    stop
    } /' move before //stop//, if there are subsections '/
@enduml

figure 5.5 Glossary parser activity diagram

@startuml /' a1 '/
skinparam padding 1
        partition "parse glossary definitions" {
        start
        floating note right
        parse term/definition block:

        [ abbreviation [ <abbrev link> ] | ] term [ <term link> ]
        ␣␣␣␣definition line
        ␣␣␣␣definition line
        ␣␣␣␣.. |subst| replace:: **subst**
        ␣␣␣␣.. _//link//: http://some.where.com

        Blank lines between term and
        first non-empty line of
        definition are ignored.

        link and subst definitions are
        diverted to //abbrev_defs.inc//
        end note
        while (for each line) is (do)
            if (section active?) then (yes)
                if (section_rx matches?) then (yes)
                    :record section in glossary
                    leave state IN_SECTION;
                else
                    :collect section line;
                endif
                :next line>
            else
                if (any section marker matches?) then (yes)
                        :intialize section context
                        enter state IN_SECTION;
                    :next line>
                endif
            endif
            if (definition active?) then (yes)
                if (line is not blank?) then (yes)
                    if (defintion is empty?) then (yes)
                        :use current indent
                        as definition indent;
                    endif
                    if (current indent < definition indent or\ncurrent indent == term indent?) then (yes)
                        :remove trailing blank
                        lines from definition;
                        :record term and definition
                        in glossary;
                        :leave state IN_DEFINITION;
                    endif
                endif
                if (definition still active?) then (yes)
                    if (line is not empty or\ndefinition is not empty?) then (yes)
                        :add line without definition indent
                        to definition;
                        :next line>
                    endif
                endif
            endif
            if (definition is inactive?) then (yes)
                if (PARSE_RX matches?) then (yes)
                    :record indent in context
                    record abbrev/term in context
                    enter state IN_DEFINITION;
                    :next line>
                endif
            endif
        endwhile ( )
        :record pending section in glossary;
        :add pending definition to glossary;
        stop
        }
@enduml

figure 5.6 Activity diagram for parsing a file

5.3.4. State diagram

@startuml /' s0 '/
skinparam padding 1
        [*] --> GLO_OUT
                GLO_IN --> GLO_OUT : line matches\nGLO_MARKER_RX
                GLO_IN --> [*] : EOF
                State "Outside glossary definition" as GLO_OUT {
                State "reading lines" as READ_LINE {
                note as RL_N1
                {{
                start
                while (next line not EOF?) is (do)
                if (line matches GLO_MARKER_RX?) then (yes)
                break
                endif
                endwhile
                stop
                }}
                end note
                }
                }
                GLO_OUT --> GLO_IN : line matches\nGLO_MARKER_RX
                GLO_OUT --> [*] : EOF
            State "Inside glossary definition" as GLO_IN {
            State "| reading lines |" as READ_LINE_2 {
            }
            }
@enduml

figure 5.7 Glossary parser state diagram