newforms-admin: Merged from trunk up to [7232]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7233 bcc190cf-cafb-0310-a4f2-bffc1f526a37

15 files changed, 110 insertions, 78 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index 4d45fd9836..212e17ac62 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
@@ -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/db-api.txt b/docs/db-api.txt
index adca8b4d5c..80f8a2d60b 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -1605,8 +1605,7 @@ the cache of all one-to-many relationships ahead of time. Example::
     print e.blog  # Doesn't hit the database; uses cached version.
     print e.blog  # Doesn't hit the database; uses cached version.
 
-``select_related()`` is documented in the "QuerySet methods that return new
-QuerySets" section above.
+``select_related()`` is documented in the `QuerySet methods that return new QuerySets`_ section above.
 
 Backward
 ~~~~~~~~
diff --git a/docs/faq.txt b/docs/faq.txt
index cef0508562..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?
@@ -353,7 +353,7 @@ How do I install mod_python on Windows?
       working`_.
 
 .. _`win32 build of mod_python for Python 2.4`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24
-.. _`Django on Windows howto`: http://thinkhole.org/wp/2006/04/03/django-on-windows-howto/
+.. _`Django on Windows howto`: http://thinkhole.org/wp/django-on-windows/
 .. _`Running mod_python on Apache on Windows2000`: http://groups-beta.google.com/group/comp.lang.python/msg/139af8c83a5a9d4f
 .. _`guide to getting mod_python working`: http://www.dscpl.com.au/articles/modpython-001.html
 
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/i18n.txt b/docs/i18n.txt
index 78404d4503..bb6cf74ded 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``).
     * 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,8 @@ 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).
 
 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 7eb0fdbb28..66fa63e3c6 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -784,9 +784,17 @@ you can use the name of the model, rather than the model object itself::
     class Manufacturer(models.Model):
         # ...
 
-Note, however, that you can only use strings to refer to models in the same
-models.py file -- you cannot use a string to reference a model in a different
-application, or to reference a model that has been imported from elsewhere.
+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::
+
+    class Car(models.Model):
+        manufacturer = models.ForeignKey('production.Manufacturer')
 
 Behind the scenes, Django appends ``"_id"`` to the field name to create its
 database column name. In the above example, the database table for the ``Car``
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index b9f0d88165..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::
 
@@ -323,17 +323,18 @@ parameter when declaring the form field::
 
 Form inheritance
 ----------------
-As with the basic forms, you can extend and reuse ``ModelForms`` by inheriting
-them. Normally, this will be useful if you need to declare some extra fields
-or extra methods on a parent class for use in a number of forms derived from
-models. For example, using the previous ``ArticleForm`` class::
+
+As with basic forms, you can extend and reuse ``ModelForms`` by inheriting
+them. This is useful if you need to declare extra fields or extra methods on a
+parent class for use in a number of forms derived from models. For example,
+using the previous ``ArticleForm`` class::
 
     >>> class EnhancedArticleForm(ArticleForm):
     ...     def clean_pub_date(self):
     ...         ...
 
-This creates a form that behaves identically to ``ArticleForm``, except there
-is some extra validation and cleaning for the ``pub_date`` field.
+This creates a form that behaves identically to ``ArticleForm``, except there's
+some extra validation and cleaning for the ``pub_date`` field.
 
 You can also subclass the parent's ``Meta`` inner class if you want to change
 the ``Meta.fields`` or ``Meta.excludes`` lists::
@@ -342,17 +343,18 @@ the ``Meta.fields`` or ``Meta.excludes`` lists::
     ...     class Meta(ArticleForm.Meta):
     ...         exclude = ['body']
 
-This adds in the extra method from the ``EnhancedArticleForm`` and modifies
+This adds the extra method from the ``EnhancedArticleForm`` and modifies
 the original ``ArticleForm.Meta`` to remove one field.
 
-There are a couple of things to note, however. Most of these won't normally be
-of concern unless you are trying to do something tricky with subclassing.
+There are a couple of things to note, however.
 
  * Normal Python name resolution rules apply. If you have multiple base
    classes that declare a ``Meta`` inner class, only the first one will be
-   used.  This means the child's ``Meta``, if it exists, otherwise the
+   used. This means the child's ``Meta``, if it exists, otherwise the
    ``Meta`` of the first parent, etc.
 
- * For technical reasons, you cannot have a subclass that is inherited from
-   both a ``ModelForm`` and a ``Form`` simultaneously.
+ * For technical reasons, a subclass cannot inherit from both a ``ModelForm``
+   and a ``Form`` simultaneously.
 
+Chances are these notes won't affect you unless you're trying to do something
+tricky with subclassing.
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 33cf48c274..229f704ca7 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -246,6 +246,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.
@@ -1563,7 +1567,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/request_response.txt b/docs/request_response.txt
index 47c66355e8..e50cfc5ea3 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -576,7 +576,7 @@ Three things to note about 404 views:
       in the 404.
 
     * The 404 view is passed a ``RequestContext`` and will have access to
-      variables supplied by your ``TEMPLATE_CONTEXT_PROCESSORS`` (e.g.
+      variables supplied by your ``TEMPLATE_CONTEXT_PROCESSORS`` setting (e.g.,
       ``MEDIA_URL``).
 
     * If ``DEBUG`` is set to ``True`` (in your settings module), then your 404
diff --git a/docs/serialization.txt b/docs/serialization.txt
index dff33f219f..e901410f1c 100644
--- a/docs/serialization.txt
+++ b/docs/serialization.txt
@@ -88,7 +88,7 @@ something like::
 
     for deserialized_object in serializers.deserialize("xml", data):
         if object_should_be_saved(deserialized_object):
-            obj.save()
+            deserialized_object.save()
 
 In other words, the usual use is to examine the deserialized objects to make
 sure that they are "appropriate" for saving before doing so.  Of course, if you trust your data source you could just save the object and move on.
diff --git a/docs/settings.txt b/docs/settings.txt
index 8478e0ce96..ace893f1b5 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -579,6 +579,16 @@ in standard language format. For example, U.S. English is ``"en-us"``. See the
 
 .. _internationalization docs: ../i18n/
 
+LANGUAGE_COOKIE_NAME
+--------------------
+
+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 +832,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/shortcuts.txt b/docs/shortcuts.txt
index f1d7f38ffa..005fdc3029 100644
--- a/docs/shortcuts.txt
+++ b/docs/shortcuts.txt
@@ -30,9 +30,9 @@ Optional arguments
 ``context_instance``
     The context instance to render the template with. By default, the template
     will be rendered with a ``Context`` instance (filled with values from
-    ``dictionary``). If you need to use `context processors`_, you will want to
-    render the template with a ``RequestContext`` instance instead. Your code
-    might look something like this::
+    ``dictionary``). If you need to use `context processors`_, render the
+    template with a ``RequestContext`` instance instead. Your code might look
+    something like this::
 
         return render_to_response('my_template.html',
                                   my_data_dictionary,
diff --git a/docs/templates.txt b/docs/templates.txt
index c351c951c9..d473a6f06f 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -1406,6 +1406,8 @@ Joins a list with a string, like Python's ``str.join(list)``.
 last
 ~~~~
 
+**New in Django development version.**
+
 Returns the last item in a list.
 
 length
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index f98cfa3249..43ef016ed4 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -395,6 +395,8 @@ See the `internationalization docs`_ for more.
 django.core.context_processors.media
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**New in Django development version**
+
 If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
 ``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
 value of the `MEDIA_URL setting`_.
@@ -627,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
 
@@ -981,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
@@ -1014,7 +1017,7 @@ This is not a very common situation, but it's useful if you're rendering a
 template yourself. For example::
 
     def render(self, context):
-        t = template.load_template('small_fragment.html')
+        t = template.loader.get_template('small_fragment.html')
         return t.render(Context({'var': obj}, autoescape=context.autoescape))
 
 If we had neglected to pass in the current ``context.autoescape`` value to our
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 952763f078..789399de8d 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -191,12 +191,12 @@ The remaining arguments should be tuples in this format::
 `Passing extra options to view functions`_ below.)
 
 .. note::
-    Since `patterns()` is a function call, it accepts a maximum of 255
+    Because `patterns()` is a function call, it accepts a maximum of 255
     arguments (URL patterns, in this case). This is a limit for all Python
-    function calls. This will rarely be  problem in practice, since you'll
+    function calls. This is rarely a problem in practice, because you'll
     typically structure your URL patterns modularly by using `include()`
     sections. However, on the off-chance you do hit the 255-argument limit,
-    realise that `patterns()` returns a Python list, so you can split up the
+    realize that `patterns()` returns a Python list, so you can split up the
     construction of the list.
 
     ::
@@ -209,8 +209,8 @@ The remaining arguments should be tuples in this format::
             )
 
     Python lists have unlimited size, so there's no limit to how many URL
-    patterns you can construct; merely that you may only create 254 at a time
-    (the 255-th argument is the initial prefix argument).
+    patterns you can construct. The only limit is that you can only create 254
+    at a time (the 255th argument is the initial prefix argument).
 
 url
 ---