gis: Merged revisions 7280-7353 via svnmerge from trunk.

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

15 files changed, 405 insertions, 110 deletions

diff --git a/docs/custom_model_fields.txt b/docs/custom_model_fields.txt
index 923b331a95..2b344921ef 100644
--- a/docs/custom_model_fields.txt
+++ b/docs/custom_model_fields.txt
@@ -401,8 +401,8 @@ For example::
         # ...
 
         def get_db_prep_save(self, value):
-            return ''.join([''.join(l) for l in (self.north,
-                    self.east, self.south, self.west)])
+            return ''.join([''.join(l) for l in (value.north,
+                    value.east, value.south, value.west)])
 
 ``pre_save(self, model_instance, add)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 80f8a2d60b..e9b5c05f6b 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -1372,7 +1372,7 @@ equivalent::
     Entry.objects.filter(blog__pk=3) # __pk implies __id__exact
 
 Lookups that span relationships
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 Django offers a powerful and intuitive way to "follow" relationships in
 lookups, taking care of the SQL ``JOIN``\s for you automatically, behind the
@@ -1396,7 +1396,7 @@ whose ``headline`` contains ``'Lennon'``::
     Blog.objects.filter(entry__headline__contains='Lennon')
 
 Escaping percent signs and underscores in LIKE statements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------
 
 The field lookups that equate to ``LIKE`` SQL statements (``iexact``,
 ``contains``, ``icontains``, ``startswith``, ``istartswith``, ``endswith``
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 17187894c0..b7beb0b4be 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -751,6 +751,19 @@ In addition to ``extra_context``, the template's context will be:
 
 If the results are paginated, the context will contain these extra variables:
 
+    * **New in Django development version:** ``paginator``: An instance of
+      ``django.core.paginator.Paginator``.
+
+    * **New in Django development version:** ``page_obj``: An instance of
+      ``django.core.paginator.Page``.
+
+In older versions of Django, before ``paginator`` and ``page_obj`` were added
+to this template's context, the template included several other variables
+related to pagination. Note that you should *NOT* use these variables anymore;
+use ``paginator`` and ``page_obj`` instead, because they let you do everything
+these old variables let you do (and more!). But for legacy installations,
+here's a list of those old template variables:
+
     * ``results_per_page``: The number of objects per page. (Same as the
       ``paginate_by`` parameter.)
 
@@ -777,8 +790,8 @@ If the results are paginated, the context will contain these extra variables:
     * ``hits``: The total number of objects across *all* pages, not just this
       page.
 
-    * **New in Django development version:** ``page_range``: A list of the 
-      page numbers that are available. This is 1-based.
+    * ``page_range``: A list of the page numbers that are available. This is
+      1-based.
 
 Notes on pagination
 ~~~~~~~~~~~~~~~~~~~
diff --git a/docs/install.txt b/docs/install.txt
index 542036e2af..341c4280e8 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -167,6 +167,20 @@ These commands will install Django in your Python installation's
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. admonition:: Tracking Django development
+    
+    If you decide to use the latest development version of Django,
+    you'll want to pay close attention to `the development timeline`_,
+    and you'll want to keep an eye on `the list of
+    backwards-incompatible changes`_; this will help you stay on top
+    of any new features you might want to use, as well as any changes
+    you'll need to make to your code when updating your copy of Django
+    (for stable releases, any necessary changes are documented in the
+    release notes).
+
+.. _the development timeline: http://code.djangoproject.com/timeline
+.. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
+
 If you'd like to be able to update your Django code occasionally with the
 latest bug fixes and improvements, follow these instructions:
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 4901a9a854..f73c5aadf7 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -626,7 +626,8 @@ option is ignored.
 ``default``
 ~~~~~~~~~~~
 
-The default value for the field.
+The default value for the field. This can be a value or a callable object. If
+callable it will be called every time a new object is created.
 
 ``editable``
 ~~~~~~~~~~~~
@@ -1788,14 +1789,15 @@ For example::
 This example allows you to request ``Person.men.all()``, ``Person.women.all()``,
 and ``Person.people.all()``, yielding predictable results.
 
-If you use custom ``Manager`` objects, take note that the first ``Manager``
-Django encounters (in order by which they're defined in the model) has a
-special status. Django interprets the first ``Manager`` defined in a class as
-the "default" ``Manager``. Certain operations -- such as Django's admin site --
-use the default ``Manager`` to obtain lists of objects, so it's generally a
-good idea for the first ``Manager`` to be relatively unfiltered. In the last
-example, the ``people`` ``Manager`` is defined first -- so it's the default
-``Manager``.
+If you use custom ``Manager`` objects, take note that the first
+``Manager`` Django encounters (in the order in which they're defined
+in the model) has a special status. Django interprets this first
+``Manager`` defined in a class as the "default" ``Manager``, and
+several parts of Django (though not the admin application) will use
+that ``Manager`` exclusively for that model. As a result, it's often a
+good idea to be careful in your choice of default manager, in order to
+avoid a situation where overriding of ``get_query_set()`` results in
+an inability to retrieve objects you'd like to work with.
 
 Model methods
 =============
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index 47eaa9a769..05f9b1b3d4 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -231,6 +231,16 @@ For example::
     # Create and save the new author instance. There's no need to do anything else.
     >>> new_author = f.save()
 
+Other than the ``save()`` and ``save_m2m()`` methods, a ``ModelForm``
+works exactly the same way as any other ``newforms`` form. For
+example, the ``is_valid()`` method is used to check for validity, the
+``is_multipart()`` method is used to determine whether a form requires
+multipart file upload (and hence whether ``request.FILES`` must be
+passed to the form), etc.; see `the standard newforms documentation`_
+for more information.
+
+.. _the standard newforms documentation: ../newforms/
+
 Using a subset of fields on the form
 ------------------------------------
 
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 0b5559ab88..533ff75185 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1333,13 +1333,14 @@ given length.
 
 An ``UploadedFile`` object has two attributes:
 
-    ======================  =====================================================
-    Argument                Description
-    ======================  =====================================================
+    ======================  ====================================================
+    Attribute               Description
+    ======================  ====================================================
     ``filename``            The name of the file, provided by the uploading
                             client.
+                            
     ``content``             The array of bytes comprising the file content.
-    ======================  =====================================================
+    ======================  ====================================================
 
 The string representation of an ``UploadedFile`` is the same as the filename
 attribute.
@@ -1349,6 +1350,38 @@ When you use a ``FileField`` on a form, you must also remember to
 
 .. _`bind the file data to the form`: `Binding uploaded files to a form`_
 
+``FilePathField``
+~~~~~~~~~~~~~~~~~
+
+**New in Django development version**
+
+    * Default widget: ``Select``
+    * Empty value: ``None``
+    * Normalizes to: A unicode object
+    * Validates that the selected choice exists in the list of choices.
+    * Error message keys: ``required``, ``invalid_choice``
+
+The field allows choosing from files inside a certain directory. It takes three
+extra arguments:
+
+    ==============  ==========  ===============================================
+    Argument        Required?   Description
+    ==============  ==========  ===============================================
+    ``path``        Yes         The absolute path to the directory whose 
+                                contents you want listed. This directory must 
+                                exist.
+                            
+    ``recursive``   No          If ``False`` (the default) only the direct
+                                contents of ``path`` will be offered as choices.
+                                If ``True``, the directory will be descended
+                                into recursively and all descendants will be
+                                listed as choices.
+                                
+    ``match``       No          A regular expression pattern; only files with
+                                names matching this expression will be allowed
+                                as choices.
+    ==============  ==========  ===============================================
+
 ``ImageField``
 ~~~~~~~~~~~~~~
 
@@ -1499,6 +1532,41 @@ the bottom of this document, for examples of their use.
 ``SplitDateTimeField``
 ~~~~~~~~~~~~~~~~~~~~~~
 
+Fields which handle relationships
+---------------------------------
+
+For representing relationships between models, two fields are
+provided which can derive their choices from a ``QuerySet``, and which
+place one or more model objects into the ``cleaned_data`` dictionary
+of forms in which they're used. Both of these fields have an
+additional required argument:
+
+``queryset``
+    A ``QuerySet`` of model objects from which the choices for the
+    field will be derived, and which will be used to validate the
+    user's selection.
+
+``ModelChoiceField``
+~~~~~~~~~~~~~~~~~~~~
+
+Allows the selection of a single model object, suitable for representing a
+foreign key. The method receives an object as an argument and must return a
+string to represent it.
+
+The labels for the choice field call the ``__unicode__`` method of the model to
+generate string representations. To provide custom labels, subclass ``ModelChoiceField`` and override ``label_for_model``::
+
+    class MyModelChoiceField(ModelChoiceField):
+        def label_from_instance(self, obj):
+            return "My Object #%i" % obj.id
+
+``ModelMultipleChoiceField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows the selection of one or more model objects, suitable for representing a
+many-to-many relation. As with ``ModelChoiceField``, you can use
+``label_from_instance`` to customize the object labels.
+
 Creating custom fields
 ----------------------
 
@@ -1569,9 +1637,9 @@ The three types of cleaning methods are:
 
 These methods are run in the order given above, one field at a time.  That is,
 for each field in the form (in the order they are declared in the form
-definition), the ``Field.clean()`` method (or it's override) is run, then
+definition), the ``Field.clean()`` method (or its override) is run, then
 ``clean_<fieldname>()``. Finally, once those two methods are run for every
-field, the ``Form.clean()`` method, or it's override, is executed.
+field, the ``Form.clean()`` method, or its override, is executed.
 
 As mentioned above, any of these methods can raise a ``ValidationError``. For
 any field, if the ``Field.clean()`` method raises a ``ValidationError``, any
@@ -1693,7 +1761,7 @@ For example, take the following simple form::
         comment = forms.CharField()
 
 This form will include three default TextInput widgets, with default rendering -
-no CSS class, no extra attributes. This means that the inputs boxes provided for
+no CSS class, no extra attributes. This means that the input boxes provided for
 each widget will be rendered exactly the same::
 
     >>> f = CommentForm(auto_id=False)
diff --git a/docs/pagination.txt b/docs/pagination.txt
new file mode 100644
index 0000000000..486c92264b
--- /dev/null
+++ b/docs/pagination.txt
@@ -0,0 +1,133 @@
+==========
+Pagination
+==========
+
+**New in Django development version**
+
+Django provides a few classes that help you manage paginated data -- that is,
+data that's split across several pages, with "Previous/Next" links. These
+classes live in the module ``django/core/paginator.py``.
+
+Example
+=======
+
+Give ``Paginator`` a list of objects, plus the number of items you'd like to
+have on each page, and it gives you methods for accessing the items for each
+page::
+
+    >>> from django.core.paginator import Paginator
+    >>> objects = ['john', 'paul', 'george', 'ringo']
+    >>> p = Paginator(objects, 2)
+
+    >>> p.count
+    4
+    >>> p.num_pages
+    2
+    >>> p.page_range
+    [1, 2]
+
+    >>> page1 = p.page(1)
+    >>> page1
+    <Page 1 of 2>
+    >>> page1.object_list
+    ['john', 'paul']
+
+    >>> page2 = p.page(2)
+    >>> page2.object_list
+    ['george', 'ringo']
+    >>> page2.has_next()
+    False
+    >>> page2.has_previous()
+    True
+    >>> page2.has_other_pages()
+    True
+    >>> page2.next_page_number()
+    3
+    >>> page2.previous_page_number()
+    1
+    >>> page2.start_index() # The 1-based index of the first item on this page
+    3
+    >>> page2.end_index() # The 1-based index of the last item on this page
+    4
+
+    >>> p.page(0)
+    Traceback (most recent call last):
+    ...
+    InvalidPage
+    >>> p.page(3)
+    Traceback (most recent call last):
+    ...
+    InvalidPage
+
+``Paginator`` objects
+=====================
+
+Methods
+-------
+
+``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
+Raises ``InvalidPage`` if the given page number doesn't exist.
+
+Attributes
+----------
+
+``count`` -- The total number of objects, across all pages.
+
+``num_pages`` -- The total number of pages.
+
+``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
+
+``Page`` objects
+================
+
+Methods
+-------
+
+``has_next()`` -- Returns ``True`` if there's a next page.
+
+``has_previous()`` -- Returns ``True`` if there's a previous page.
+
+``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page.
+
+``next_page_number()`` -- Returns the next page number. Note that this is
+"dumb" and will return the next page number regardless of whether a subsequent
+page exists.
+
+``previous_page_number()`` -- Returns the previous page number. Note that this
+is "dumb" and will return the previous page number regardless of whether a
+previous page exists.
+
+``start_index()`` -- Returns the 1-based index of the first object on the page,
+relative to all of the objects in the paginator's list. For example, when
+paginating a list of 5 objects with 2 objects per page, the second page's
+``start_index()`` would return ``3``.
+
+``end_index()`` -- Returns the 1-based index of the last object on the page,
+relative to all of the objects in the paginator's list. For example, when
+paginating a list of 5 objects with 2 objects per page, the second page's
+``end_index()`` would return ``4``.
+
+Attributes
+----------
+
+``object_list`` -- The list of objects on this page.
+
+``number`` -- The 1-based page number for this page.
+
+``paginator`` -- The associated ``Paginator`` object.
+
+``QuerySetPaginator`` objects
+=============================
+
+Use ``QuerySetPaginator`` instead of ``Paginator`` if you're paginating across
+a ``QuerySet`` from Django's database API. This is slightly more efficient, and
+there are no API differences between the two classes.
+
+The legacy ``ObjectPaginator`` class
+====================================
+
+The ``Paginator`` and ``Page`` classes are new in the Django development
+version, as of revision 7306. In previous versions, Django provided an
+``ObjectPaginator`` class that offered similar functionality but wasn't as
+convenient. This class still exists, for backwards compatibility, but Django
+now issues a ``DeprecationWarning`` if you try to use it.
diff --git a/docs/request_response.txt b/docs/request_response.txt
index e50cfc5ea3..0e0f046a2d 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -141,6 +141,16 @@ All attributes except ``session`` should be considered read-only.
     The raw HTTP POST data. This is only useful for advanced processing. Use
     ``POST`` instead.
 
+``urlconf``
+    Not defined by Django itself, but will be read if other code
+    (e.g., a custom middleware class) sets it; when present, this will
+    be used as the root URLConf for the current request, overriding
+    the ``ROOT_URLCONF`` setting. See `How Django processes a
+    request`_ for details.
+
+.. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
+
+
 Methods
 -------
 
@@ -189,6 +199,23 @@ Methods
    Returns ``True`` if the request is secure; that is, if it was made with
    HTTPS.
 
+``is_ajax()``
+   **New in Django development version**
+
+   Returns ``True`` if the request was made via an XMLHttpRequest by checking
+   the ``HTTP_X_REQUESTED_WITH`` header for the string *'XMLHttpRequest'*. The
+   following major Javascript libraries all send this header:
+
+   * jQuery
+   * Dojo
+   * MochiKit
+   * MooTools
+   * Prototype
+   * YUI
+
+   If you write your own XMLHttpRequest call (on the browser side), you will
+   have to set this header manually to use this method.
+
 QueryDict objects
 -----------------
 
diff --git a/docs/sessions.txt b/docs/sessions.txt
index 6355524d2e..d8bac5b8d4 100644
--- a/docs/sessions.txt
+++ b/docs/sessions.txt
@@ -48,10 +48,10 @@ Using file-based sessions
 To use file-based sessions, set the ``SESSION_ENGINE`` setting to
 ``"django.contrib.sessions.backends.file"``.
 
-You might also want to set the ``SESSION_FILE_PATH`` setting (which
-defaults to ``/tmp``) to control where Django stores session files. Be
-sure to check that your Web server has permissions to read and write to
-this location.
+You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults
+to output from ``tempfile.gettempdir()``, most likely  ``/tmp``) to control
+where Django stores session files. Be sure to check that your Web server has
+permissions to read and write to this location.
 
 Using cache-based sessions
 --------------------------
diff --git a/docs/settings.txt b/docs/settings.txt
index 77e3c6692f..fb2e04f1ea 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -185,8 +185,11 @@ ADMIN_MEDIA_PREFIX
 
 Default: ``'/media/'``
 
-The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
-a trailing slash.
+The URL prefix for admin media -- CSS, JavaScript and images used by
+the Django administrative interface. Make sure to use a trailing
+slash, and to have this be different from the ``MEDIA_URL`` setting
+(since the same URL cannot be mapped onto two different sets of
+files).
 
 ADMINS
 ------
@@ -754,7 +757,9 @@ ROOT_URLCONF
 Default: Not defined
 
 A string representing the full Python import path to your root URLconf. For example:
-``"mydjangoapps.urls"``. See `How Django processes a request`_.
+``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
+setting the attribute ``urlconf`` on the incoming ``HttpRequest``
+object. See `How Django processes a request`_ for details.
 
 .. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
 
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index ebd6af26f8..f86acfe54d 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -245,6 +245,13 @@ request to the URL ``/rss/beats/0613/``:
       subclass of ``ObjectDoesNotExist``. Raising ``ObjectDoesNotExist`` in
       ``get_object()`` tells Django to produce a 404 error for that request.
 
+      **New in Django development version:** The ``get_object()`` method also
+      has a chance to handle the ``/rss/beats/`` url.  In this case, ``bits``
+      will be an empty list. In our example, ``len(bits) != 1`` and an
+      ``ObjectDoesNotExist`` exception will be raised, so ``/rss/beats/`` will
+      generate a 404 page. But you can handle this case however you like.  For
+      example you could generate a combined feed for all beats.
+
     * To generate the feed's ``<title>``, ``<link>`` and ``<description>``,
       Django uses the ``title()``, ``link()`` and ``description()`` methods. In
       the previous example, they were simple string class attributes, but this
diff --git a/docs/templates.txt b/docs/templates.txt
index 471f44cfbf..ea9f3fb6b2 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -429,8 +429,9 @@ all block tags. For example::
     # base.html
 
     {% autoescape off %}
-    <h1>{% block title %}</h1>
+    <h1>{% block title %}{% endblock %}</h1>
     {% block content %}
+    {% endblock %}
     {% endautoescape %}
 
 
@@ -438,10 +439,11 @@ all block tags. For example::
 
     {% extends "base.html" %}
     {% block title %}This & that{% endblock %}
-    {% block content %}<b>Hello!</b>{% endblock %}
+    {% block content %}{{ greeting }}{% endblock %}
 
 Because auto-escaping is turned off in the base template, it will also be
-turned off in the child template, resulting in the following rendered HTML::
+turned off in the child template, resulting in the following rendered
+HTML when the ``greeting`` variable contains the string ``<b>Hello!</b>``::
 
     <h1>This & that</h1>
     <b>Hello!</b>
@@ -1222,20 +1224,20 @@ Built-in filter reference
 add
 ~~~
 
-Adds the arg to the value.
+Adds the argument to the value.
 
 For example::
 
-    {{ value|add:2 }}
+    {{ value|add:"2" }}
 
-If ``value`` is 4, then the output will be 6.
+If ``value`` is ``4``, then the output will be ``6``.
 
 addslashes
 ~~~~~~~~~~
 
 Adds slashes before quotes. Useful for escaping strings in CSV, for example.
 
-**New in Django development version**: for escaping data in JavaScript strings,
+**New in Django development version**: For escaping data in JavaScript strings,
 use the `escapejs`_ filter instead.
 
 capfirst
@@ -1257,7 +1259,7 @@ For example::
 
     {{ value|cut:" "}}
 
-If ``value`` is "String with spaces", the output will be ``Stringwithspaces``.
+If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``.
 
 date
 ~~~~
@@ -1268,35 +1270,40 @@ 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``.
+If ``value`` is a ``datetime`` object (e.g., the result of
+``datetime.datetime.now()``), the output will be the string
+``'Wed 09 Jan 2008'``.
 
 default
 ~~~~~~~
 
-If value is unavailable, use given default.
+If value evaluates to ``False``, use given default. Otherwise, use the value.
 
 For example::
 
     {{ value|default:"nothing" }}
 
-If ``value`` is ``Undefined``, the output would be ``nothing``.
+If ``value`` is ``""`` (the empty string), the output will be ``nothing``.
 
 default_if_none
 ~~~~~~~~~~~~~~~
 
-If value is ``None``, use given default.
+If (and only if) value is ``None``, use given default. Otherwise, use the
+value.
+
+Note that if an empty string is given, the default value will *not* be used.
+Use the ``default`` filter if you want to fallback for empty strings.
 
 For example::
 
     {{ value|default_if_none:"nothing" }}
 
-If ``value`` is ``None``, the output would be ``nothing``.
+If ``value`` is ``None``, the output will be the string ``"nothing"``.
 
 dictsort
 ~~~~~~~~
 
-Takes a list of dictionaries, returns that list sorted by the key given in
+Takes a list of dictionaries and returns that list sorted by the key given in
 the argument.
 
 For example::
@@ -1304,46 +1311,42 @@ For example::
     {{ value|dictsort:"name" }}
 
 If ``value`` is::
-    
+
     [
-        {'name': 'zed', 'age': 19}
-        {'name': 'amy', 'age': 22}, 
-        {'name': 'joe', 'age': 31}, 
+        {'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}
+        {'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. This works exactly the same as the above filter, but
-the returned value will be in reverse order.
+Takes a list of dictionaries and returns that list sorted in reverse order by
+the 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.
+Returns ``True`` if the value is divisible by the argument.
 
 For example::
 
-    {{ value|divisibleby:3 }}
+    {{ value|divisibleby:"3" }}
 
 If ``value`` is ``21``, the output would be ``True``.
 
 escape
 ~~~~~~
 
-**New in Django development version:** The behaviour of this filter has
-changed slightly in the development version (the affects are only applied
-once, after all other filters).
-
 Escapes a string's HTML. Specifically, it makes these replacements:
 
     * ``<`` is converted to ``&lt;``
@@ -1362,6 +1365,10 @@ applied to the result will only result in one round of escaping being done. So
 it is safe to use this function even in auto-escaping environments. If you want
 multiple escaping passes to be applied, use the ``force_escape`` filter.
 
+**New in Django development version:** Due to auto-escaping, the behavior of
+this filter has changed slightly. The replacements are only made once, after
+all other filters are applied -- including filters before and after it.
+
 escapejs
 ~~~~~~~~
 
@@ -1392,7 +1399,7 @@ For example::
 
     {{ value|first }}
 
-If ``value`` is ``['a', 'b', 'c']``, the output would be `a`.
+If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``.
 
 fix_ampersands
 ~~~~~~~~~~~~~~
@@ -1403,11 +1410,11 @@ For example::
 
     {{ value|fix_ampersands }}
 
-If ``value`` is ``Tom & Jerry``, the output would be ``Tom &amp; Jerry``.
+If ``value`` is ``Tom & Jerry``, the output will 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.
+**New in Django development version**: This filter generally is no longer
+useful, because ampersands are automatically escaped in templates. See escape_
+for more on how auto-escaping works.
 
 floatformat
 ~~~~~~~~~~~
@@ -1463,16 +1470,16 @@ filter.
 get_digit
 ~~~~~~~~~
 
-Given a whole number, returns the requested digit of it, where 1 is the
-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.
+Given a whole number, returns the requested digit, where 1 is the 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``.
+    {{ value|get_digit:"2" }}
+
+If ``value`` is ``123456789``, the output will be ``8``.
 
 iriencode
 ~~~~~~~~~
@@ -1493,7 +1500,8 @@ For example::
 
     {{ value|join:" // " }}
 
-If ``value`` is ``['a', 'b', 'c']``, the output would be ``a // b // c``.
+If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string
+``"a // b // c"``.
 
 last
 ~~~~
@@ -1506,29 +1514,30 @@ For example::
 
     {{ value|last }}
 
-If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``d``.
+If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string
+``"d"``.
 
 length
 ~~~~~~
 
-Returns the length of the value. Useful for lists.
+Returns the length of the value. This works for both strings and lists.
 
 For example::
 
     {{ value|length }}
 
-If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``4``.
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
 
 length_is
 ~~~~~~~~~
 
-Returns a boolean of whether the value's length is the argument.
+Returns ``True`` if the value's length is the argument, or ``False`` otherwise.
 
 For example::
 
-    {{ value|length_is:4 }}
+    {{ value|length_is:"4" }}
 
-If ``value`` is ``['a', 'b', 'c', 'd']``, the output would be ``True``.
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``.
 
 linebreaks
 ~~~~~~~~~~
@@ -1541,7 +1550,7 @@ For example::
 
     {{ value|linebreaks }}
 
-If ``value`` is ``Joel\nis a slug``, the output would be ``<p>Joe<br>is a
+If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joe<br>is a
 slug</p>``.
 
 linebreaksbr
@@ -1571,7 +1580,7 @@ For example::
 
     {{ value|lower }}
 
-If ``value`` is ``Joel Is a Slug``, the output would be ``joel is a slug``.
+If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``.
 
 make_list
 ~~~~~~~~~
@@ -1583,8 +1592,9 @@ 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]``.
+If ``value`` is the string ``"Joe"``, the output would be the list
+``[u'J', u'o', u'e']``. If ``value`` is ``123``, the output will be the list
+``[1, 2, 3]``.
 
 phone2numeric
 ~~~~~~~~~~~~~
@@ -1629,25 +1639,25 @@ __ http://www.python.org/doc/2.5/lib/module-pprint.html
 random
 ~~~~~~
 
-Returns a random item from the list.
+Returns a random item from the given list.
 
 For example::
 
     {{ value|random }}
 
-If ``value`` is ``['a', 'b', 'c', 'd']``, the output could be ``b``.
+If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``.
 
 removetags
 ~~~~~~~~~~
 
-Removes a space separated list of [X]HTML tags from the output.
+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``.
+If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
+output will be ``"Joel <button>is</button> a slug"``.
 
 rjust
 ~~~~~
@@ -1684,7 +1694,7 @@ For example::
 
     {{ value|slugify }}
 
-If ``value`` is ``Joel is a slug``, the output would be ``joel-is-a-slug``.
+If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
 
 stringformat
 ~~~~~~~~~~~~
@@ -1700,7 +1710,7 @@ For example::
 
     {{ value|stringformat:"s" }}
 
-If ``value`` is ``Joel is a slug``, the output would be ``Joel is a slug``.
+If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``.
 
 striptags
 ~~~~~~~~~
@@ -1711,8 +1721,8 @@ 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``.
+If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the
+output will be ``"Joel is a slug"``.
 
 time
 ~~~~
@@ -1726,13 +1736,13 @@ For example::
 
     {{ value|time:"H:i" }}
 
-If ``value`` is ``datetime.datetime.now()``, the output would be formatted
-like ``01:23``.
+If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be
+the string ``"01:23"``.
 
 timesince
 ~~~~~~~~~
 
-Formats a date as the time since that date (i.e. "4 days, 6 hours").
+Formats a date as the time since that date (e.g., "4 days, 6 hours").
 
 Takes an optional argument that is a variable containing the date to use as
 the comparison point (without the argument, the comparison point is *now*).
@@ -1774,7 +1784,7 @@ For example::
 
     {{ value|truncatewords:2 }}
 
-If ``value`` is ``Joel is a slug``, the output would be ``Joel is ...``.
+If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``.
 
 truncatewords_html
 ~~~~~~~~~~~~~~~~~~
@@ -1792,10 +1802,8 @@ unordered_list
 Recursively takes a self-nested list and returns an HTML unordered list --
 WITHOUT opening and closing <ul> tags.
 
-**Changed in Django development version**
-
-The format accepted by ``unordered_list`` has changed to an easier to
-understand format.
+**New in Django development version:** The format accepted by
+``unordered_list`` has changed to be easier to understand.
 
 The list is assumed to be in the proper format. For example, if ``var`` contains
 ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
@@ -1825,7 +1833,7 @@ For example::
 
     {{ value|upper }}
 
-If ``value`` is ``Joel is a slug``, the output would be ``JOEL IS A SLUG``.
+If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``.
 
 urlencode
 ~~~~~~~~~
@@ -1844,9 +1852,9 @@ 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>``.
+If ``value`` is ``"Check out www.djangoproject.com"``, the output will be
+``"Check out <a
+href="http://www.djangoproject.com">www.djangoproject.com</a>"``.
 
 urlizetrunc
 ~~~~~~~~~~~
@@ -1862,9 +1870,9 @@ 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>``.
+If ``value`` is ``"Check out www.djangoproject.com"``, the output would be
+``'Check out <a
+href="http://www.djangoproject.com">www.djangopr...</a>'``.
 
 wordcount
 ~~~~~~~~~
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index bd16fa2924..473fba1ef8 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -37,6 +37,12 @@ A quick rundown:
       form will alter data server-side. Whenever you create a form that alters
       data server-side, use ``method="post"``. This tip isn't specific to
       Django; it's just good Web development practice.
+    
+    * ``forloop.counter`` indicates how many times the ``for`` tag has
+      gone through its loop; for more information, see `the
+      documentation for the "for" tag`_.
+
+.. _the documentation for the "for" tag: ../templates/#for
 
 Now, let's create a Django view that handles the submitted data and does
 something with it. Remember, in `Tutorial 3`_, we created a URLconf for the
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 789399de8d..053ee954a3 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -32,9 +32,11 @@ How Django processes a request
 When a user requests a page from your Django-powered site, this is the
 algorithm the system follows to determine which Python code to execute:
 
-    1. Django looks at the ``ROOT_URLCONF`` setting in your `settings file`_.
-       This should be a string representing the full Python import path to your
-       URLconf. For example: ``"mydjangoapps.urls"``.
+    1. Django determines the root URLConf module to use; ordinarily
+       this is the value of the ``ROOT_URLCONF`` setting in your
+       `settings file`_, but if the incoming ``HttpRequest`` object
+       has an attribute called ``urlconf``, its value will be used in
+       place of the ``ROOT_URLCONF`` setting.
     2. Django loads that Python module and looks for the variable
        ``urlpatterns``. This should be a Python list, in the format returned by
        the function ``django.conf.urls.defaults.patterns()``.