Clarified docs for some tags and filters

docs/ref/templates/builtins.txt

@@ -60,6 +60,8 @@ Sample usage::
         <p>Commented out text with {{ create_date|date:"c" }}</p>
     {% endcomment %}
 
+``comment`` tags cannot be nested.
+
 .. templatetag:: csrf_token
 
 csrf_token
@@ -73,10 +75,12 @@ This tag is used for CSRF protection, as described in the documentation for
 cycle
 ^^^^^
 
-Cycles among the given strings or variables each time this tag is encountered.
+Produces one of its arguments each time this tag is encountered. The first
+argument is produced on the first encounter, the second argument on the second
+encounter, and so forth. Once all arguments are exhausted, the tag cycles to
+the first argument and produces it again.
 
-Within a loop, cycles among the given strings each time through the
+This tag is particularly useful in a loop::
-loop::
 
     {% for o in some_list %}
         <tr class="{% cycle 'row1' 'row2' %}">
@@ -84,8 +88,13 @@ loop::
         </tr>
     {% endfor %}
 
+The first iteration produces HTML that refers to class ``row1``, the second to
+``row2``, the third to ``row1`` again, and so on for each iteration of the
+loop.
+
 You can use variables, too. For example, if you have two template variables,
-``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this::
+``rowvalue1`` and ``rowvalue2``, you can alternate between their values like
+this::
 
     {% for o in some_list %}
         <tr class="{% cycle rowvalue1 rowvalue2 %}">
@@ -93,9 +102,10 @@ You can use variables, too. For example, if you have two template variables,
         </tr>
     {% endfor %}
 
-Note that variable arguments (``rowvalue1`` and ``rowvalue2`` above) are NOT
+Note that the variables included in the cycle will not be escaped. Any HTML or
-auto-escaped! So either make sure that you trust their values, or use explicit
+Javascript code contained in the printed variable will be rendered as-is, which
-escaping, like this::
+could potentially lead to security issues. So either make sure that you trust
+their values or use explicit escaping like this::
 
     {% for o in some_list %}
         <tr class="{% filter force_escape %}{% cycle rowvalue1 rowvalue2 %}{% endfilter %}">
@@ -111,17 +121,17 @@ You can mix variables and strings::
         </tr>
     {% endfor %}
 
-In some cases you might want to refer to the next value of a cycle from
+In some cases you might want to refer to the current value of a cycle
-outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using
+without advancing to the next value. To do this,
-"as", like this::
+just give the ``{% cycle %}`` tag a name, using "as", like this::
 
     {% cycle 'row1' 'row2' as rowcolors %}
 
-From then on, you can insert the current value of the cycle wherever
+From then on, you can insert the current value of the cycle wherever you'd like
-you'd like in your template by referencing the cycle name as a context
+in your template by referencing the cycle name as a context variable. If you
-variable. If you want to move the cycle onto the next value, you use
+want to move the cycle to the next value independently of the original
-the cycle tag again, using the name of the variable. So, the following
+``cycle`` tag, you can use another ``cycle`` tag and specify the name of the
-template::
+variable. So, the following template::
 
     <tr>
         <td class="{% cycle 'row1' 'row2' as rowcolors %}">...</td>
@@ -143,15 +153,39 @@ would output::
         <td class="row2">...</td>
     </tr>
 
-You can use any number of values in a ``{% cycle %}`` tag, separated by spaces.
+You can use any number of values in a ``cycle`` tag, separated by spaces.
-Values enclosed in single (``'``) or double quotes (``"``) are treated as
+Values enclosed in single quotes (``'``) or double quotes (``"``) are treated
-string literals, while values without quotes are treated as template variables.
+as string literals, while values without quotes are treated as template
+variables.
 
-Note that currently the variables included in the cycle will not be escaped.
+By default, when you use the ``as`` keyword with the cycle tag, the
-Any HTML or Javascript code contained in the printed variable will be rendered
+usage of ``{% cycle %}`` that initiates the cycle will itself produce
-as-is, which could potentially lead to security issues.
+the first value in the cycle. This could be a problem if you want to
+use the value in a nested loop or an included template. If you only want
+to declare the cycle but not produce the first value, you can add a
+``silent`` keyword as the last keyword in the tag. For example::
 
-For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior
+    {% for obj in some_list %}
+        {% cycle 'row1' 'row2' as rowcolors silent %}
+        <tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
+    {% endfor %}
+
+This will output a list of ``<tr>`` elements with ``class``
+alternating between ``row1`` and ``row2``. The subtemplate will have
+access to ``rowcolors`` in its context and the value will match the class
+of the ``<tr>`` that encloses it. If the ``silent`` keyword were to be
+omitted, ``row1`` and ``row2`` would be emitted as normal text, outside the
+``<tr>`` element.
+
+When the silent keyword is used on a cycle definition, the silence
+automatically applies to all subsequent uses of that specific cycle tag.
+The following template would output *nothing*, even though the second
+call to ``{% cycle %}`` doesn't specify ``silent``::
+
+    {% cycle 'row1' 'row2' as rowcolors silent %}
+    {% cycle rowcolors %}
+
+For backward compatibility, the ``{% cycle %}`` tag supports the much inferior
 old syntax from previous Django versions. You shouldn't use this in any new
 projects, but for the sake of the people who are still using it, here's what it
 looks like::
@@ -162,42 +196,15 @@ In this syntax, each value gets interpreted as a literal string, and there's no
 way to specify variable values. Or literal commas. Or spaces. Did we mention
 you shouldn't use this syntax in any new projects?
 
-By default, when you use the ``as`` keyword with the cycle tag, the
-usage of ``{% cycle %}`` that declares the cycle will itself output
-the first value in the cycle. This could be a problem if you want to
-use the value in a nested loop or an included template. If you want to
-just declare the cycle, but not output the first value, you can add a
-``silent`` keyword as the last keyword in the tag. For example::
-
-    {% for obj in some_list %}
-        {% cycle 'row1' 'row2' as rowcolors silent %}
-        <tr class="{{ rowcolors }}">{% include "subtemplate.html" %}</tr>
-    {% endfor %}
-
-This will output a list of ``<tr>`` elements with ``class``
-alternating between ``row1`` and ``row2``; the subtemplate will have
-access to ``rowcolors`` in its context that matches the class of the
-``<tr>`` that encloses it. If the ``silent`` keyword were to be
-omitted, ``row1`` would be emitted as normal text, outside the
-``<tr>`` element.
-
-When the silent keyword is used on a cycle definition, the silence
-automatically applies to all subsequent uses of the cycle tag. In,
-the following template would output *nothing*, even though the second
-call to ``{% cycle %}`` doesn't specify silent::
-
-    {% cycle 'row1' 'row2' as rowcolors silent %}
-    {% cycle rowcolors %}
-
 .. versionchanged:: 1.6
 
-    To improve safety, future versions of ``cycle`` will automatically escape
+To improve safety, future versions of ``cycle`` will automatically escape
-    their output. You're encouraged to activate this behavior by loading
+their output. You're encouraged to activate this behavior by loading
-    ``cycle`` from the ``future`` template library::
+``cycle`` from the ``future`` template library::
 
     {% load cycle from future %}
 
-    When using the ``future`` version, you can disable auto-escaping with::
+When using the ``future`` version, you can disable auto-escaping with::
 
     {% for o in some_list %}
         <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}">
@@ -237,10 +244,12 @@ See :ref:`template-inheritance` for more information.
 filter
 ^^^^^^
 
-Filters the contents of the variable through variable filters.
+Filters the contents of the block through one or more filters. Multiple
+filters can be specified with pipes and filters can have arguments, just as
+in variable syntax.
 
-Filters can also be piped through each other, and they can have arguments --
+Note that the block includes *all* the text between the ``filter`` and
-just like in variable syntax.
+``endfilter`` tags.
 
 Sample usage::
 
@@ -259,8 +268,8 @@ Sample usage::
 firstof
 ^^^^^^^
 
-Outputs the first variable passed that is not False. Does NOT auto-escape
+Outputs the first argument variable that is not False. This tag does *not*
-variable values.
+auto-escape variable values.
 
 Outputs nothing if all the passed variables are False.
 
@@ -315,8 +324,9 @@ to escape the variables in the firstof tag, you must do so explicitly::
 for
 ^^^
 
-Loop over each item in an array.  For example, to display a list of athletes
+Loops over each item in an array, making the item available in a context
-provided in ``athlete_list``::
+variable. For example, to display a list of athletes provided in
+``athlete_list``::
 
     <ul>
     {% for athlete in athlete_list %}
@@ -328,7 +338,7 @@ 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 each sub-list into individual variables. For example, if your context
+in each sublist into individual variables. 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::
 
@@ -357,14 +367,14 @@ Variable                    Description
                             loop (0-indexed)
 ``forloop.first``           True if this is the first time through the loop
 ``forloop.last``            True if this is the last time through the loop
-``forloop.parentloop``      For nested loops, this is the loop "above" the
+``forloop.parentloop``      For nested loops, this is the loop surrounding
-                            current one
+                            the current one
 ==========================  ===============================================
 
 for ... empty
 ^^^^^^^^^^^^^
 
-The ``for`` tag can take an optional ``{% empty %}`` clause that will be
+The ``for`` tag can take an optional ``{% empty %}`` clause whose text is
 displayed if the given array is empty or could not be found::
 
     <ul>
@@ -697,8 +707,8 @@ the variable ``template_name``::
     accepts a context. This allows you to reference a compiled ``Template`` in
     your context.
 
-An included template is rendered with the context of the template that's
+An included template is rendered within the context of the template that
-including it. This example produces the output ``"Hello, John"``:
+includes it. This example produces the output ``"Hello, John"``:
 
 * Context: variable ``person`` is set to ``"john"``.
 * Template::
@@ -713,8 +723,9 @@ You can pass additional context to the template using keyword arguments::
 
     {% include "name_snippet.html" with person="Jane" greeting="Hello" %}
 
-If you want to only render the context with the variables provided (or even
+If you want to render the context only with the variables provided (or even
-no variables at all), use the ``only`` option::
+no variables at all), use the ``only`` option. No other variables are
+available to the included template::
 
     {% include "name_snippet.html" with greeting="Hi" only %}
 
@@ -1194,7 +1205,8 @@ If ``value`` is ``"I'm using Django"``, the output will be
 capfirst
 ^^^^^^^^
 
-Capitalizes the first character of the value.
+Capitalizes the first character of the value. If the first character is not
+a letter, this filter has no effect.
 
 For example::
 
@@ -2081,7 +2093,8 @@ date that is in the past relative to the comparison point.
 title
 ^^^^^
 
-Converts a string into titlecase.
+Converts a string into titlecase by capitalizing each word in the string.
+This tag makes no effort to keep "trivial words" in lowercase.
 
 For example::