gis: Merged revisions 7181-7277 via svnmerge from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@7279 bcc190cf-cafb-0310-a4f2-bffc1f526a37

12 files changed, 598 insertions, 58 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index 5134e90267..9167458db2 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -83,12 +83,12 @@ Methods
 objects in the same way as any other `Django model`_::
 
     myuser.groups = [group_list]
-    myuser.groups.add(group, group,...)
-    myuser.groups.remove(group, group,...)
+    myuser.groups.add(group, group, ...)
+    myuser.groups.remove(group, group, ...)
     myuser.groups.clear()
     myuser.user_permissions = [permission_list]
     myuser.user_permissions.add(permission, permission, ...)
-    myuser.user_permissions.remove(permission, permission, ...]
+    myuser.user_permissions.remove(permission, permission, ...)
     myuser.user_permissions.clear()
 
 In addition to those automatic API methods, ``User`` objects have the following
@@ -309,7 +309,7 @@ with that ``User``.
 
 For more information, see `Chapter 12 of the Django book`_.
 
-.. _Chapter 12 of the Django book: http://www.djangobook.com/en/beta/chapter12/#cn226
+.. _Chapter 12 of the Django book: http://www.djangobook.com/en/1.0/chapter12/#cn222
 
 Authentication in Web requests
 ==============================
@@ -380,14 +380,14 @@ This example shows how you might use both ``authenticate()`` and ``login()``::
             # Return an 'invalid login' error message.
 
 .. admonition:: Calling ``authenticate()`` first
-    
+
     When you're manually logging a user in, you *must* call
     ``authenticate()`` before you call ``login()``. ``authenticate()``
     sets an attribute on the ``User`` noting which authentication
     backend successfully authenticated that user (see the `backends
     documentation`_ for details), and this information is needed later
     during the login process.
-    
+
 .. _backends documentation: #other-authentication-sources
 
 Manually checking a user's password
@@ -460,7 +460,7 @@ introduced in Python 2.4::
 
 In the Django development version, ``login_required`` also takes an optional
 ``redirect_field_name`` parameter. Example::
-    
+
     from django.contrib.auth.decorators import login_required
 
     def my_view(request):
@@ -468,7 +468,7 @@ In the Django development version, ``login_required`` also takes an optional
     my_view = login_required(redirect_field_name='redirect_to')(my_view)
 
 Again, an equivalent example of the more compact decorator syntax introduced in Python 2.4::
-    
+
     from django.contrib.auth.decorators import login_required
 
     @login_required(redirect_field_name='redirect_to')
@@ -479,7 +479,7 @@ Again, an equivalent example of the more compact decorator syntax introduced in
 
     * If the user isn't logged in, redirect to ``settings.LOGIN_URL``
       (``/accounts/login/`` by default), passing the current absolute URL
-      in the query string as ``next`` or the value of ``redirect_field_name``. 
+      in the query string as ``next`` or the value of ``redirect_field_name``.
       For example:
       ``/accounts/login/?next=/polls/3/``.
     * If the user is logged in, execute the view normally. The view code is
@@ -1119,7 +1119,7 @@ object the first time a user authenticates::
 Handling authorization in custom backends
 -----------------------------------------
 
-Custom auth backends can provide their own permissions. 
+Custom auth backends can provide their own permissions.
 
 The user model will delegate permission lookup functions
 (``get_group_permissions()``, ``get_all_permissions()``, ``has_perm()``, and
@@ -1132,9 +1132,9 @@ one backend grants.
 
 The simple backend above could implement permissions for the magic admin fairly
 simply::
-        
+
     class SettingsBackend:
-    
+
         # ...
 
         def has_perm(self, user_obj, perm):
@@ -1142,7 +1142,7 @@ simply::
                 return True
             else:
                 return False
-                
+
 This gives full permissions to the user granted access in the above example. Notice
 that the backend auth functions all take the user object as an argument, and
 they also accept the same arguments given to the associated ``User`` functions.
diff --git a/docs/contributing.txt b/docs/contributing.txt
index 37c9196467..885f5159b9 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -328,8 +328,12 @@ incorrect translation, or if you'd like to add a language that isn't yet
 translated, here's what to do:
 
     * Join the `Django i18n mailing list`_ and introduce yourself.
-    * Create and submit translations using the methods described in the
+    * Create translations using the methods described in the
       `i18n documentation`_.
+    * Create a diff of the ``.po`` file against the current Subversion trunk.
+    * Make sure that `` bin/compile-messages.py -l <lang>`` runs without
+      producing any warnings.
+    * Attach the patch to a ticket in Django's ticket system.
 
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
 .. _i18n documentation: ../i18n/
diff --git a/docs/faq.txt b/docs/faq.txt
index 3d7db36fbc..56c9536eda 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -166,7 +166,7 @@ logical to us.
 We're well aware that there are other awesome Web frameworks out there, and
 we're not averse to borrowing ideas where appropriate. However, Django was
 developed precisely because we were unhappy with the status quo, so please be
-aware that "because <Framework X>" does it is not going to be sufficient reason
+aware that "because <Framework X> does it" is not going to be sufficient reason
 to add a given feature to Django.
 
 Why did you write all of Django from scratch, instead of using other Python libraries?
diff --git a/docs/flatpages.txt b/docs/flatpages.txt
index 7c27fe8793..b6fa8e035f 100644
--- a/docs/flatpages.txt
+++ b/docs/flatpages.txt
@@ -24,11 +24,14 @@ Installation
 
 To install the flatpages app, follow these steps:
 
-    1. Add ``'django.contrib.flatpages'`` to your INSTALLED_APPS_ setting.
-    2. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
+    1. Install the `sites framework`_ by adding ``'django.contrib.sites'`` to
+       your INSTALLED_APPS_ setting, if it's not already in there.
+    2. Add ``'django.contrib.flatpages'`` to your INSTALLED_APPS_ setting.
+    3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
        to your MIDDLEWARE_CLASSES_ setting.
-    3. Run the command ``manage.py syncdb``.
+    4. Run the command ``manage.py syncdb``.
 
+.. _sites framework: ../sites/
 .. _INSTALLED_APPS: ../settings/#installed-apps
 .. _MIDDLEWARE_CLASSES: ../settings/#middleware-classes
 
diff --git a/docs/form_wizard.txt b/docs/form_wizard.txt
new file mode 100644
index 0000000000..cd9e58ded1
--- /dev/null
+++ b/docs/form_wizard.txt
@@ -0,0 +1,304 @@
+===========
+Form wizard
+===========
+
+**New in Django development version.**
+
+Django comes with an optional "form wizard" application that splits forms_
+across multiple Web pages. It maintains state in hashed HTML
+``<input type="hidden">`` fields, and the data isn't processed server-side
+until the final form is submitted.
+
+You might want to use this if you have a lengthy form that would be too
+unwieldy for display on a single page. The first page might ask the user for
+core information, the second page might ask for less important information,
+etc.
+
+The term "wizard," in this context, is `explained on Wikipedia`_.
+
+.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29
+.. _forms: ../newforms/
+
+How it works
+============
+
+Here's the basic workflow for how a user would use a wizard:
+
+    1. The user visits the first page of the wizard, fills in the form and
+       submits it.
+    2. The server validates the data. If it's invalid, the form is displayed
+       again, with error messages. If it's valid, the server calculates a
+       secure hash of the data and presents the user with the next form,
+       saving the validated data and hash in ``<input type="hidden">`` fields.
+    3. Step 1 and 2 repeat, for every subsequent form in the wizard.
+    4. Once the user has submitted all the forms and all the data has been
+       validated, the wizard processes the data -- saving it to the database,
+       sending an e-mail, or whatever the application needs to do.
+
+Usage
+=====
+
+This application handles as much machinery for you as possible. Generally, you
+just have to do these things:
+
+    1. Define a number of ``django.newforms`` ``Form`` classes -- one per wizard
+       page.
+    2. Create a ``FormWizard`` class that specifies what to do once all of your
+       forms have been submitted and validated. This also lets you override some
+       of the wizard's behavior.
+    3. Create some templates that render the forms. You can define a single,
+       generic template to handle every one of the forms, or you can define a
+       specific template for each form.
+    4. Point your URLconf at your ``FormWizard`` class.
+
+Defining ``Form`` classes
+=========================
+
+The first step in creating a form wizard is to create the ``Form`` classes.
+These should be standard ``django.newforms`` ``Form`` classes, covered in the
+`newforms documentation`_.
+
+These classes can live anywhere in your codebase, but convention is to put them
+in a file called ``forms.py`` in your application.
+
+For example, let's write a "contact form" wizard, where the first page's form
+collects the sender's e-mail address and subject, and the second page collects
+the message itself. Here's what the ``forms.py`` might look like::
+
+    from django import newforms as forms
+
+    class ContactForm1(forms.Form):
+        subject = forms.CharField(max_length=100)
+        sender = forms.EmailField()
+
+    class ContactForm2(forms.Form):
+        message = forms.CharField(widget=forms.Textarea)
+
+**Important limitation:** Because the wizard uses HTML hidden fields to store
+data between pages, you may not include a ``FileField`` in any form except the
+last one.
+
+.. _newforms documentation: ../newforms/
+
+Creating a ``FormWizard`` class
+===============================
+
+The next step is to create a ``FormWizard`` class, which should be a subclass
+of ``django.contrib.formtools.wizard.FormWizard``.
+
+As your ``Form`` classes, this ``FormWizard`` class can live anywhere in your
+codebase, but convention is to put it in ``forms.py``.
+
+The only requirement on this subclass is that it implement a ``done()`` method,
+which specifies what should happen when the data for *every* form is submitted
+and validated. This method is passed two arguments:
+
+    * ``request`` -- an HttpRequest_ object
+    * ``form_list`` -- a list of ``django.newforms`` ``Form`` classes
+
+In this simplistic example, rather than perform any database operation, the
+method simply renders a template of the validated data::
+
+    from django.shortcuts import render_to_response
+    from django.contrib.formtools.wizard import FormWizard
+
+    class ContactWizard(FormWizard):
+        def done(self, request, form_list):
+            return render_to_response('done.html', {
+                'form_data': [form.cleaned_data for form in form_list],
+            })
+
+Note that this method will be called via ``POST``, so it really ought to be a
+good Web citizen and redirect after processing the data. Here's another
+example::
+
+    from django.http import HttpResponseRedirect
+    from django.contrib.formtools.wizard import FormWizard
+
+    class ContactWizard(FormWizard):
+        def done(self, request, form_list):
+            do_something_with_the_form_data(form_list)
+            return HttpResponseRedirect('/page-to-redirect-to-when-done/')
+
+See the section "Advanced ``FormWizard`` methods" below to learn about more
+``FormWizard`` hooks.
+
+.. _HttpRequest: request_response/#httprequest-objects
+
+Creating templates for the forms
+================================
+
+Next, you'll need to create a template that renders the wizard's forms. By
+default, every form uses a template called ``forms/wizard.html``. (You can
+change this template name by overriding ``FormWizard.get_template()``, which is
+documented below. This hook also allows you to use a different template for
+each form.)
+
+This template expects the following context:
+
+    * ``step_field`` -- The name of the hidden field containing the step.
+    * ``step0`` -- The current step (zero-based).
+    * ``step`` -- The current step (one-based).
+    * ``step_count`` -- The total number of steps.
+    * ``form`` -- The ``Form`` instance for the current step (either empty or
+      with errors).
+    * ``previous_fields`` -- A string representing every previous data field,
+      plus hashes for completed forms, all in the form of hidden fields. Note
+      that you'll need to run this through the ``safe`` template filter, to
+      prevent auto-escaping, because it's raw HTML.
+
+It will also be passed any objects in ``extra_context``, which is a dictionary
+you can specify that contains extra values to add to the context. You can
+specify it in two ways:
+
+    * Set the ``extra_context`` attribute on your ``FormWizard`` subclass to a
+      dictionary.
+
+    * Pass ``extra_context`` as extra parameters in the URLconf.
+
+Here's a full example template::
+
+    {% extends "base.html" %}
+
+    {% block content %}
+    <p>Step {{ step }} of {{ step_count }}</p>
+    <form action="." method="post">
+    <table>
+    {{ form }}
+    </table>
+    <input type="hidden" name="{{ step_field }}" value="{{ step0 }}" />
+    {{ previous_fields|safe }}
+    <input type="submit">
+    </form>
+    {% endblock %}
+
+Note that ``previous_fields``, ``step_field`` and ``step0`` are all required
+for the wizard to work properly.
+
+Hooking the wizard into a URLconf
+=================================
+
+Finally, give your new ``FormWizard`` object a URL in ``urls.py``. The wizard
+takes a list of your form objects as arguments::
+
+    from django.conf.urls.defaults import *
+    from mysite.testapp.forms import ContactForm1, ContactForm2, ContactWizard
+
+    urlpatterns = patterns('',
+        (r'^contact/$', ContactWizard([ContactForm1, ContactForm2])),
+    )
+
+Advanced ``FormWizard`` methods
+===============================
+
+Aside from the ``done()`` method, ``FormWizard`` offers a few advanced method
+hooks that let you customize how your wizard works.
+
+Some of these methods take an argument ``step``, which is a zero-based counter
+representing the current step of the wizard. (E.g., the first form is ``0`` and
+the second form is ``1``.)
+
+``prefix_for_step``
+~~~~~~~~~~~~~~~~~~~
+
+Given the step, returns a ``Form`` prefix to use. By default, this simply uses
+the step itself. For more, see the `form prefix documentation`_.
+
+Default implementation::
+
+    def prefix_for_step(self, step):
+        return str(step)
+
+.. _form prefix documentation: ../newforms/#prefixes-for-forms
+
+``render_hash_failure``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Renders a template if the hash check fails. It's rare that you'd need to
+override this.
+
+Default implementation::
+
+    def render_hash_failure(self, request, step):
+        return self.render(self.get_form(step), request, step,
+            context={'wizard_error': 'We apologize, but your form has expired. Please continue filling out the form from this page.'})
+
+``security_hash``
+~~~~~~~~~~~~~~~~~
+
+Calculates the security hash for the given request object and ``Form`` instance.
+
+By default, this uses an MD5 hash of the form data and your
+`SECRET_KEY setting`_. It's rare that somebody would need to override this.
+
+Example::
+
+    def security_hash(self, request, form):
+        return my_hash_function(request, form)
+
+.. _SECRET_KEY setting: ../settings/#secret-key
+
+``parse_params``
+~~~~~~~~~~~~~~~~
+
+A hook for saving state from the request object and ``args`` / ``kwargs`` that
+were captured from the URL by your URLconf.
+
+By default, this does nothing.
+
+Example::
+
+    def parse_params(self, request, *args, **kwargs):
+        self.my_state = args[0]
+
+``get_template``
+~~~~~~~~~~~~~~~~
+
+Returns the name of the template that should be used for the given step.
+
+By default, this returns ``'forms/wizard.html'``, regardless of step.
+
+Example::
+
+    def get_template(self, step):
+        return 'myapp/wizard_%s.html' % step
+
+If ``get_template`` returns a list of strings, then the wizard will use the
+template system's ``select_template()`` function, `explained in the template docs`_.
+This means the system will use the first template that exists on the filesystem.
+For example::
+
+    def get_template(self, step):
+        return ['myapp/wizard_%s.html' % step, 'myapp/wizard.html']
+
+.. _explained in the template docs: ../templates_python/#the-python-api
+
+``render_template``
+~~~~~~~~~~~~~~~~~~~
+
+Renders the template for the given step, returning an ``HttpResponse`` object.
+
+Override this method if you want to add a custom context, return a different
+MIME type, etc. If you only need to override the template name, use
+``get_template()`` instead.
+
+The template will be rendered with the context documented in the
+"Creating templates for the forms" section above.
+
+``process_step``
+~~~~~~~~~~~~~~~~
+
+Hook for modifying the wizard's internal state, given a fully validated ``Form``
+object. The Form is guaranteed to have clean, valid data.
+
+This method should *not* modify any of that data. Rather, it might want to set
+``self.extra_context`` or dynamically alter ``self.form_list``, based on
+previously submitted forms.
+
+Note that this method is called every time a page is rendered for *all*
+submitted steps.
+
+The function signature::
+
+    def process_step(self, request, form, step):
+        # ...
diff --git a/docs/i18n.txt b/docs/i18n.txt
index 78404d4503..8da19cd242 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -547,7 +547,7 @@ following this algorithm:
 
     * First, it looks for a ``django_language`` key in the the current user's
       `session`_.
-    * Failing that, it looks for a cookie called ``django_language``.
+    * Failing that, it looks for a cookie that is named according to your ``LANGUAGE_COOKIE_NAME`` setting. (The default name is ``django_language``, and this setting is new in the Django development version. In Django version 0.96 and before, the cookie's name is hard-coded to ``django_language``.)
     * Failing that, it looks at the ``Accept-Language`` HTTP header. This
       header is sent by your browser and tells the server which language(s) you
       prefer, in order by priority. Django tries each language in the header
@@ -719,7 +719,9 @@ Activate this view by adding the following line to your URLconf::
 The view expects to be called via the ``POST`` method, with a ``language``
 parameter set in request. If session support is enabled, the view
 saves the language choice in the user's session. Otherwise, it saves the
-language choice in a ``django_language`` cookie.
+language choice in a cookie that is by default named ``django_language``.
+(The name can be changed through the ``LANGUAGE_COOKIE_NAME`` setting if you're
+using the Django development version.)
 
 After setting the language choice, Django redirects the user, following this
 algorithm:
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 66fa63e3c6..4901a9a854 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -788,10 +788,10 @@ Note, however, that this only refers to models in the same models.py file -- you
 cannot use a string to reference a model defined in another application or
 imported from elsewhere.
 
-**New in Django development version:** to refer to models defined in another
-application, you must instead explicitially specify the application label. That
-is, if the ``Manufacturer`` model above is defined in another application called
-``production``, you'd need to use::
+**New in Django development version:** To refer to models defined in another
+application, you must instead explicitly specify the application label. For
+example, if the ``Manufacturer`` model above is defined in another application
+called ``production``, you'd need to use::
 
     class Car(models.Model):
         manufacturer = models.ForeignKey('production.Manufacturer')
@@ -1022,6 +1022,8 @@ See the `One-to-one relationship model example`_ for a full example.
 Custom field types
 ------------------
 
+**New in Django development version**
+
 If one of the existing model fields cannot be used to fit your purposes, or if
 you wish to take advantage of some less common database column types, you can
 create your own field class. Full coverage of creating your own fields is
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 853fb3159e..47eaa9a769 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -226,7 +226,7 @@ For example::
 
     # Create a form instance with POST data.
     >>> a = Author()
-    >>> f = AuthorForm(a, request.POST)
+    >>> f = AuthorForm(request.POST, instance=a)
 
     # Create and save the new author instance. There's no need to do anything else.
     >>> new_author = f.save()
@@ -238,34 +238,34 @@ In some cases, you may not want all the model fields to appear on the generated
 form. There are three ways of telling ``ModelForm`` to use only a subset of the
 model fields:
 
-    1. Set ``editable=False`` on the model field. As a result, *any* form
-       created from the model via ``ModelForm`` will not include that
-       field.
+1. Set ``editable=False`` on the model field. As a result, *any* form
+   created from the model via ``ModelForm`` will not include that
+   field.
 
-    2. Use the ``fields`` attribute of the ``ModelForm``'s inner ``Meta`` class.
-       This attribute, if given, should be a list of field names to include in
-       the form.
+2. Use the ``fields`` attribute of the ``ModelForm``'s inner ``Meta``
+   class.  This attribute, if given, should be a list of field names
+   to include in the form.
 
-    3. Use the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta`` class.
-       This attribute, if given, should be a list of field names to exclude
-       the form.
+3. Use the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta``
+   class.  This attribute, if given, should be a list of field names
+   to exclude from the form.
 
-       For example, if you want a form for the ``Author`` model (defined above)
-       that includes only the ``name`` and ``title`` fields, you would specify
-       ``fields`` or  ``exclude`` like this::
+For example, if you want a form for the ``Author`` model (defined
+above) that includes only the ``name`` and ``title`` fields, you would
+specify ``fields`` or ``exclude`` like this::
 
-          class PartialAuthorForm(ModelForm):
-              class Meta:
-                  model = Author
-                  fields = ('name', 'title')
-
-          class PartialAuthorForm(ModelForm):
-              class Meta:
-                  model = Author
-                  exclude = ('birth_date',)
+    class PartialAuthorForm(ModelForm):
+        class Meta:
+            model = Author
+            fields = ('name', 'title')
+    
+    class PartialAuthorForm(ModelForm):
+        class Meta:
+            model = Author
+            exclude = ('birth_date',)
 
-        Since the Author model has only 3 fields, 'name', 'title', and
-        'birth_date', the forms above will contain exactly the same fields.
+Since the Author model has only 3 fields, 'name', 'title', and
+'birth_date', the forms above will contain exactly the same fields.
 
 .. note::
 
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 19f42cb2ee..0b5559ab88 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -243,6 +243,10 @@ object::
     >>> f.cleaned_data
     {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
 
+.. note::
+    **New in Django development version** The ``cleaned_data`` attribute was
+    called ``clean_data`` in earlier releases.
+
 Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
 always cleans the input into a Unicode string. We'll cover the encoding
 implications later in this document.
@@ -1560,7 +1564,7 @@ The three types of cleaning methods are:
 
       Note that any errors raised by your ``Form.clean()`` override will not
       be associated with any field in particular. They go into a special
-      "field" (called ``__all__``, which you can access via the
+      "field" (called ``__all__``), which you can access via the
       ``non_field_errors()`` method if you need to.
 
 These methods are run in the order given above, one field at a time.  That is,
diff --git a/docs/settings.txt b/docs/settings.txt
index 8478e0ce96..77e3c6692f 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -579,6 +579,17 @@ in standard language format. For example, U.S. English is ``"en-us"``. See the
 
 .. _internationalization docs: ../i18n/
 
+LANGUAGE_COOKIE_NAME
+--------------------
+
+**New in Django development version**
+
+Default: ``'django_language'``
+
+The name of the cookie to use for the language cookie. This can be whatever
+you want (but should be different from ``SESSION_COOKIE_NAME``). See the
+`internationalization docs`_ for details.
+
 LANGUAGES
 ---------
 
@@ -822,8 +833,8 @@ SESSION_COOKIE_NAME
 
 Default: ``'sessionid'``
 
-The name of the cookie to use for sessions. This can be whatever you want.
-See the `session docs`_.
+The name of the cookie to use for sessions. This can be whatever you want (but
+should be different from ``LANGUAGE_COOKIE_NAME``). See the `session docs`_.
 
 SESSION_COOKIE_PATH
 -------------------
diff --git a/docs/templates.txt b/docs/templates.txt
index d473a6f06f..471f44cfbf 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -1224,6 +1224,12 @@ add
 
 Adds the arg to the value.
 
+For example::
+
+    {{ value|add:2 }}
+
+If ``value`` is 4, then the output will be 6.
+
 addslashes
 ~~~~~~~~~~
 
@@ -1247,38 +1253,90 @@ cut
 
 Removes all values of arg from the given string.
 
+For example::
+
+    {{ value|cut:" "}}
+
+If ``value`` is "String with spaces", the output will be ``Stringwithspaces``.
+
 date
 ~~~~
 
 Formats a date according to the given format (same as the `now`_ tag).
 
+For example::
+
+    {{ value|date:"D d M Y" }}
+
+If ``value`` is a datetime object (ie. datetime.datetime.now()), the output
+would be formatted like ``Wed 09 Jan 2008``.
+
 default
 ~~~~~~~
 
 If value is unavailable, use given default.
 
+For example::
+
+    {{ value|default:"nothing" }}
+
+If ``value`` is ``Undefined``, the output would be ``nothing``.
+
 default_if_none
 ~~~~~~~~~~~~~~~
 
 If value is ``None``, use given default.
 
+For example::
+
+    {{ value|default_if_none:"nothing" }}
+
+If ``value`` is ``None``, the output would be ``nothing``.
+
 dictsort
 ~~~~~~~~
 
 Takes a list of dictionaries, returns that list sorted by the key given in
 the argument.
 
+For example::
+
+    {{ value|dictsort:"name" }}
+
+If ``value`` is::
+    
+    [
+        {'name': 'zed', 'age': 19}
+        {'name': 'amy', 'age': 22}, 
+        {'name': 'joe', 'age': 31}, 
+    ]
+
+then the output would be::
+
+    [
+        {'name': 'amy', 'age': 22}, 
+        {'name': 'joe', 'age': 31}, 
+        {'name': 'zed', 'age': 19}
+    ]
+
 dictsortreversed
 ~~~~~~~~~~~~~~~~
 
 Takes a list of dictionaries, returns that list sorted in reverse order by the
-key given in the argument.
+key given in the argument. This works exactly the same as the above filter, but
+the returned value will be in reverse order.
 
 divisibleby
 ~~~~~~~~~~~
 
 Returns true if the value is divisible by the argument.
 
+For example::
+
+    {{ value|divisibleby:3 }}
+
+If ``value`` is ``21``, the output would be ``True``.
+
 escape
 ~~~~~~
 
@@ -1319,16 +1377,38 @@ filesizeformat
 Format the value like a 'human-readable' file size (i.e. ``'13 KB'``,
 ``'4.1 MB'``, ``'102 bytes'``, etc).
 
+For example::
+
+    {{ value|filesizeformat }}
+
+If ``value`` is 123456789, the output would be ``117.7 MB``.
+
 first
 ~~~~~
 
 Returns the first item in a list.
 
+For example::
+
+    {{ value|first }}
+
+If ``value`` is ``['a', 'b', 'c']``, the output would be `a`.
+
 fix_ampersands
 ~~~~~~~~~~~~~~
 
 Replaces ampersands with ``&amp;`` entities.
 
+For example::
+
+    {{ value|fix_ampersands }}
+
+If ``value`` is ``Tom & Jerry``, the output would be ``Tom &amp; Jerry``.
+
+**New in Django development version**: you probably don't need to use this
+filter since ampersands will be automatically escaped. See escape_ for more on
+how auto-escaping works.
+
 floatformat
 ~~~~~~~~~~~
 
@@ -1388,6 +1468,12 @@ right-most digit, 2 is the second-right-most digit, etc. Returns the original
 value for invalid input (if input or argument is not an integer, or if argument
 is less than 1). Otherwise, output is always an integer.
 
+For example::
+    
+    {{ value|get_digit:2 }}
+
+If ``value`` is 123456789, the output would be ``8``.
+
 iriencode
 ~~~~~~~~~
 
@@ -1401,7 +1487,13 @@ It's safe to use this filter on a string that has already gone through the
 join
 ~~~~
 
-Joins a list with a string, like Python's ``str.join(list)``.
+Joins a list with a string, like Python's ``str.join(list)``
+
+For example::
+
+    {{ value|join:" // " }}
+
+If ``value`` is ``['a', 'b', 'c']``, the output would be ``a // b // c``.
 
 last
 ~~~~
@@ -1410,16 +1502,34 @@ last
 
 Returns the last item in a list.
 
+For example::
+
+    {{ value|last }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``d``.
+
 length
 ~~~~~~
 
 Returns the length of the value. Useful for lists.
 
+For example::
+
+    {{ value|length }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``4``.
+
 length_is
 ~~~~~~~~~
 
 Returns a boolean of whether the value's length is the argument.
 
+For example::
+
+    {{ value|length_is:4 }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``True``.
+
 linebreaks
 ~~~~~~~~~~
 
@@ -1427,6 +1537,13 @@ Replaces line breaks in plain text with appropriate HTML; a single
 newline becomes an HTML line break (``<br />``) and a new line
 followed by a blank line becomes a paragraph break (``</p>``).
 
+For example::
+
+    {{ value|linebreaks }}
+
+If ``value`` is ``Joel\nis a slug``, the output would be ``<p>Joe<br>is a
+slug</p>``.
+
 linebreaksbr
 ~~~~~~~~~~~~
 
@@ -1450,12 +1567,25 @@ lower
 
 Converts a string into all lowercase.
 
+For example::
+
+    {{ value|lower }}
+
+If ``value`` is ``Joel Is a Slug``, the output would be ``joel is a slug``.
+
 make_list
 ~~~~~~~~~
 
 Returns the value turned into a list. For an integer, it's a list of
 digits. For a string, it's a list of characters.
 
+For example::
+
+    {{ value|make_list }}
+
+If ``value`` is "Joe", the output would be ``[u'J', u'o', u'e']. If ``value`` is
+123, the output would be ``[1, 2, 3]``.
+
 phone2numeric
 ~~~~~~~~~~~~~
 
@@ -1492,18 +1622,33 @@ Example::
 pprint
 ~~~~~~
 
-A wrapper around pprint.pprint -- for debugging, really.
+A wrapper around `pprint.pprint`__ -- for debugging, really.
+
+__ http://www.python.org/doc/2.5/lib/module-pprint.html
 
 random
 ~~~~~~
 
 Returns a random item from the list.
 
+For example::
+
+    {{ value|random }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output could be ``b``.
+
 removetags
 ~~~~~~~~~~
 
 Removes a space separated list of [X]HTML tags from the output.
 
+For example::
+
+    {{ value|removetags:"b span"|safe }}
+
+If ``value`` is ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the
+output would be ``Joel <button>is</button> a slug``.
+
 rjust
 ~~~~~
 
@@ -1535,6 +1680,12 @@ Converts to lowercase, removes non-word characters (alphanumerics and
 underscores) and converts spaces to hyphens. Also strips leading and trailing
 whitespace.
 
+For example::
+
+    {{ value|slugify }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``joel-is-a-slug``.
+
 stringformat
 ~~~~~~~~~~~~
 
@@ -1545,11 +1696,24 @@ the leading "%" is dropped.
 See http://docs.python.org/lib/typesseq-strings.html for documentation of
 Python string formatting
 
+For example::
+
+    {{ value|stringformat:"s" }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``Joel is a slug``.
+
 striptags
 ~~~~~~~~~
 
 Strips all [X]HTML tags.
 
+For example::
+
+    {{ value|striptags }}
+
+If ``value`` is ``<b>Joel</b> <button>is</button> a <span>slug</span>`` the
+output would be ``Joel is a slug``.
+
 time
 ~~~~
 
@@ -1558,6 +1722,13 @@ The time filter will only accept parameters in the format string that relate
 to the time of day, not the date (for obvious reasons). If you need to
 format a date, use the `date`_ filter.
 
+For example::
+
+    {{ value|time:"H:i" }}
+
+If ``value`` is ``datetime.datetime.now()``, the output would be formatted
+like ``01:23``.
+
 timesince
 ~~~~~~~~~
 
@@ -1599,6 +1770,12 @@ Truncates a string after a certain number of words.
 
 **Argument:** Number of words to truncate after
 
+For example::
+
+    {{ value|truncatewords:2 }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``Joel is ...``.
+
 truncatewords_html
 ~~~~~~~~~~~~~~~~~~
 
@@ -1644,6 +1821,12 @@ upper
 
 Converts a string into all uppercase.
 
+For example::
+
+    {{ value|upper }}
+
+If ``value`` is ``Joel is a slug``, the output would be ``JOEL IS A SLUG``.
+
 urlencode
 ~~~~~~~~~
 
@@ -1657,6 +1840,14 @@ Converts URLs in plain 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.
 
+For example::
+
+    {{ value|urlize }}
+
+If ``value`` is ``Check out www.djangoproject.com``, the output would be
+``Check out <a
+href="http://www.djangoproject.com">www.djangoproject.com</a>``.
+
 urlizetrunc
 ~~~~~~~~~~~
 
@@ -1667,6 +1858,14 @@ As with urlize_, this filter should only be applied to *plain* text.
 
 **Argument:** Length to truncate URLs to
 
+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>``.
+
 wordcount
 ~~~~~~~~~
 
@@ -1679,6 +1878,16 @@ Wraps words at specified line length.
 
 **Argument:** number of characters at which to wrap the text
 
+For example::
+
+    {{ value|wordwrap:5 }}
+
+If ``value`` is ``Joel is a slug``, the output would be::
+
+    Joel
+    is a
+    slug
+
 yesno
 ~~~~~
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index c6e9223e9f..43ef016ed4 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -629,9 +629,10 @@ the given Python module name, not the name of the app.
 Once you've created that Python module, you'll just have to write a bit of
 Python code, depending on whether you're writing filters or tags.
 
-To be a valid tag library, the module contain a module-level variable named
-``register`` that is a ``template.Library`` instance, in which all the tags and
-filters are registered. So, near the top of your module, put the following::
+To be a valid tag library, the module must contain a module-level variable
+named ``register`` that is a ``template.Library`` instance, in which all the
+tags and filters are registered. So, near the top of your module, put the
+following::
 
     from django import template
 
@@ -983,7 +984,7 @@ Notes:
       exception. It should fail silently, just as template filters should.
 
 Ultimately, this decoupling of compilation and rendering results in an
-efficient template system, because a template can render multiple context
+efficient template system, because a template can render multiple contexts
 without having to be parsed multiple times.
 
 Auto-escaping considerations