[1.1.X] Fixed #12496 - Added code examples to built-in filter documen…

…tation. Thanks, Arthur Koziel.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@12243 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/ref/templates/builtins.txt

@@ -876,20 +876,38 @@ addslashes
 
 Adds slashes before quotes. Useful for escaping strings in CSV, for example.
 
+For example::
+
+    {{ value|addslashes }}
+
+If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``.
+
 .. templatefilter:: capfirst
 
 capfirst
 ~~~~~~~~
 
 Capitalizes the first character of the value.
 
+For example::
+
+    {{ value|capfirst }}
+
+If ``value`` is ``"django"``, the output will be ``"Django"``.
+
 .. templatefilter:: center
 
 center
 ~~~~~~
 
 Centers the value in a field of a given width.
 
+For example::
+
+    "{{ value|center:"15" }}"
+
+If ``value`` is ``"Django"``, the output will be ``"     Django    "``.
+
 .. templatefilter:: cut
 
 cut
@@ -1048,6 +1066,13 @@ Escapes characters for use in JavaScript strings. This does *not* make the
 string safe for use in HTML, but does protect you from syntax errors when using
 templates to generate JavaScript/JSON.
 
+For example::
+
+    {{ value|escapejs }}
+
+If ``value`` is ``"testing\r\njavascript \'string" <b>escaping</b>"``,
+the output will be ``"testing\\x0D\\x0Ajavascript \\x27string\\x22 \\x3Cb\\x3Eescaping\\x3C/b\\x3E"``.
+
 .. templatefilter:: filesizeformat
 
 filesizeformat
@@ -1174,6 +1199,12 @@ strings containing non-ASCII characters in a URL.
 It's safe to use this filter on a string that has already gone through the
 ``urlencode`` filter.
 
+For example::
+
+    {{ value|iriencode }}
+
+If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&amp;me=2"``.
+
 .. templatefilter:: join
 
 join
@@ -1254,13 +1285,36 @@ linebreaksbr
 Converts all newlines in a piece of plain text to HTML line breaks
 (``<br />``).
 
+For example::
+
+    {{ value|linebreaksbr }}
+
+If ``value`` is ``Joel\nis a slug``, the output will be ``Joel<br />is a
+slug``.
+
 .. templatefilter:: linenumbers
 
 linenumbers
 ~~~~~~~~~~~
 
 Displays text with line numbers.
 
+For example::
+
+    {{ value|linenumbers }}
+
+If ``value`` is::
+
+    one
+    two
+    three
+
+the output will be::
+
+    1. one
+    2. two
+    3. three
+
 .. templatefilter:: ljust
 
 ljust
@@ -1270,6 +1324,12 @@ Left-aligns the value in a field of a given width.
 
 **Argument:** field size
 
+For example::
+
+    "{{ value|ljust:"10" }}"
+
+If ``value`` is ``Django``, the output will be ``"Django    "``.
+
 .. templatefilter:: lower
 
 lower
@@ -1305,12 +1365,17 @@ phone2numeric
 ~~~~~~~~~~~~~
 
 Converts a phone number (possibly containing letters) to its numerical
-equivalent. For example, ``'800-COLLECT'`` will be converted to
-``'800-2655328'``.
+equivalent.
 
 The input doesn't have to be a valid phone number. This will happily convert
 any string.
 
+For example::
+
+    {{ value|phone2numeric }}
+
+If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``.
+
 .. templatefilter:: pluralize
 
 pluralize
@@ -1322,6 +1387,9 @@ Example::
 
     You have {{ num_messages }} message{{ num_messages|pluralize }}.
 
+If ``num_messages`` is ``1``, the output will be ``You have 1 message.``
+If ``num_messages`` is ``2``  the output will be ``You have 2 messages.``
+
 For words that require a suffix other than ``'s'``, you can provide an alternate
 suffix as a parameter to the filter.
 
@@ -1381,6 +1449,12 @@ Right-aligns the value in a field of a given width.
 
 **Argument:** field size
 
+For example::
+
+    "{{ value|rjust:"10" }}"
+
+If ``value`` is ``Django``, the output will be ``"    Django"``.
+
 .. templatefilter:: safe
 
 safe
@@ -1419,6 +1493,8 @@ Example::
 
     {{ some_list|slice:":2" }}
 
+If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``.
+
 .. templatefilter:: slugify
 
 slugify
@@ -1534,6 +1610,12 @@ title
 
 Converts a string into titlecase.
 
+For example::
+
+    {{ value|title }}
+
+If ``value`` is ``"my first post"``, the output will be ``"My First Post"``.
+
 .. templatefilter:: truncatewords
 
 truncatewords
@@ -1561,6 +1643,13 @@ closed immediately after the truncation.
 This is less efficient than ``truncatewords``, so should only be used when it
 is being passed HTML text.
 
+For example::
+
+    {{ value|truncatewords_html:2 }}
+
+If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be
+``"<p>Joel is ...</p>"``.
+
 .. templatefilter:: unordered_list
 
 unordered_list
@@ -1611,6 +1700,13 @@ urlencode
 
 Escapes a value for use in a URL.
 
+For example::
+
+    {{ value|urlencode }}
+
+If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be
+``"http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``.
+
 .. templatefilter:: urlize
 
 urlize
@@ -1656,6 +1752,12 @@ wordcount
 
 Returns the number of words.
 
+For example::
+
+    {{ value|wordcount }}
+
+If ``value`` is ``"Joel is a slug"``, the output will be ``4``.
+
 .. templatefilter:: wordwrap
 
 wordwrap