clearly state in the comments related to chameleon work arounds tha…

…t those might go away with ``chameleon > 3.8.0``;

add a not to the Zope Book that ``chameleon`` implements `attrs` and `default` in a special way and that their value should not be changed

docs/zopebook/AppendixC.rst

@@ -694,6 +694,11 @@ Note the names `root`, `context`, `container`, `template`, `request`, `user`, an
 `modules` are optional names supported by Zope, but are not required by the
 TALES standard.
 
+Note that the (popular) ``chameleon`` template engine implements ``attrs``
+and ``default`` not as standard variables but in a special way.
+Trying to change their value may have undefined effects.
+
+
 TALES Exists expressions
 ========================
 

src/Products/PageTemplates/engine.py

@@ -261,10 +261,13 @@ def __init__(self, type, expression, zt_engine):
                                     raise ExpressionError("$ unsupported", spe)
 
     def __call__(self, target, c_engine):
-        # the convoluted handling of attrs is necessary to work around
-        # "https://github.com/malthe/chameleon/issues/323"
+        # The convoluted handling of ``attrs`` below was necessary
+        # for some ``chameleon`` versions to work around
+        # "https://github.com/malthe/chameleon/issues/323".
         # The work round is partial only: until the ``chameleon``
-        # problem is fixed, `attrs` cannot be used inside ``tal:define``
+        # problem is fixed, `attrs` cannot be used inside ``tal:define``.
+        # Potentially, ``attrs`` handling could be simplified
+        # for ``chameleon > 3.8.0``.
         return template(
             "try: __zt_tmp = attrs\n"
             "except NameError: __zt_tmp = None\n"

src/Products/PageTemplates/tests/testVariables.py

@@ -54,10 +54,11 @@ def test_attrs(self):
 
     # ``test_attrs`` should have the previous definition
     # Unfortunately, "https://github.com/malthe/chameleon/issues/323"
-    # (``attrs`` cannot be used in ``tal:define`` nor in ``tal:replace``)
+    # (``attrs`` cannot be used in ``tal:define``)
     # lets it fail.
     # We must therefore test (what works with the current
     # ``chameleon``) in a different way.
+    # Note ``chameleon > 3.8.0`` likely will allow the previous definition
     def test_attrs(self):  # noqa: F811
         t = self.g.t
         t.write("<div attr='attr' tal:content='python: attrs[\"attr\"]'/>")