--- a/configmix/config.py	Sat Mar 24 22:09:44 2018 +0100
+++ b/configmix/config.py	Sun Mar 25 16:45:15 2018 +0200
@@ -55,10 +55,11 @@
     """
 
     def getvar(self, varname, default=_MARKER):
-        """Get a variable of the form ``[[ns1.]ns2.]name`` - including
+        """Get a variable of the form ``[ns:][[key1.]key2.]name`` - including
         variables from other namespaces.
 
         No variable expansion is done and no filters are applied.
+
         """
         varns, varname = self._split_ns(varname)
         try:
@@ -78,7 +79,12 @@
     def getvar_s(self, varname, default=_MARKER):
         """Get a variable - including variables from other namespaces.
 
-        Variables will be substituted recursively in the result.
+        `varname` is interpreted as in :meth:`.getvar`. But variables
+        will be expanded recursively within the variable values and
+        filters are applied.
+
+        For more details see chapter :ref:`variable-expansion`.
+
         """
         try:
             obj = self.getvar(varname)

--- a/doc/introduction.rst	Sat Mar 24 22:09:44 2018 +0100
+++ b/doc/introduction.rst	Sun Mar 25 16:45:15 2018 +0200
@@ -11,12 +11,6 @@
 - :ref:`INI files <ini-files>`
 - :ref:`executable Python scripts <executable-python-scripts>`
 
-.. todo:: Describe evaluation syntax
-
-.. todo:: Describe available filter functions (and syntax)
-
-.. todo:: Describe late evaluation of interpolation strings
-
 
 .. _yaml-files:
 
@@ -69,9 +63,6 @@
 .. note:: Contrary to the behaviour of the standard Python :mod:`configparser`
           module the INI file reader is *case-sensitive*.
 
-.. todo:: Document the build of tree-ish configuration settings out of
-          INI files.
-
 The example INI style configuration below yields an equivalent
 configuration to the YAML configuration above:
 
@@ -149,3 +140,126 @@
 
   ``.ini``
     for INI configuration files
+
+
+.. _variable-expansion:
+
+Variable Names and Expansion
+----------------------------
+
+Variables are fetched with the API method :py:meth:`.Configuration.getvar`
+or :py:meth:`.Configuration.getvar_s`.
+
+Variable tree levels are separated with a point ``.`` when trying to
+fetch them.
+
+Looking at the example in chapter :ref:`yaml-files` -- when calling
+``myconfig.getvar_s("tree1.tree2.key4")`` you will get the value
+``get this as `tree1.tree2.key4'``.
+
+Additionally -- configuration variable values that are read with
+:py:meth:`.Configuration.getvar_s` are subject to
+variable expansion. The general syntactic pattern for this is::
+
+    {{[namespace:]variable[|filter[|filter...]]}}
+
+I.e.: between double curly braces an optional `namespace` name followed by
+a colon ``:``, the `variable` and then zero or more filters, each one
+introduced by a pipe symbol ``|``.
+
+Variables are expanded at request at runtime -- exactly when calling
+:py:meth:`.Configuration.getvar_s`.
+
+
+Variable Namespaces
+~~~~~~~~~~~~~~~~~~~
+
+There are 4 namespaces currently:
+
+1. The unnamed namespace (which is also default).
+
+   All the configuration variables are part of this namespace.
+
+2. The namespace ``OS``
+
+   Available functions:
+
+     ``cwd``
+         Contains the current working directory of the process
+
+3. The namespace ``ENV``
+
+   This namespace contains all the environment variables as they are
+   available from :py:data:`os.environ`.
+
+4. The namespace ``PY``
+
+   Contains selected values from the running Python:
+
+     ``version``
+         The return value of :py:func:`platform.python_version`
+
+     ``version_maj_min``
+         Just the major and minor version of the running Python
+         (``.`` separated)
+
+     ``version_maj``
+         Just the major version of the running Python
+
+     ``implementation``
+         The return value of :py:func:`platform.python_implementation`
+
+
+Filter functions
+~~~~~~~~~~~~~~~~
+
+Interpolated values can be processed through a series of filter functions::
+
+    {{my.variable|filter1|filter2}}
+
+Available filter functions are:
+
+  ``urlquote``
+
+  ``saslprep``
+
+  ``normpath``
+
+  ``abspath``
+
+  ``posixpath``
+
+  ``lower``
+
+  ``upper``
+
+
+Examples
+~~~~~~~~
+
+::
+
+    {{OS:cwd|posixpath}}
+
+yields the current working directory as POSIX path: on Windows all backslashes
+are replaced by forward slashes.
+
+::
+
+    {{ENV:PATH}}
+
+gives the current search path from the process environment.
+
+
+::
+
+    {{PY:version}}
+
+returns the current running Python version (e.g. ``3.6.4``).
+
+::
+
+    {{PY::implementation|upper}}
+
+yields something like ``CPYTHON`` when using the standard Python interpreter
+written in C.