minor #2852 Improve documentation on tags (fabpot)

This PR was merged into the 1.x branch.

Discussion
----------

Improve documentation on tags

Commits
-------

571cf6e9 improved documentation on tags

doc/advanced.rst

@@ -386,6 +386,31 @@ One of the most exciting features of a template engine like Twig is the
 possibility to define new language constructs. This is also the most complex
 feature as you need to understand how Twig's internals work.
 
+.. tip::
+
+    A tag should only be used to create **new language constructs**. A tag
+    should not output content (use a function instead) and it should not modify
+    content (use a filter instead).
+
+    For instance, if you want to create a tag that converts a Markdown formatted
+    text to HTML, create a ``markdown`` filter instead:
+
+    .. code-block:: jinja
+
+        {{ '**markdown** text'|markdown }}
+
+    If you want use this filter on large amounts of text, wrap it with the
+    :doc:`filter <tags/filter>` tag:
+
+    .. code-block:: jinja
+
+        {% filter markdown %}
+        Title
+        =====
+
+        Much better than creating a tag as you can **compose** filters.
+        {% endfilter %}
+
 Let's create a simple ``set`` tag that allows the definition of simple
 variables from within a template. The tag can be used like follows:
 

doc/tags/filter.rst

@@ -10,11 +10,11 @@ data. Just wrap the code in the special ``filter`` section:
         This text becomes uppercase
     {% endfilter %}
 
-You can also chain filters:
+You can also chain filters and pass arguments to them:
 
 .. code-block:: jinja
 
-    {% filter lower|escape %}
+    {% filter lower|escape('html') %}
         <strong>SOME TEXT</strong>
     {% endfilter %}