From b7abf4d5e5ab0edea914ea1077e3d48fcc5c8561 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien.potencier@gmail.com>
Date: Wed, 1 May 2013 06:57:38 +0200
Subject: [PATCH] tweaked docs for the set tag (closes #1029)

---
 doc/tags/set.rst  |   34 +++++++++++++++++++++++++++-------
 doc/templates.rst |    2 ++
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/doc/tags/set.rst b/doc/tags/set.rst
index 15090e7..4f2b2ab 100644
--- a/doc/tags/set.rst
+++ b/doc/tags/set.rst
@@ -2,28 +2,48 @@
 =======
 
 Inside code blocks you can also assign values to variables. Assignments use
-the ``set`` tag and can have multiple targets:
+the ``set`` tag and can have multiple targets.
+
+Here is how you can assign the ``bar`` value to the ``foo`` variable:
 
 .. code-block:: jinja
 
-    {% set foo = 'foo' %}
+    {% set foo = 'bar' %}
 
-    {% set foo = [1, 2] %}
+After the ``set`` call, the ``foo`` variable is available in the template like
+any other ones:
 
-    {% set foo = {'foo': 'bar'} %}
+.. code-block:: jinja
+
+    {# displays bar #}
+    {{ foo }}
 
+The assigned value can be any valid :ref:`Twig expressions
+<twig-expressions>`:
+
+.. code-block:: jinja
+
+    {% set foo = [1, 2] %}
+    {% set foo = {'foo': 'bar'} %}
     {% set foo = 'foo' ~ 'bar' %}
 
+Several variables can be assigned in one block:
+
     {% set foo, bar = 'foo', 'bar' %}
 
+    {# is equivalent to #}
+
+    {% set foo = 'foo' %}
+    {% set bar = 'bar' %}
+
 The ``set`` tag can also be used to 'capture' chunks of text:
 
 .. code-block:: jinja
 
     {% set foo %}
-      <div id="pagination">
-        ...
-      </div>
+        <div id="pagination">
+            ...
+        </div>
     {% endset %}
 
 .. caution::
diff --git a/doc/templates.rst b/doc/templates.rst
index 94eb9f9..f87b036 100644
--- a/doc/templates.rst
+++ b/doc/templates.rst
@@ -544,6 +544,8 @@ macro call:
         <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" />
     {% endmacro %}
 
+.. _twig-expressions:
+
 Expressions
 -----------
 
-- 
1.7.2.5