updated macro documentation to warn about a hack that won't work anymore in Twig 2.x

diff --git a/doc/tags/macro.rst b/doc/tags/macro.rst
index 3d920e3..155f7fe 100644 (file)
--- a/doc/tags/macro.rst
+++ b/doc/tags/macro.rst
@@ -48,41 +48,33 @@ The macro can then be called at will:
     <p>{{ forms.input('password', null, 'password') }}</p>
 
 If macros are defined and used in the same template, you can use the
-special ``_self`` variable, without importing them:
+special ``_self`` variable to import them:
 
 .. code-block:: jinja
 
-    <p>{{ _self.input('username') }}</p>
+    {% import _self as forms %}
 
-When you want to use a macro in another one from the same file, use the ``_self``
-variable:
+    <p>{{ forms.input('username') }}</p>
 
-.. code-block:: jinja
+.. warning::
 
-    {% macro input(name, value, type, size) %}
-      <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
-    {% endmacro %}
+    When you define a macro in the template where you are going to use it, you
+    might be tempted to call the macro directly via ``_self.input()`` instead
+    of importing it; even if seems to work, this is just a side-effect of the
+    current implementation and it won't work anymore in Twig 2.x.
 
-    {% macro wrapped_input(name, value, type, size) %}
-        <div class="field">
-            {{ _self.input(name, value, type, size) }}
-        </div>
-    {% endmacro %}
-
-When the macro is defined in another file, you need to import it:
+When you want to use a macro in another macro from the same file, you need to
+import it locally:
 
 .. code-block:: jinja
 
-    {# forms.html #}
-
     {% macro input(name, value, type, size) %}
-      <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
+        <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
     {% endmacro %}
 
-    {# shortcuts.html #}
-
     {% macro wrapped_input(name, value, type, size) %}
-        {% import "forms.html" as forms %}
+        {% import _self as forms %}
+
         <div class="field">
             {{ forms.input(name, value, type, size) }}
         </div>