DOC: Explain units

src/doc/cfood.rst

@@ -27,17 +27,17 @@ A single document with a converter tree specification:
 
 .. _example_1:
 .. code-block:: yaml
-                
+
    extroot:
      type: Directory
      match: ^extroot$
      subtree:
        DataAnalysis:
-         type: Directory
-         match: DataAnalysis
-         # (...)
+	 type: Directory
+	 match: DataAnalysis
+	 # (...)
+
 
-         
 A single document with a converter tree specification, but also including a custom converters section:
 
 .. _example_2:
@@ -50,15 +50,15 @@ A single document with a converter tree specification, but also including a cust
      CustomConverter_2:
        package: mypackage.converters
        converter: CustomConverter2
-                
+
    extroot:
      type: Directory
      match: ^extroot$
      subtree:
        DataAnalysis:
-         type: Directory
-         match: DataAnalysis
-         # (...)
+	 type: Directory
+	 match: DataAnalysis
+	 # (...)
 
 
 
@@ -78,11 +78,11 @@ two custom converters in the second document (**not recommended**, see the recom
      - !defmacro
        name: SimulationDatasetFile
        params:
-         match: null
-         recordtype: null
-         nodename: null
+	 match: null
+	 recordtype: null
+	 nodename: null
        definition:
-         # (...)
+	 # (...)
    ---
    Converters:
      CustomConverter_1:
@@ -91,15 +91,15 @@ two custom converters in the second document (**not recommended**, see the recom
      CustomConverter_2:
        package: mypackage.converters
        converter: CustomConverter2
-                
+
    extroot:
      type: Directory
      match: ^extroot$
      subtree:
        DataAnalysis:
-         type: Directory
-         match: DataAnalysis
-         # (...)
+	 type: Directory
+	 match: DataAnalysis
+	 # (...)
 
 
 
@@ -118,27 +118,27 @@ The **recommended way** of defining metadata, custom converters, macros and the
      - !defmacro
        name: SimulationDatasetFile
        params:
-         match: null
-         recordtype: null
-         nodename: null
+	 match: null
+	 recordtype: null
+	 nodename: null
        definition:
-         # (...)
+	 # (...)
      Converters:
        CustomConverter_1:
-         package: mypackage.converters
-         converter: CustomConverter1
+	 package: mypackage.converters
+	 converter: CustomConverter1
        CustomConverter_2:
-         package: mypackage.converters
-         converter: CustomConverter2
+	 package: mypackage.converters
+	 converter: CustomConverter2
    ---
    extroot:
      type: Directory
      match: ^extroot$
      subtree:
        DataAnalysis:
-         type: Directory
-         match: DataAnalysis
-         # (...)
+	 type: Directory
+	 match: DataAnalysis
+	 # (...)
 
 
 List Mode
@@ -148,11 +148,33 @@ Specifying values of properties can make use of two special characters, in order
 create lists or multi properties instead of single values:
 
 .. code-block:: yaml
-                
-        Experiment1:
-            Measurement: +Measurement #  Element in List (list is cleared before run)
-                         *Measurement #  Multi Property (properties are removed before run)
-                         Measurement  #  Overwrite
+
+	Experiment1:
+	    Measurement: +Measurement #  Element in List (list is cleared before run)
+			 *Measurement #  Multi Property (properties are removed before run)
+			 Measurement  #  Overwrite
+
+Values and units
+----------------
+
+Units of numeric values can be set by providing a property value not
+as a single string, but as a dictionary with a ``value`` and a
+``unit`` key. Within a converter definition this could look the
+following.
+
+.. code-block:: yaml
+
+   ValueWithUnitElt:
+     type: TextElement
+     match_name: ^my_prop$
+     match_value: "^(?P<number>\d+\.?\d*)\s+(?P<unit>.+)"  # Extract value and unit from a string which
+							   # has a number followed by at least one whitespace
+							   # character followed by a unit.
+     records:
+       MyRecord:
+	 MyProp:
+	   value: $number
+	   unit: $unit
 
 
 File Entities
@@ -160,7 +182,7 @@ File Entities
 
 In order to use File Entities, you must set the appropriate ``role: File``.
 Additionally, the path and file keys have to be given, with values that set the
-paths remotely and locally, respectively. You can use the variable 
+paths remotely and locally, respectively. You can use the variable
 ``<converter name>_path`` that is automatically created by converters that deal
 with file system related StructureElements. The file object itsself is stored
 in a vairable with the same name (as it is the case for other Records).
@@ -169,15 +191,15 @@ in a vairable with the same name (as it is the case for other Records).
 .. code-block:: yaml
 
       somefile:
-        type: SimpleFile
-        match: ^params.*$  # macht any file that starts with "params"
-        records:
-          fileEntity:
-            role: File           # necessary to create a File Entity
-            path: somefile.path  # defines the path in CaosDB
-            file: somefile.path  # path where the file is found locally
-          SomeRecord:
-            ParameterFile: $fileEntity  # creates a reference to the file
+	type: SimpleFile
+	match: ^params.*$  # macht any file that starts with "params"
+	records:
+	  fileEntity:
+	    role: File           # necessary to create a File Entity
+	    path: somefile.path  # defines the path in CaosDB
+	    file: somefile.path  # path where the file is found locally
+	  SomeRecord:
+	    ParameterFile: $fileEntity  # creates a reference to the file
 
 
 Transform Functions