From ec282bfab6f7b7c3d69a5a1b10bea593c7b3df41 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Wed, 7 Aug 2024 11:12:53 +0200
Subject: [PATCH] Add a note about how macros can override existing functions

---
 doc/tags/macro.rst | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/doc/tags/macro.rst b/doc/tags/macro.rst
index effa6b6bdc9..c3093f0fb66 100644
--- a/doc/tags/macro.rst
+++ b/doc/tags/macro.rst
@@ -7,7 +7,7 @@ are useful to reuse template fragments to not repeat yourself.
 Macros are defined in regular templates.
 
 Imagine having a generic helper template that define how to render HTML forms
-via macros (called ``forms.html``):
+via macros (called ``forms.twig``):
 
 .. code-block:: html+twig
 
@@ -49,9 +49,9 @@ tag:
 
 .. code-block:: twig
 
-    {% import "forms.html" as forms %}
+    {% import "forms.twig" as forms %}
 
-The above ``import`` call imports the ``forms.html`` file (which can contain
+The above ``import`` call imports the ``forms.twig`` file (which can contain
 only macros, or a template and some macros), and import the macros as items of
 the ``forms`` local variable.
 
@@ -67,11 +67,23 @@ via the ``from`` tag:
 
 .. code-block:: html+twig
 
-    {% from 'forms.html' import input as input_field, textarea %}
+    {% from 'forms.twig' import input as input_field, textarea %}
 
     <p>{{ input_field('password', '', 'password') }}</p>
     <p>{{ textarea('comment') }}</p>
 
+.. caution::
+
+    As macros imported via ``from`` are accessible by calling them like
+    functions, be careful to not override existing functions:
+
+    .. code-block:: twig
+
+        {% from 'forms.twig' import input as include %}
+
+        {# include refers to the macro and not to the built-in "include" function #}
+        {{ include() }}
+
 .. tip::
 
     When macro usages and definitions are in the same template, you don't need to