--- a/docs/introduction.rst	Fri May 07 09:30:46 2021 +0200
+++ b/docs/introduction.rst	Fri May 07 09:31:22 2021 +0200
@@ -250,6 +250,14 @@
 and :py:meth:`.Configuration.getvarl_s` the namespace is given as
 optional keyword parameter `namespace`.
 
+.. note:: Special characters within namespace, key and filter names
+          *must* be quoted (see :ref:`quoting`) when using
+          :py:meth:`~.Configuration.getvar` or
+          :py:meth:`~.Configuration.getvar_s` to retrieve variables.
+
+          With :py:meth:`~.Configuration.getvarl` or
+          :py:meth:`~.Configuration.getvarl_s` quoting is neither needed
+          and not supported.
 
 .. _merging-deletions:
 
@@ -284,6 +292,8 @@
 
    All the configuration variables are part of this namespace.
 
+   .. seealso:: :ref:`quoting`
+
 2. The namespace ``ref`` to be used for configuration references.
 
    This is a namespace that is handled special within "ConfigMix".
@@ -377,6 +387,10 @@
 :py:meth:`.Configuration.substitute_variables_in_obj` or
 :py:meth:`.Configuration.expand_variable`
 
+.. note:: Special characters within namespace, key and filter names
+          *must* be quoted (see :ref:`quoting`) when using variable
+          interpolation syntax.
+
 
 Filter functions
 ~~~~~~~~~~~~~~~~
@@ -439,9 +453,42 @@
 
 - special namespace ``ref``
 - No special handling when merging is done
-- Keys within `.getvar_s()` and `.getvar()` are handled
-- in `.getvar()` only, when it is the directly referenced value
-- recursive expandion in `.getvar_s()` expands
+- Keys within :meth:`.Configuration.getvar_s()` and
+  :py:meth:`.Configuration.getvar()` are handled
+- in :py:meth:`.Configuration.getvar()` only, when it is the directly
+  referenced value
+- recursive expandion in :py:meth:`.Configuration.getvar_s()` expands
+
+
+.. _quoting:
+
+Quoting
+-------
+
+When using :py:meth:`.Configuration.getvar` and
+:py:meth:`.Configuration.getvar_s` and when retrieving values in the
+default namespace the namespace separator ``:`` or the hierarchy
+separator ``.`` are characters with a special meaning. When using
+:ref:`variable interpolation <variable-interpolation>` the filter
+separator ``|`` is also special. To use then in key names they must be
+quoted.
+
+Quoting is done with a variant of the well-known percent-encoding in
+URIs (:rfc:`3986`).
+
+A percent-encoded character consists of the percent character ``%``,
+followed by one of the characters ``x``, ``u`` or ``U``, followed by
+the two, four or eight hexadecimal digits of the unicode codepoint
+value of the character that is to be quoted. ``x`` must be followed by
+two hex digits, ``u`` by four and ``U`` by eight.
+
+Example:
+
+  The character ``.`` with the Unicode (and ASCII) value 46 (hex 0x2e)
+  can be encoded as ``%x2e`` or ``%u002e`` or ``%U0000002e``.
+
+.. note:: Filters neeed no quoting -- and quoting within filters is *not*
+          supported.
 
 
 Custom filename extensions and custom loaders