Merge pull request #16 from mikapfl/doc-fixes

Documentation fixes

docs/data_format_details.rst

@@ -14,18 +14,18 @@ For all dimensions, defined names have to be used and additional metadata about
 dimensions is stored in the datasets ``attrs``.
 The dimensions are:
 
-===============  =====================  ========  ========================================================  ===================================
-dimension        dimension key          required  notes                                                     attrs
----------------  ---------------------  --------  --------------------------------------------------------  -----------------------------------
+===============  =====================  ========  ======================================  =======================================
+dimension        dimension key          required  notes                                   attrs
+---------------  ---------------------  --------  --------------------------------------  ---------------------------------------
 time             time                   ✗         for periods, the *start* of the period
-area             area (<category-set>)  ✗         must be a pre-defined category set                        'area': 'area (<category set>)'
-category         category (<c-set>)               primary category                                          'cat': 'category (<c-set>)'
-sec. categories  <type> (<c-set>)                 there can be multiple                                     'sec_cats': ['<type> (<c-set>)', …]
-scenario         scenario (<c-set>)                                                                         'scen': 'scenario (<c-set>)'
-provenance       provenance                       values are ``measured``, ``projected``, and ``derived``
+area             area (<category-set>)  ✗         must be a pre-defined category set      ``'area': 'area (<category set>)'``
+category         category (<c-set>)               primary category                        ``'cat': 'category (<c-set>)'``
+sec. categories  <type> (<c-set>)                 there can be multiple                   ``'sec_cats': ['<type> (<c-set>)', …]``
+scenario         scenario (<c-set>)                                                       ``'scen': 'scenario (<c-set>)'``
+provenance       provenance                       values from fixed set
 model            model                            model should be from a predefined list
 source           source                 ✗         a short source identifier
-===============  =====================  ========  ========================================================  ===================================
+===============  =====================  ========  ======================================  =======================================
 
 For some dimensions, the meaning of the data is directly visible from the data type
 (``time`` uses an xarray datetime data type) or the values come from a pre-defined list
@@ -51,6 +51,8 @@ category-set (for example, ``animal (FAOSTAT)``).
 Additional rules:
 
 * The size of the ``source`` dimension must be exactly 1.
+* The valid values for the ``provenance`` are ``measured``, ``projected``, and
+  ``derived``.
 
 Additional Coordinates
 ----------------------
@@ -99,17 +101,17 @@ The metadata about the dimensions is described above in the paragraph concerning
 dimensions.
 The other attributes with metadata about the dataset as a whole are:
 
-===========  ========================================  ============================================
+===========  ========================================  =========================================
 attribute    description                               data type
------------  ----------------------------------------  --------------------------------------------
-references   citable reference(s) describing the data  ``str`` starting with ``doi:`` or free-form
+-----------  ----------------------------------------  -----------------------------------------
+references   citable reference(s) describing the data  free-form ``str`` (ideally URL, e.g. DOI)
 rights       license or other usage restrictions       free-form ``str``
-contact      who can answer questions about the data   usually email address, but free-form ``str``
+contact      who can answer questions about the data   free-form ``str`` (usually email)
 title        a succinct description                    free-form ``str``
 comment      longer form description                   free-form ``str``
 institution  where the data originates                 free-form ``str``
 history      processing steps done on the data         ``str`` with specific rules (see text)
-===========  ========================================  ============================================
+===========  ========================================  =========================================
 
 All of these attributes are optional.
 If the ``references`` field starts with ``doi:``, it is a doi, otherwise it is a