--- a/CHANGES.txt	Fri May 07 09:30:46 2021 +0200
+++ b/CHANGES.txt	Fri May 07 09:31:22 2021 +0200
@@ -16,7 +16,7 @@
 ~~~~~~~~~
 
 - **[breaking] [feature]**
-  Allowed quoting of variables.
+  Allowed quoting of variable and namespace names.
 
   This is mostly important for variable names that contain ``.``,
   ``:`` or ``|`` but probably useful for characters like ``"` ``'``

--- a/configmix/config.py	Fri May 07 09:30:46 2021 +0200
+++ b/configmix/config.py	Fri May 07 09:31:22 2021 +0200
@@ -79,6 +79,8 @@
 
         No variable interpolation is done and no filters are applied.
 
+        Quoting of `names` and `namespace` is *not* needed and wrong.
+
         """
         default = kwds.pop("default", _MARKER)
         namespace = kwds.pop("namespace", None)
@@ -105,6 +107,11 @@
 
         No variable interpolation is done and no filters are applied.
 
+        Special characters (e.g. ``:`` and ``.``) must be quoted when using
+        the default namespace.
+
+        See also :meth:`~.quote`.
+
         """
         varns, varname = self._split_ns(varname)
         if not varns:
@@ -375,8 +382,14 @@
 
     @classmethod
     def quote(klass, s):
-        """Quote a key to protect all dangerous chars: ``%``, ``.``, ``:``,
-        ``#`` and ``|``
+        """Replace important special characters in string `s` by replacing
+        them with ``%xNN`` where `NN` are the two hexadecimal digits of the
+        characters unicode codepoint value.
+
+        Handled are the important special chars: ``%``, ``.``, ``:``,
+        ``#``; ``'``, ``"`` and ``|``.
+
+        See also the :ref:`quoting` section.
 
         """
         qc = klass._QUOTE
@@ -390,8 +403,10 @@
 
     @classmethod
     def unquote(klass, s):
-        """Unquote the content of `s`: handle all patterns ``%xXX``,
-        ``%uXXXX`` or `%UXXXXXXXX``
+        """Unquote the content of `s`: handle all patterns ``%xNN``,
+        ``%uNNNN`` or ``%UNNNNNNNN``.
+
+        This is the inverse of :meth:`~.quote`.
 
         """
         if klass._QUOTE not in s:

--- a/docs/changes.rst	Fri May 07 09:30:46 2021 +0200
+++ b/docs/changes.rst	Fri May 07 09:31:22 2021 +0200
@@ -19,7 +19,7 @@
 none
 ----
 
-- Allow quoting of variables names
+- Allow quoting of variable and namespace names
 
 - Move some important public constants from :py:mod:`configmix` into
   the :py:mod:`configmix.constants` module.

--- 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