--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/introduction.rst	Sun Mar 18 16:45:51 2018 +0100
@@ -0,0 +1,92 @@
+.. -*- coding: utf-8; indent-tabs-mode: nil; -*-
+
+.. _introduction:
+
+Introduction
+============
+
+The configurations can be read from different types of files:
+
+- :ref:`YAML files <yaml-files>`
+- :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:
+
+YAML Files
+----------
+
+Need the :mod:`yaml` package (e.g. ``pip install pyyaml``)
+
+.. note:: All strings are returned as Unicode text strings.
+
+
+.. _ini-files:
+
+INI Files
+---------
+
+Read the file and all sections named in parameter `extract` are flattened
+into the resulting dictionary. By default the section named ``config`` is
+used.
+
+Normally all values are returned as Unicode text strings.
+But values can be annotated and therefore interpreted as other types:
+
+  ``:int:``
+      The value is handled in the same way as a Python :class:`int`
+      literal
+
+  ``:float:``
+      The value is interpreted as :class:`float`
+
+  ``:bool:``
+      The resulting value is a :class:`bool` where
+
+        ``1``, ``true``, ``yes``, ``on``
+           yield a Python ``True``
+
+        ``0``, ``false``, ``no``, ``off``
+           yield a Python ``False``
+
+      The evaluation is done *case-insensitively*.
+
+.. note:: All strings are returned as Unicode text strings.
+
+.. note:: Contrary to the behaviour of the standard Python :mod:`configparser`
+          module the INI file reader is *case-sensitive*.
+
+.. todo:: Implement tree-ish interpretation of INI files
+
+   Currently there is no tree.
+
+
+.. _executable-python-scripts:
+
+Executable Python Scripts
+-------------------------
+
+What will be exported:
+
+1. If loading is done with the `extract` parameter only the given keys are
+   extracted from the script.
+
+2. Otherwise it is checked if the scripts defines an ``__all__``
+   sequence. If there is one it's contents are the keys to be
+   extracted.
+
+3. If there is no ``__all__`` object all names not starting with an
+   underscore ``_`` are found.
+
+This is analogous to as Python modules behave when importing them with
+``from module import *``.
+
+.. note:: The Python configuration files are evaluated with ``exec`` and not
+          imported.