--- a/docs/introduction.rst	Sat Jun 10 04:08:40 2023 +0200
+++ b/docs/introduction.rst	Sat Jun 10 11:40:05 2023 +0200
@@ -359,6 +359,8 @@
 
    Think of them as symbolic links.
 
+   See also chapter `Configuration tree references`_.
+
 3. The namespace ``OS``
 
    Available functions:
@@ -515,22 +517,23 @@
 Configuration tree references
 -----------------------------
 
-With ``{{ref:#my.other.key}}``
+Syntax is ``{{ref:#my.other.key}}``.
 
-- think of it as a sort of a symbolic link to other parts of the
-  configuration tree
-- by employing the special namespace ``ref``
-- can not be quoted currently in variable interpolation syntax
+- Think of it as a sort of a symbolic link to other parts of the
+  configuration tree.
+- They occupy the special namespace ``ref``.
+- Note that they can not be quoted currently in variable interpolation syntax.
 - No special handling when merging is done -- merging is agnostic of
-  tree references
+  tree references.
 - Keys within :meth:`.Configuration.getvar_s`,
   :py:meth:`.Configuration.getvar`, :py:meth:`.Configuration.getvarl`
-  and :py:meth:`.Configuration.getvarl_s`  are handled
-- in :py:meth:`.Configuration.getvar` only, when it is the directly
-  referenced value
-- recursive expansion in :py:meth:`.Configuration.getvar_s` and
+  and :py:meth:`.Configuration.getvarl_s`  are handled.
+- In :py:meth:`.Configuration.getvar` a reference handled only when it
+  is the directly referenced value
+- Recursive expansion in :py:meth:`.Configuration.getvar_s` and
   :py:meth:`.Configuration.getvarl_s`:
-  beware of recursive (direct or indirect) tree references
+  beware of recursive (direct or indirect) tree references.
+- References do work as root paths of `Jailed Configurations`_.
 
 
 .. _quoting: