.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2019, Wolfgang Scherer, .. .. This file is part of Documentation Standard. .. .. Permission is granted to copy, distribute and/or modify this document .. under the terms of the GNU Free Documentation License, Version 1.3 .. or any later version published by the Free Software Foundation; .. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .. A copy of the license is included in the section entitled "GNU .. Free Documentation License". .. inline comments (with du_comment_role) .. role:: rem(comment) .. role:: html(raw) :format: html .. role:: shx(code) :language: sh .. rst-class:: xnarrow xmedium large xhuge xultra ################################################## :rem:`|||:sec:|||`\ Glossary ################################################## .. >>CODD See `the components of a doctoral dissertation and their order `_ .. >>CODD Dedication .. >>CODD Epigraph .. >>CODD Abstract .. compound:: Glossary and abbreviations are generated by :program:`sphinx_doc_glossary.py` from the common source :file:`doc/glossary.src`. .. \|:here:| .. >>CODD Introduction ======================================================================== :rem:`|||:sec:|||`\ 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`_. .. _`glossary entries example`: https://www.google.com/search?q=glossary+entries+example ======================================================================== :rem:`|||:sec:|||`\ 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 | +==============================================================+=======================================+ | .. code-block:: rest | | | | | | Abbreviations | .. rubric:: Abbreviations | | ============= | | | | | | .. glossary:: | .. glossary:: | | | | | |abbrr| | |abbrr| | | a black blade runner | a black blade runner | | | | | first | first | | see :term:`f i r s t` | see :term:`f i r s t` | | and short :term:`abbrr` | and short :term:`abbrr` | +--------------------------------------------------------------+---------------------------------------+ | .. code-block:: rest | | | | | | Glossary | .. rubric:: Glossary | | ======== | | | | | | .. glossary:: | .. glossary:: | | | | | abbrr | abbrr | | a black blade runner | a black blade runner | | | | | some description | some description | | | | | a black blade runner | a black blade runner | | elaborate entry for |abbrr| | elaborate entry for |abbrr| | | | | | f i r s t | f i r s t | | see :term:`first` | see :term:`first` | +--------------------------------------------------------------+---------------------------------------+ | .. code-block:: rest | | | | | | .. |abbrr| replace:: :term:`abbrr ` | | +--------------------------------------------------------------+---------------------------------------+ .. |abbrr| replace:: :term:`abbrr ` ----------------------------------------------------- :rem:`||:sec:||`\ 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 :term:`abbrr` (``:term:`abbrr```) and an elaborate one |abbrr| (``.. |abbrr| replace:: :term:`tstaddr ```). ======================================================================== :rem:`|||:sec:|||`\ Combinations of glossary and abbreviation generation ======================================================================== .. (progn (forward-line 1) (shell-command "xlsx-dump.sh --rest sphinx_doc_glossary.csv | sed 's,| [.],| |,g'" t) (insert "\n")) Enable features with option `--enable FLG,FLG,...`: gl[ossary] option: `glo_enabled` generate :file:`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 :file:`abbrevs.inc` ad[efs] option: `adef_enabled` generate :file:`abbrev_defs.inc` f[glossary] option: `force_glossary` force abbreviation only entries as :todo: glossary entries :numref:`fig:combinations of glossary and abbreviation generation` .. _`fig:combinations of glossary and abbreviation generation`: .. graphviz:: :caption: Combinations of Glossary and Abbreviation Generation 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=<
Column
Description
Dflt
* = default setting for sphinx_doc_glossary.py
Glo Term?
+ => glossary contains expanded term entry
- => glossary does not contain expanded term entry
Glo Abbr?
+ => glossary contains abbreviation entry
- => glossary does not contains abbreviation entry
Glossary Entries
Entries generated for glossary
Abbreviation Entry
Entry generated for list of abbreviations
Abbreviation Subst
Subst definition for abbreviation
>] // (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=<
DfltGlo Term?
Glo Abbr?
Glossary Entries
Abbreviation Entry
Abbreviation Subst
+
+
abbrr
see :term:`a black blade runner`

a black blade runner
some description
abbrr
:term:`a black blade runner`
.. |abbrr| replace:: :term:`abbrr <a black blade runner>`
*+
-
a black blade runner
some description
abbrr
:term:`a black blade runner`
.. |abbrr| replace:: :term:`abbrr <a black blade runner>`
-
+
abbrr
a black blade runner

Some description
|abbrr|
a black blade runner
.. |abbrr| replace:: :term:`abbrr`
-
-

abbrr
a black blade runner
.. |abbrr| replace:: :term:`abbrr`
>] } -------------------------------------------------- :rem:`||:sec:||`\ Object diagrams -------------------------------------------------- .. _`fig:Generated output files for glossary terms enabled`: .. uml:: _static/sphinx_doc_glossary-o1.puml :caption: Generated output files for glossary terms enabled :scale: 50% .. _`fig:Generated output files for glossary terms disabled`: .. uml:: _static/sphinx_doc_glossary-o2.puml :caption: Generated output files for glossary terms disabled :scale: 50% -------------------------------------------------- :rem:`||:sec:||`\ Class diagram -------------------------------------------------- .. _`fig:Glossary class`: .. uml:: _static/sphinx_doc_glossary-c0.puml :caption: Glossary class :scale: 50% -------------------------------------------------- :rem:`||:sec:||`\ Activity diagrams -------------------------------------------------- .. _`fig:Glossary parser activity diagram`: .. uml:: _static/sphinx_doc_glossary-a0.puml :caption: Glossary parser activity diagram :scale: 50% .. _`fig:Activity diagram for parsing a file`: .. uml:: _static/sphinx_doc_glossary-a1.puml :caption: Activity diagram for parsing a file :scale: 50% -------------------------------------------------- :rem:`||:sec:||`\ State diagram -------------------------------------------------- .. _`fig:Glossary parser state diagram`: .. uml:: _static/sphinx_doc_glossary-s0.puml :caption: Glossary parser state diagram :scale: 50% .. >>CODD Chapter .. >>CODD Conclusion .. >>CODD Appendix A .. \|:here:| .. >>CODD Notes .. ================================================== .. :rem:`|||:sec:|||`\ Footnotes .. ================================================== :html:`
` .. \[#] .. include:: doc_defs.inc .. include:: doc_defs_combined.inc .. include:: abbrev_defs.inc .. .. \||<-snap->|| doc_standalone .. include:: doc/doc_defs_secret.inc .. \||<-snap->|| doc_standalone .. \||<-snap->|| not_doc_standalone .. include:: doc_defs_secret.inc .. \||<-snap->|| not_doc_standalone .. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de