Added a section to the template documentation to clarify the arbitrary Python

code should not be expected to work. The might help balance expectations.
Thanks, James Bennett. Fixed #5125.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@6562 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/templates.txt

@@ -11,9 +11,26 @@ ease. It's designed to feel comfortable to those used to working with HTML. If
 you have any exposure to other text-based template languages, such as Smarty_
 or CheetahTemplate_, you should feel right at home with Django's templates.
 
+.. admonition:: Philosophy
+
+    If you have a background in programming, or if you're used to languages
+    like PHP which mix programming code directly into HTML, you'll want to
+    bear in mind that the Django template system is not simply Python embedded
+    into HTML. This is by design: the template system is meant to express
+    presentation, not program logic.
+
+    The Django template system provides tags which function similarly to some
+    programming constructs -- an ``{% if %}`` tag for boolean tests, a ``{%
+    for %}`` tag for looping, etc. -- but these are not simply executed as the
+    corresponding Python code, and the template system will not execute
+    arbitrary Python expressions. Only the tags, filters and syntax listed
+    below are supported by default (although you can add `your own
+    extensions`_ to the template language as needed).
+
 .. _`The Django template language: For Python programmers`: ../templates_python/
 .. _Smarty: http://smarty.php.net/
 .. _CheetahTemplate: http://www.cheetahtemplate.org/
+.. _your own extensions: ../templates_python/#extending-the-template-system
 
 Templates
 =========
@@ -382,7 +399,7 @@ loop::
             ...
         </tr>
     {% endfor %}
- 
+
 Outside of a loop, give the values a unique name the first time you call it,
 then use that name each successive time through::
 
@@ -390,16 +407,16 @@ then use that name each successive time through::
         <tr class="{% cycle rowcolors %}">...</tr>
         <tr class="{% cycle rowcolors %}">...</tr>
 
-You can use any number of values, separated by spaces. Values enclosed in 
+You can use any number of values, separated by spaces. Values enclosed in
-single (') or double quotes (") are treated as string literals, while values 
+single (') or double quotes (") are treated as string literals, while values
-without quotes are assumed to refer to context variables. 
+without quotes are assumed to refer to context variables.
 
 You can also separate values with commas::
 
     {% cycle row1,row2,row3 %}
-    
+
-In this syntax, each value will be interpreted as literal text. The 
+In this syntax, each value will be interpreted as literal text. The
-comma-based syntax exists for backwards-compatibility, and should not be 
+comma-based syntax exists for backwards-compatibility, and should not be
 used for new projects.
 
 debug
@@ -477,13 +494,13 @@ You can loop over a list in reverse by using ``{% for obj in list reversed %}``.
 If you need to loop over a list of lists, you can unpack the values
 in eachs sub-list into a set of known names. For example, if your context contains
 a list of (x,y) coordinates called ``points``, you could use the following
-to output the list of points:: 
+to output the list of points::
 
     {% for x, y in points %}
         There is a point at {{ x }},{{ y }}
     {% endfor %}
-    
+
-This can also be useful if you need to access the items in a dictionary. 
+This can also be useful if you need to access the items in a dictionary.
 For example, if your context contained a dictionary ``data``, the following
 would display the keys and values of the dictionary::