--- a/doc/introduction.rst	Thu Mar 29 08:53:35 2018 +0200
+++ b/doc/introduction.rst	Thu Mar 29 08:58:34 2018 +0200
@@ -142,39 +142,43 @@
     for INI configuration files
 
 
-.. _variable-expansion:
+.. _getting-values:
 
-Variable Names and Expansion
-----------------------------
+Getting configuration variables
+-------------------------------
+
+Get a -- possibly expanded -- configuration variable's value with::
 
-Variables are fetched with the API method :py:meth:`.Configuration.getvar`
-or :py:meth:`.Configuration.getvar_s`.
+    value1 = config.getvar_s("key1")
+
+Get a raw configuration variable's value with::
 
-Variable tree levels are separated with a point ``.`` when trying to
-fetch them.
+    value1_raw = config.getvar("key1")
+
+Because the configuration is not only a plain list of but a tree of
+key-value pairs you will want to fetch them by separating the individual
+level keys with a point ``.``.
 
 Looking at the example in chapter :ref:`yaml-files` -- when calling
-``myconfig.getvar_s("tree1.tree2.key4")`` you will get the value
+``config.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
+This is true for both methods :py:meth:`.Configuration.getvar` and
 :py:meth:`.Configuration.getvar_s`.
 
+Both methods also perform :ref:`variable-expansion` and handle
+:ref:`variable-namespaces`. Filtering is not supported. So -- the
+variable name arguments of :py:meth:`.Configuration.getvar` and
+:py:meth:`.Configuration.getvar_s` are of the form
+``[namespace:]variable``.
+
+
+.. _variable-namespaces:
 
 Variable Namespaces
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
-There are 4 namespaces currently:
+Currently there are 4 namespaces:
 
 1. The unnamed namespace (which is also default).
 
@@ -210,6 +214,35 @@
          The return value of :py:func:`platform.python_implementation`
 
 
+Examples
+~~~~~~~~
+
+::
+
+     config.getvar("OS:cwd")
+
+yields the current working directory as :py:func:`os.getcwd` does.
+
+
+.. _variable-expansion:
+
+Variable Expansion
+------------------
+
+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 lately at runtime -- exactly when calling
+:py:meth:`.Configuration.getvar_s` or :py:meth:`.Configuration.getvar`.
+
+
 Filter functions
 ~~~~~~~~~~~~~~~~
 
@@ -241,25 +274,24 @@
 
     {{OS:cwd|posixpath}}
 
-yields the current working directory as POSIX path: on Windows all backslashes
-are replaced by forward slashes.
+expands to 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.
-
+expands to the current search path from the process environment.
 
 ::
 
     {{PY:version}}
 
-returns the current running Python version (e.g. ``3.6.4``).
+expands to 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.
+expands to something like ``CPYTHON`` when using the standard Python
+interpreter written in C.