[1.2.X] Fixed #14912 -- Expanded documentation for the urlize template filter. Thanks to adamv for the draft patch.

Backport of [15086] from trunk.

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

1 files changed, 28 insertions, 12 deletions

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index de14481d39..816a3b19f7 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -1956,38 +1956,54 @@ If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be
 urlize
 ~~~~~~
 
-Converts URLs in plain text into clickable links.
+Converts URLs in text into clickable links.
 
-Note that if ``urlize`` is applied to text that already contains HTML markup,
-things won't work as expected. Apply this filter only to *plain* text.
+Works on links beginning with ``http://``, ``https://``, or ``www.`` and 
+ending with ``.org``, ``.net`` or ``.com``. Links can have trailing punctuation
+(periods, commas, close-parens) and leading punctuation (opening parens) and
+``urlize`` will still do the right thing.
+
+Links generated by ``urlize`` have a ``rel="nofollow"`` attribute added
+to them.
 
 For example::
 
     {{ value|urlize }}
 
 If ``value`` is ``"Check out www.djangoproject.com"``, the output will be
-``"Check out <a
-href="http://www.djangoproject.com">www.djangoproject.com</a>"``.
+``"Check out <a href="http://www.djangoproject.com"
+rel="nofollow">www.djangoproject.com</a>"``.
+
+The ``urlize`` filter also takes an optional parameter ``autoescape``. If
+``autoescape`` is ``True``, the link text and URLs will be escaped using
+Django's built-in :tfilter:`escape` filter. The default value for
+``autoescape`` is ``True``.
+
+.. note::
+
+    If ``urlize`` is applied to text that already contains HTML markup,
+    things won't work as expected. Apply this filter only to plain text.
 
 .. templatefilter:: urlizetrunc
 
 urlizetrunc
 ~~~~~~~~~~~
 
-Converts URLs into clickable links, truncating URLs longer than the given
-character limit.
-
-As with urlize_, this filter should only be applied to *plain* text.
+Converts URLs into clickable links just like urlize_, but truncates URLs
+longer than the given character limit.
 
-**Argument:** Length to truncate URLs to
+**Argument:** Number of characters that link text should be truncated to, 
+including the ellipsis that's added if truncation is necessary.
 
 For example::
 
     {{ value|urlizetrunc:15 }}
 
 If ``value`` is ``"Check out www.djangoproject.com"``, the output would be
-``'Check out <a
-href="http://www.djangoproject.com">www.djangopr...</a>'``.
+``'Check out <a href="http://www.djangoproject.com"
+rel="nofollow">www.djangopr...</a>'``.
+
+As with urlize_, this filter should only be applied to plain text.
 
 .. templatefilter:: wordcount