Improve whitespace docs to reflect reality.

[jinja2.git] / docs / templates.rst

diff --git a/docs/templates.rst b/docs/templates.rst
index b563277ca5ecdbae8d0ab37d5a43be4c71ae03c5..790b95e7c24908ff083291ad8e338ca6396b0685 100644 (file)
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -101,7 +101,7 @@ if printed and that you can iterate over it, but every other operation fails.
 Filters
 -------
 
-Variables can by modified by **filters**.  Filters are separated from the
+Variables can be modified by **filters**.  Filters are separated from the
 variable by a pipe symbol (``|``) and may have optional arguments in
 parentheses.  Multiple filters can be chained.  The output of one filter is
 applied to the next.
@@ -152,10 +152,11 @@ yourself::
 Whitespace Control
 ------------------
 
-In the default configuration whitespace is not further modified by the
-template engine, so each whitespace (spaces, tabs, newlines etc.) is returned
-unchanged.  If the application configures Jinja to `trim_blocks` the first
-newline after a a template tag is removed automatically (like in PHP).
+In the default configuration, a single trailing newline is stripped if
+present, and whitespace is not further modified by the template engine. Each
+whitespace (spaces, tabs, newlines etc.) is returned unchanged.  If the
+application configures Jinja to `trim_blocks` the first newline after a a
+template tag is removed automatically (like in PHP).
 
 But you can also strip whitespace in templates by hand.  If you put an minus
 sign (``-``) to the start or end of an block (for example a for tag), a
@@ -332,7 +333,7 @@ advantage of it, see :ref:`null-master-fallback`.
 
 The filename of the template depends on the template loader.  For example the
 :class:`FileSystemLoader` allows you to access other templates by giving the
-filename.  You can access templates in subdirectories with an slash::
+filename.  You can access templates in subdirectories with a slash::
 
     {% extends "layout/default.html" %}
 
@@ -497,7 +498,21 @@ provided in a variable called `users`::
     {% endfor %}
     </ul>
 
-Inside of a for loop block you can access some special variables:
+As variables in templates retain their object properties, it is possible to
+iterate over containers like `dict`::
+
+    <dl>
+    {% for key, value in my_dict.iteritems() %}
+        <dt>{{ key|e }}</dt>
+        <dd>{{ value|e }}</dd>
+    {% endfor %}
+    </dl>
+
+Note however that dictionaries usually are unordered so you might want to
+either pass it as a sorted list to the template or use the `dictsort`
+filter.
+
+Inside of a for-loop block you can access some special variables:
 
 +-----------------------+---------------------------------------------------+
 | Variable              | Description                                       |
@@ -529,7 +544,7 @@ each time through the loop by using the special `loop.cycle` helper::
         <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
     {% endfor %}
 
-With Jinja 2.1 an extra `cycle` helper exists that allows loop-unbound
+Since Jinja 2.1 an extra `cycle` helper exists that allows loop-unbound
 cycling.  For more information have a look at the :ref:`builtin-globals`.
 
 .. _loop-filtering:
@@ -805,7 +820,7 @@ Jinja2 supports putting often used code into macros.  These macros can go into
 different templates and get imported from there.  This works similar to the
 import statements in Python.  It's important to know that imports are cached
 and imported templates don't have access to the current template variables,
-just the globals by defualt.  For more details about context behavior of
+just the globals by default.  For more details about context behavior of
 imports and includes see :ref:`import-visibility`.
 
 There are two ways to import templates.  You can import the complete template
@@ -1180,7 +1195,7 @@ The following functions are available in the global scope by default:
 .. class:: joiner(sep=', ')
 
     A tiny helper that can be use to "join" multiple sections.  A joiner is
-    passed a string and will return that string every time it's calld, except
+    passed a string and will return that string every time it's called, except
     the first time in which situation it returns an empty string.  You can
     use this to join things::
 
@@ -1276,7 +1291,7 @@ placeholders is a lot easier:
     {{ gettext('Hello %(name)s!', name='World') }}
     {{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }}
 
-Note that the `ngettext` function's format string automatically recieves
+Note that the `ngettext` function's format string automatically receives
 the count as `num` parameter additionally to the regular parameters.
 
 
@@ -1295,7 +1310,7 @@ Loop Controls
 
 If the application enables the :ref:`loopcontrols-extension` it's possible to
 use `break` and `continue` in loops.  When `break` is reached, the loop is
-terminated, if `continue` is eached the processing is stopped and continues
+terminated;  if `continue` is reached, the processing is stopped and continues
 with the next iteration.
 
 Here a loop that skips every second item::