Glossary updates and more term refs.

Expanded db glossary definition with list of supported physical db's.

added definition for hyperdb.

expanded definition of itemid to include that it is handled as a string
in some circumstances.

Author: rouilj

doc/glossary.txt

@@ -8,41 +8,53 @@ Roundup Glossary
 ================
 
 .. glossary::
+   :sorted:
 
    class
-      a definition of the properties and behaviour of a set of items
+      a definition of the properties and behavior of a set of items
 
    classname
       the name of a class. It must start with a letter, end with a letter
       or "_", and only have alphanumerics and "_" in the middle.
 
-   db (or hyperdb)
-      a collection of items
+   db
+      database used to store the data in the tracker. Roundup supports
+      4 databases: dbm (Berkeley DB/BDB), SQLite, PostgreSQL, MySQL/MariaDB.
 
    definitional class
-      a class that exists to define a descrete set of values. For example
+      a class that exists to define a discrete set of values. For example
       status or priority.
 
    designator
-      a combined class + itemid reference to any item in the
-      hyperdb. E.g. issue26. Note that form values can include
-      something that looks like a designator composed of a classname, a
-      dash '-', and a number. E.g. file-1. These
-      are used to create new instances of a class via the web interface.
+      a combined :term:`classname` + :term:`itemid` reference to any item
+      in the hyperdb. E.g. ``issue26``. Note that form values can include
+      something that looks like a designator composed of a classname,
+      a dash '-', and a number. E.g. ``file-1``. These are used to create
+      new instances of a class via the web interface.
 
-   itemid
-      a numeric reference to a particular item of one class
+   hyperdb
+      a software layer between the user and the underlying :term:`db`.
+      It is responsible for mutating the underlying db when the schema
+      changes. It also executes the detectors when items in the db change.
 
    item
       a collection of data that forms one entry in the hyperdb.
 
+   itemid
+      an integer reference to a particular item of one
+      class. Internally it is stored as a string and not an integer
+      number. This results in a string not numeric sort by id in some
+      circumstances.
+
    property
       one element of data that makes up an item. In Roundup, the set 
       of item properties may be changed as needed - even after the 
-      tracker has been initialised and used in production.
+      tracker has been initialized and used in production.
 
    schema
-      the definition of all the classes that make up an tracker
+      the definition of all the classes and properties that make up a
+      tracker. Contained in the file ``schema.py``. The permissions
+      for the schema items are usually defined in the same file.
 
    tracker
       the schema and hyperdb that forms one issue tracker

doc/reference.txt

@@ -1516,12 +1516,13 @@ Database Content
 
 .. note::
    If you modify the content of a :term:`definitional class`, you will
-   need to edit the tracker `detectors`_ if they reference a value
-   of a definitional class. (E.g. if a detector checks to see if an
-   issue has a status of "open", and you change the "open" definition
-   to be "working", you need to change the check.)
+   need to edit the tracker `detectors`_ if they reference a value of
+   a definitional class. (E.g. if a detector checks to see if an issue
+   has a status of "open", and you change the "open" definition to be
+   "working", you need to change the check.)
 
-Customisation of the special definitional classes (eg. status,
+Customisation of the special :term:`definitional classes <definitional
+class>` (eg. status,
 priority, resolution, ...) may be done either before or after the
 tracker is initialised. The actual method of doing so is completely
 different in each case though, so be careful to use the right one.