Merge pull request #4040 from ngrilly/devel

Update documentation about Jinja2 expressions in playbooks

docsite/latest/rst/playbooks.rst

@@ -149,7 +149,17 @@ These variables can be used later in the playbook like this::
 
     {{ varname }}
 
-Variables are passed through the Jinja2 templating engine, and support the use of filters to modify the variable (for example: `{{ varname|int }}` ensures the variable is interpreted as an integer). To learn more about Jinja2, you can optionally see the `Jinja2 docs <http://jinja.pocoo.org/docs/>`_ - though remember that Jinja2 loops and conditionals are only for 'templates' in Ansible, in playbooks, ansible has the 'when' and 'with' keywords for conditionals and loops.
+Variables are passed through the Jinja2 templating engine. Any valid Jinja2
+expression can be used between the curly braces,  including the use of filters
+to modify the variable (for example, `{{ varname|int }}` ensures the variable is
+interpreted as an integer).
+
+Jinja2 expressions are very similar to Python and even if you are not working
+with Python you should feel comfortable with them. See the `Jinja2 documentation
+<http://jinja.pocoo.org/docs/templates/>`_ to learn more about the syntax.
+Please note that Jinja2 loops and conditionals are only useful in Ansible
+templates, not in playbooks. Use the 'when' and 'with' keywords for
+conditionals and loops in Ansible playbooks.
 
 If there are discovered variables about the system, called 'facts', these variables bubble up back into the playbook, and can be used on each system just like explicitly set variables.  Ansible provides several
 of these, prefixed with 'ansible', which are documented under 'setup' in the module documentation.  Additionally,

docsite/latest/rst/playbooks2.rst

@@ -307,7 +307,8 @@ Sometimes you will want to skip a particular step on a particular host.  This co
 as simple as not installing a certain package if the operating system is a particular version,
 or it could be something like performing some cleanup steps if a filesystem is getting full.
 
-This is easy to do in Ansible, with the `when` clause, which actually is a Python expression.
+This is easy to do in Ansible, with the `when` clause, which contains a Jinja2 expression (see chapter
+`Playbooks <http://www.ansibleworks.com/docs/playbooks.html#vars-section>`_ for more info).
 Don't panic -- it's actually pretty simple::
 
     tasks:
@@ -1130,8 +1131,8 @@ Running a task in check mode
 .. versionadded:: 1.3
 
 Sometimes you may want to have a task to be executed even in check
-mode. To achieve this use the `always_run` clause on the task. Its
+mode. To achieve this, use the `always_run` clause on the task. Its
-value is a Python expression, just like the `when` clause. In simple
+value is a Jinja2 expression, just like the `when` clause. In simple
 cases a boolean YAML value would be sufficient as a value.
 
 Example::