added some docs about the difference between the include tag and the include function

doc/advanced.rst

@@ -244,8 +244,9 @@ last argument to the filter call as an array::
         // ...
     }, ['is_variadic' => true]);
 
-Be warned that named arguments passed to a variadic filter cannot be checked
-for validity as they will automatically end up in the option array.
+Be warned that :ref:`named arguments <named-arguments>` passed to a variadic
+filter cannot be checked for validity as they will automatically end up in the
+option array.
 
 Dynamic Filters
 ~~~~~~~~~~~~~~~

doc/tags/include.rst

@@ -2,7 +2,7 @@
 ===========
 
 The ``include`` statement includes a template and returns the rendered content
-of that file into the current namespace:
+of that file:
 
 .. code-block:: jinja
 
@@ -10,6 +10,30 @@ of that file into the current namespace:
         Body
     {% include 'footer.html' %}
 
+.. note::
+
+    As of Twig 1.12, it is recommended to use the
+    :doc:`include<../functions/include>` function instead as it provides the
+    same features with a bit more flexibility:
+
+    * The ``include`` function is semantically more "correct" (including a
+      template outputs its rendered contents in the current scope; a tag should
+      not display anything);
+
+    * The rendered template can be more easily stored in a variable when using
+      the ``include`` function:
+
+      .. code-block:: jinja
+
+          {% set content %}{% include 'template.html' %}{% endset %}
+
+          {# vs #}
+
+          {% set content = include('template.html') %}
+
+    * The ``include`` function does not impose any specific order for
+      arguments thanks to :ref:`named arguments <named-arguments>`.
+
 Included templates have access to the variables of the active context.
 
 If you are using the filesystem loader, the templates are looked for in the

doc/templates.rst

@@ -196,6 +196,8 @@ progression of integers:
 Go to the :doc:`functions<functions/index>` page to learn more about the
 built-in functions.
 
+.. _named-arguments:
+
 Named Arguments
 ---------------