From 0559cacfaf815af5bd11b81f88855cdf211e0736 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien.potencier@gmail.com>
Date: Sun, 4 Aug 2013 08:56:55 +0200
Subject: [PATCH] tweaked documentation about overloading existing filters, ... (closes #1094)

---
 doc/advanced.rst |   25 +++++++++++++++----------
 1 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/advanced.rst b/doc/advanced.rst
index e1945eb..0bf5af2 100644
--- a/doc/advanced.rst
+++ b/doc/advanced.rst
@@ -735,16 +735,8 @@ Overloading
 -----------
 
 To overload an already defined filter, test, operator, global variable, or
-function, define it again **as late as possible**::
-
-    $twig = new Twig_Environment($loader);
-    $twig->addFilter(new Twig_SimpleFilter('date', function ($timestamp, $format = 'F j, Y H:i') {
-        // do something different from the built-in date filter
-    }));
-
-Here, we have overloaded the built-in ``date`` filter with a custom one.
-
-That also works with an extension::
+function, re-define it in an extension and register it **as late as
+possible** (order matters)::
 
     class MyCoreExtension extends Twig_Extension
     {
@@ -769,6 +761,19 @@ That also works with an extension::
     $twig = new Twig_Environment($loader);
     $twig->addExtension(new MyCoreExtension());
 
+Here, we have overloaded the built-in ``date`` filter with a custom one.
+
+If you do the same on the Twig_Environment itself, beware that it takes
+precedence over any other registered extensions::
+
+    $twig = new Twig_Environment($loader);
+    $twig->addFilter(new Twig_SimpleFilter('date', function ($timestamp, $format = 'F j, Y H:i') {
+        // do something different from the built-in date filter
+    }));
+    // the date filter will come from the above registration, not
+    // from the registered extension below
+    $twig->addExtension(new MyCoreExtension());
+
 .. caution::
 
     Note that overloading the built-in Twig elements is not recommended as it
-- 
1.7.2.5