DOC: Add more explanations to value definitions

src/doc/cfood.rst

@@ -157,6 +157,46 @@ create lists or multi properties instead of single values:
 Values and units
 ----------------
 
+Property values can be specified as a simple strings (as above) or as
+a dictionaries that may also specify the :ref:`collection mode <List
+Mode>`. Strings starting with a "$" will be replaced by a
+corresponding variable if there is any. See the :doc:`tutorials
+chapter<tutorials/index>` of this documentation for more elaborate
+examples on how the variable replacment works exactly. A simple
+example could look the following.
+
+.. code-block:: yaml
+
+   ValueElt:
+     type: TextElement
+     match_name: ^my_prop$
+     match_value: "(?P<value>.*)"  # Anything in here is stored in the variable "value"
+     records:
+       MyRecord:
+	 MyProp: $value  # will be replace by whatever is stored in the "value" variable set above.
+
+If not given explicitly, the collection mode will be determined from
+the first character of the property value as explained above, and the
+following three definitions are all equivalent:
+
+.. code-block:: yaml
+
+   MyProp: +$value
+
+.. code-block:: yaml
+
+   MyProp:
+     value: +$value
+
+and
+
+.. code-block:: yaml
+
+   MyProp:
+     value: $value
+     collection_mode: list
+
+
 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