--- a/docs/introduction.rst	Sat Jun 10 03:56:17 2023 +0200
+++ b/docs/introduction.rst	Sat Jun 10 04:08:40 2023 +0200
@@ -357,6 +357,8 @@
 
    Must be Filters are **not** supported.
 
+   Think of them as symbolic links.
+
 3. The namespace ``OS``
 
    Available functions:
@@ -638,6 +640,13 @@
 .. note:: A jailed configuration holds a strong reference to the unjailed
           base configuration.
 
+.. note:: If a jail's root path points to a location with a variable
+          substitutions the jail does not work: it is not possible to
+          expand the substitution.
+
+          Using ``ref`` namespaces instead works: think of
+          symbolic links.
+
 
 Custom filename extensions and custom loaders
 ---------------------------------------------