Merge branch 'master' into schema-alteration

23 files changed, 277 insertions, 95 deletions

diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt
index d5df369fb3..a65a59bc8b 100644
--- a/docs/ref/class-based-views/generic-editing.txt
+++ b/docs/ref/class-based-views/generic-editing.txt
@@ -2,7 +2,28 @@
 Generic editing views
 =====================
 
-The views described here provide a foundation for editing content.
+The following views are described on this page and provide a foundation for 
+editing content:
+
+* :class:`django.views.generic.edit.FormView`
+* :class:`django.views.generic.edit.CreateView`
+* :class:`django.views.generic.edit.UpdateView`
+* :class:`django.views.generic.edit.DeleteView`
+
+.. note::
+
+    Some of the examples on this page assume that a model titled 'Author'
+    has been defined. For these cases we assume the following has been defined 
+    in `myapp/models.py`::
+
+        from django import models
+        from django.core.urlresolvers import reverse
+
+        class Author(models.Model):
+            name = models.CharField(max_length=200)
+
+            def get_absolute_url(self):
+                return reverse('author-detail', kwargs={'pk': self.pk})
 
 .. class:: django.views.generic.edit.FormView
 
@@ -11,6 +32,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.FormView`
     * :class:`django.views.generic.base.TemplateResponseMixin`
     * :class:`django.views.generic.edit.BaseFormView`
@@ -18,6 +41,35 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.edit.ProcessFormView`
     * :class:`django.views.generic.base.View`
 
+    **Example forms.py**::
+
+        from django import forms
+
+        class ContactForm(forms.Form):
+            name = forms.CharField()
+            message = forms.CharField(widget=forms.Textarea)
+
+            def send_email(self):
+                # send email using the self.cleaned_data dictionary
+                pass
+
+    **Example views.py**::
+
+        from myapp.forms import ContactForm
+        from django.views.generic.edit import FormView
+
+        class ContactView(FormView):
+            template_name = 'contact.html'
+            form_class = ContactForm
+            success_url = '/thanks/'
+
+            def form_valid(self, form):
+                # This method is called when valid form data has been POSTed.
+                # It should return an HttpResponse.
+                form.send_email()
+                return super(ContactView, self).form_valid(form)
+
+
 .. class:: django.views.generic.edit.CreateView
 
     A view that displays a form for creating an object, redisplaying the form
@@ -25,6 +77,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.CreateView`
     * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
     * :class:`django.views.generic.base.TemplateResponseMixin`
@@ -35,6 +89,24 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.edit.ProcessFormView`
     * :class:`django.views.generic.base.View`
 
+    **Attributes**
+
+    .. attribute:: template_name_suffix
+
+        The CreateView page displayed to a GET request uses a
+        ``template_name_suffix`` of ``'_form.html'``. For 
+        example, changing this attribute to ``'_create_form.html'`` for a view
+        creating objects for the the example `Author` model would cause the the
+        default `template_name` to be ``'myapp/author_create_form.html'``.
+
+    **Example views.py**::
+
+        from django.views.generic.edit import CreateView
+        from myapp.models import Author
+
+        class AuthorCreate(CreateView):
+            model = Author
+
 .. class:: django.views.generic.edit.UpdateView
 
     A view that displays a form for editing an existing object, redisplaying
@@ -44,6 +116,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.UpdateView`
     * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
     * :class:`django.views.generic.base.TemplateResponseMixin`
@@ -54,6 +128,24 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.edit.ProcessFormView`
     * :class:`django.views.generic.base.View`
 
+    **Attributes**
+
+    .. attribute:: template_name_suffix
+
+        The UpdateView page displayed to a GET request uses a
+        ``template_name_suffix`` of ``'_form.html'``. For 
+        example, changing this attribute to ``'_update_form.html'`` for a view
+        updating objects for the the example `Author` model would cause the the
+        default `template_name` to be ``'myapp/author_update_form.html'``.        
+
+    **Example views.py**::
+
+        from django.views.generic.edit import UpdateView
+        from myapp.models import Author
+
+        class AuthorUpdate(UpdateView):
+            model = Author
+
 .. class:: django.views.generic.edit.DeleteView
 
     A view that displays a confirmation page and deletes an existing object.
@@ -63,6 +155,8 @@ The views described here provide a foundation for editing content.
 
     **Ancestors (MRO)**
 
+    This view inherits methods and attributes from the following views:
+
     * :class:`django.views.generic.edit.DeleteView`
     * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
     * :class:`django.views.generic.base.TemplateResponseMixin`
@@ -72,7 +166,23 @@ The views described here provide a foundation for editing content.
     * :class:`django.views.generic.detail.SingleObjectMixin`
     * :class:`django.views.generic.base.View`
 
-    **Notes**
+    **Attributes**
+
+    .. attribute:: template_name_suffix
+
+        The DeleteView page displayed to a GET request uses a
+        ``template_name_suffix`` of ``'_confirm_delete.html'``. For 
+        example, changing this attribute to ``'_check_delete.html'`` for a view
+        deleting objects for the the example `Author` model would cause the the
+        default `template_name` to be ``'myapp/author_check_delete.html'``.        
+
+
+    **Example views.py**::
+
+        from django.views.generic.edit import DeleteView
+        from django.core.urlresolvers import reverse_lazy
+        from myapp.models import Author
 
-    * The delete confirmation page displayed to a GET request uses a
-      ``template_name_suffix`` of ``'_confirm_delete'``.
+        class AuthorDelete(DeleteView):
+            model = Author
+            success_url = reverse_lazy('author-list')        
diff --git a/docs/ref/class-based-views/index.txt b/docs/ref/class-based-views/index.txt
index c10e66b396..f2271d2506 100644
--- a/docs/ref/class-based-views/index.txt
+++ b/docs/ref/class-based-views/index.txt
@@ -32,9 +32,9 @@ A class-based view is deployed into a URL pattern using the
 
     Arguments passed to a view are shared between every instance of a view.
     This means that you shoudn't use a list, dictionary, or any other
-    variable object as an argument to a view. If you did, the actions of
-    one user visiting your view could have an effect on subsequent users
-    visiting the same view.
+    mutable object as an argument to a view. If you do and the shared object
+    is modified, the actions of one user visiting your view could have an
+    effect on subsequent users visiting the same view.
 
 Any argument passed into :meth:`~View.as_view()` will be assigned onto the
 instance that is used to service a request. Using the previous example,
diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt
index 7258893d63..89610889db 100644
--- a/docs/ref/class-based-views/mixins-editing.txt
+++ b/docs/ref/class-based-views/mixins-editing.txt
@@ -2,6 +2,18 @@
 Editing mixins
 ==============
 
+The following mixins are used to construct Django's editing views:
+
+* :class:`django.views.generic.edit.FormMixin`
+* :class:`django.views.generic.edit.ModelFormMixin`
+* :class:`django.views.generic.edit.ProcessFormView`
+* :class:`django.views.generic.edit.DeletionMixin`
+
+.. note::
+
+    Examples of how these are combined into editing views can be found at
+    the documentation on ``Generic editing views``.
+
 .. class:: django.views.generic.edit.FormMixin
 
     A mixin class that provides facilities for creating and displaying forms.
diff --git a/docs/ref/contrib/admin/_images/article_actions.png b/docs/ref/contrib/admin/_images/article_actions.png
index 78a78ae494..1d35e60e5d 100644
--- a/docs/ref/contrib/admin/_images/article_actions.png
+++ b/docs/ref/contrib/admin/_images/article_actions.png
diff --git a/docs/ref/contrib/admin/_images/article_actions_message.png b/docs/ref/contrib/admin/_images/article_actions_message.png
index 6ea9439b8e..16a2d0e197 100644
--- a/docs/ref/contrib/admin/_images/article_actions_message.png
+++ b/docs/ref/contrib/admin/_images/article_actions_message.png
diff --git a/docs/ref/contrib/admin/_images/user_actions.png b/docs/ref/contrib/admin/_images/user_actions.png
index fdbe2ad897..22d40e0181 100644
--- a/docs/ref/contrib/admin/_images/user_actions.png
+++ b/docs/ref/contrib/admin/_images/user_actions.png
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index f28aa4687b..4d39981a4d 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1266,11 +1266,11 @@ provided some extra mapping data that would not otherwise be available::
             # ...
             pass
 
-        def change_view(self, request, object_id, extra_context=None):
+        def change_view(self, request, object_id, form_url='', extra_context=None):
             extra_context = extra_context or {}
             extra_context['osm_data'] = self.get_osm_info()
             return super(MyModelAdmin, self).change_view(request, object_id,
-                extra_context=extra_context)
+                form_url, extra_context=extra_context)
 
 .. versionadded:: 1.4
 
diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt
index 5007ddff69..0ef37a9a0b 100644
--- a/docs/ref/contrib/comments/custom.txt
+++ b/docs/ref/contrib/comments/custom.txt
@@ -51,9 +51,9 @@ To make this kind of customization, we'll need to do three things:
    custom :setting:`COMMENTS_APP`.
 
 So, carrying on the example above, we're dealing with a typical app structure in
-the ``my_custom_app`` directory::
+the ``my_comment_app`` directory::
 
-    my_custom_app/
+    my_comment_app/
         __init__.py
         models.py
         forms.py
@@ -98,11 +98,11 @@ Django provides a couple of "helper" classes to make writing certain types of
 custom comment forms easier; see :mod:`django.contrib.comments.forms` for
 more.
 
-Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to
+Finally, we'll define a couple of methods in ``my_comment_app/__init__.py`` to
 point Django at these classes we've created::
 
-    from my_comments_app.models import CommentWithTitle
-    from my_comments_app.forms import CommentFormWithTitle
+    from my_comment_app.models import CommentWithTitle
+    from my_comment_app.forms import CommentFormWithTitle
 
     def get_model():
         return CommentWithTitle
diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt
index eda9617381..f4e706d275 100644
--- a/docs/ref/contrib/gis/geos.txt
+++ b/docs/ref/contrib/gis/geos.txt
@@ -75,6 +75,17 @@ return a :class:`GEOSGeometry` object from an input string or a file::
     >>> pnt = fromfile('/path/to/pnt.wkt')
     >>> pnt = fromfile(open('/path/to/pnt.wkt'))
 
+.. _geos-exceptions-in-logfile:
+
+.. admonition:: My logs are filled with GEOS-related errors
+
+    You find many ``TypeError`` or ``AttributeError`` exceptions filling your
+    Web server's log files. This generally means that you are creating GEOS
+    objects at the top level of some of your Python modules. Then, due to a race
+    condition in the garbage collector, your module is garbage collected before
+    the GEOS object. To prevent this, create :class:`GEOSGeometry` objects
+    inside the local scope of your functions/methods.
+
 Geometries are Pythonic
 -----------------------
 :class:`GEOSGeometry` objects are 'Pythonic', in other words components may
diff --git a/docs/ref/contrib/gis/install.txt b/docs/ref/contrib/gis/install.txt
index 5ee6d5153d..72bd72a6f8 100644
--- a/docs/ref/contrib/gis/install.txt
+++ b/docs/ref/contrib/gis/install.txt
@@ -191,6 +191,8 @@ GEOS C library.  For example:
     The setting must be the *full* path to the **C** shared library; in
     other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
 
+See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
+
 .. _proj4:
 
 PROJ.4
diff --git a/docs/ref/contrib/humanize.txt b/docs/ref/contrib/humanize.txt
index cdc3009a51..57978288b1 100644
--- a/docs/ref/contrib/humanize.txt
+++ b/docs/ref/contrib/humanize.txt
@@ -103,9 +103,9 @@ naturaltime
 .. versionadded:: 1.4
 
 For datetime values, returns a string representing how many seconds,
-minutes or hours ago it was -- falling back to a longer date format if the
-value is more than a day old. In case the datetime value is in the future
-the return value will automatically use an appropriate phrase.
+minutes or hours ago it was -- falling back to the :tfilter:`timesince` 
+format if the value is more than a day old. In case the datetime value is in
+the future the return value will automatically use an appropriate phrase.
 
 Examples (when 'now' is 17 Feb 2007 16:30:00):
 
@@ -115,13 +115,14 @@ Examples (when 'now' is 17 Feb 2007 16:30:00):
 * ``17 Feb 2007 16:25:35`` becomes ``4 minutes ago``.
 * ``17 Feb 2007 15:30:29`` becomes ``an hour ago``.
 * ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``.
-* ``16 Feb 2007 13:31:29`` becomes ``1 day ago``.
+* ``16 Feb 2007 13:31:29`` becomes ``1 day, 3 hours ago``.
 * ``17 Feb 2007 16:30:30`` becomes ``29 seconds from now``.
 * ``17 Feb 2007 16:31:00`` becomes ``a minute from now``.
 * ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``.
 * ``17 Feb 2007 16:30:29`` becomes ``an hour from now``.
 * ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``.
 * ``18 Feb 2007 16:31:29`` becomes ``1 day from now``.
+* ``26 Feb 2007 18:31:29`` becomes ``1 week, 2 days from now``.
 
 .. templatefilter:: ordinal
 
diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt
index 6929a3b0d0..4cf90ee381 100644
--- a/docs/ref/contrib/messages.txt
+++ b/docs/ref/contrib/messages.txt
@@ -5,12 +5,14 @@ The messages framework
 .. module:: django.contrib.messages
    :synopsis: Provides cookie- and session-based temporary message storage.
 
-Django provides full support for cookie- and session-based messaging, for
-both anonymous and authenticated clients. The messages framework allows you
-to temporarily store messages in one request and retrieve them for display
-in a subsequent request (usually the next one). Every message is tagged
-with a specific ``level`` that determines its priority (e.g., ``info``,
-``warning``, or ``error``).
+Quite commonly in web applications, you may need to display a one-time
+notification message (also know as "flash message") to the user after
+processing a form or some other types of user input. For this, Django provides
+full support for cookie- and session-based messaging, for both anonymous and
+authenticated users. The messages framework allows you to temporarily store
+messages in one request and retrieve them for display in a subsequent request
+(usually the next one). Every message is tagged with a specific ``level`` that
+determines its priority (e.g., ``info``, ``warning``, or ``error``).
 
 Enabling messages
 =================
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 74e6b48f07..92b5665bea 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -238,7 +238,7 @@ to you, the developer, to handle the fact that you will receive bytestrings if
 you configure your table(s) to use ``utf8_bin`` collation. Django itself should
 mostly work smoothly with such columns (except for the ``contrib.sessions``
 ``Session`` and ``contrib.admin`` ``LogEntry`` tables described below), but
-your code must be prepared to call ``django.utils.encoding.smart_unicode()`` at
+your code must be prepared to call ``django.utils.encoding.smart_text()`` at
 times if it really wants to work with consistent data -- Django will not do
 this for you (the database backend layer and the model population layer are
 separated internally so the database layer doesn't know it needs to make this
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index c4295c68d5..5ff7ecba2c 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -747,7 +747,7 @@ use the ``--plain`` option, like so::
 
 If you would like to specify either IPython or bpython as your interpreter if
 you have both installed you can specify an alternative interpreter interface
-with the ``-i`` or ``--interface`` options like so::
+with the ``-i`` or ``--interface`` options like so:
 
 IPython::
 
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 50488b026a..777d73e015 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -199,8 +199,8 @@ 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.
 
-If your data does *not* validate, your ``Form`` instance will not have a
-``cleaned_data`` attribute::
+If your data does *not* validate, the ``cleaned_data`` dictionary contains
+only the valid fields::
 
     >>> data = {'subject': '',
     ...         'message': 'Hi there',
@@ -210,9 +210,12 @@ If your data does *not* validate, your ``Form`` instance will not have a
     >>> f.is_valid()
     False
     >>> f.cleaned_data
-    Traceback (most recent call last):
-    ...
-    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
+    {'cc_myself': True, 'message': u'Hi there'}
+
+.. versionchanged:: 1.5
+
+Until Django 1.5, the ``cleaned_data`` attribute wasn't defined at all when
+the ``Form`` didn't validate.
 
 ``cleaned_data`` will always *only* contain a key for fields defined in the
 ``Form``, even if you pass extra data when you define the ``Form``. In this
@@ -232,9 +235,9 @@ but ``cleaned_data`` contains only the form's fields::
     >>> f.cleaned_data # Doesn't contain extra_field_1, etc.
     {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
 
-``cleaned_data`` will include a key and value for *all* fields defined in the
-``Form``, even if the data didn't include a value for fields that are not
-required. In this example, the data dictionary doesn't include a value for the
+When the ``Form`` is valid, ``cleaned_data`` will include a key and value for
+*all* its fields, even if the data didn't include a value for some optional
+fields. In this example, the data dictionary doesn't include a value for the
 ``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::
 
     >>> class OptionalPersonForm(Form):
@@ -583,7 +586,7 @@ lazy developers -- they're not the only way a form object can be displayed.
 
    Used to display HTML or access attributes for a single field of a
    :class:`Form` instance.
-   
+
    The :meth:`__unicode__` and :meth:`__str__` methods of this object displays
    the HTML for this field.
 
diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt
index 97883d7880..95424d0cd0 100644
--- a/docs/ref/forms/validation.txt
+++ b/docs/ref/forms/validation.txt
@@ -362,7 +362,9 @@ Secondly, once we have decided that the combined data in the two fields we are
 considering aren't valid, we must remember to remove them from the
 ``cleaned_data``.
 
-In fact, Django will currently completely wipe out the ``cleaned_data``
-dictionary if there are any errors in the form. However, this behavior may
-change in the future, so it's not a bad idea to clean up after yourself in the
-first place.
+.. versionchanged:: 1.5
+
+Django used to remove the ``cleaned_data`` attribute entirely if there were
+any errors in the form. Since version 1.5, ``cleaned_data`` is present even if
+the form doesn't validate, but it contains only field values that did
+validate.
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index c280202ebf..a6ea9a6c41 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -146,7 +146,7 @@ Locale middleware
 
 Enables language selection based on data from the request. It customizes
 content for each user. See the :doc:`internationalization documentation
-</topics/i18n/index>`.
+</topics/i18n/translation>`.
 
 Message middleware
 ------------------
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 5039ba4373..a43163c5e9 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -86,42 +86,43 @@ field.
 If this is given, Django's admin will use a select box instead of the standard
 text field and will limit choices to the choices given.
 
-A choices list looks like this::
+A choices list is an iterable of 2-tuples; the first element in each
+tuple is the actual value to be stored, and the second element is the
+human-readable name. For example::
 
     YEAR_IN_SCHOOL_CHOICES = (
         ('FR', 'Freshman'),
         ('SO', 'Sophomore'),
         ('JR', 'Junior'),
         ('SR', 'Senior'),
-        ('GR', 'Graduate'),
     )
 
-The first element in each tuple is the actual value to be stored. The second
-element is the human-readable name for the option.
+Generally, it's best to define choices inside a model class, and to
+define a suitably-named constant for each value::
 
-The choices list can be defined either as part of your model class::
-
-    class Foo(models.Model):
+    class Student(models.Model):
+        FRESHMAN = 'FR'
+        SOPHOMORE = 'SO'
+        JUNIOR = 'JR'
+        SENIOR = 'SR'
         YEAR_IN_SCHOOL_CHOICES = (
-            ('FR', 'Freshman'),
-            ('SO', 'Sophomore'),
-            ('JR', 'Junior'),
-            ('SR', 'Senior'),
-            ('GR', 'Graduate'),
+            (FRESHMAN, 'Freshman'),
+            (SOPHOMORE, 'Sophomore'),
+            (JUNIOR, 'Junior'),
+            (SENIOR, 'Senior'),
         )
-        year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
+        year_in_school = models.CharField(max_length=2,
+                                          choices=YEAR_IN_SCHOOL_CHOICES,
+                                          default=FRESHMAN)
 
-or outside your model class altogether::
+        def is_upperclass(self):
+	    return self.year_in_school in (self.JUNIOR, self.SENIOR)
 
-    YEAR_IN_SCHOOL_CHOICES = (
-        ('FR', 'Freshman'),
-        ('SO', 'Sophomore'),
-        ('JR', 'Junior'),
-        ('SR', 'Senior'),
-        ('GR', 'Graduate'),
-    )
-    class Foo(models.Model):
-        year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
+Though you can define a choices list outside of a model class and then
+refer to it, defining the choices and names for each choice inside the
+model class keeps all of that information with the class that uses it,
+and makes the choices easy to reference (e.g, ``Student.SOPHOMORE``
+will work anywhere that the ``Student`` model has been imported).
 
 You can also collect your available choices into named groups that can
 be used for organizational purposes::
@@ -1002,9 +1003,10 @@ define the details of how the relation works.
     <abstract-base-classes>`; and when you do so
     :ref:`some special syntax <abstract-related-name>` is available.
 
-    If you'd prefer Django didn't create a backwards relation, set ``related_name``
-    to ``'+'``. For example, this will ensure that the ``User`` model won't get a
-    backwards relation to this model::
+    If you'd prefer Django not to create a backwards relation, set
+    ``related_name`` to ``'+'`` or end it with ``'+'``. For example, this will
+    ensure that the ``User`` model won't have a backwards relation to this
+    model::
 
         user = models.ForeignKey(User, related_name='+')
 
@@ -1095,6 +1097,13 @@ that control how the relationship functions.
 
     Same as :attr:`ForeignKey.related_name`.
 
+    If you have more than one ``ManyToManyField`` pointing to the same model
+    and want to suppress the backwards relations, set each ``related_name``
+    to a unique value ending with ``'+'``::
+
+        users = models.ManyToManyField(User, related_name='u+')
+        referents = models.ManyToManyField(User, related_name='ref+')
+
 .. attribute:: ManyToManyField.limit_choices_to
 
     Same as :attr:`ForeignKey.limit_choices_to`.
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 509ea9d30e..14541ad0d1 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -453,9 +453,9 @@ using ``__str__()`` like this::
         last_name = models.CharField(max_length=50)
 
         def __str__(self):
-            # Note use of django.utils.encoding.smart_str() here because
+            # Note use of django.utils.encoding.smart_bytes() here because
             # first_name and last_name will be unicode strings.
-            return smart_str('%s %s' % (self.first_name, self.last_name))
+            return smart_bytes('%s %s' % (self.first_name, self.last_name))
 
 ``get_absolute_url``
 --------------------
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 72d60453c3..531ff33da2 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -183,7 +183,7 @@ compose a prefix, version and key into a final cache key. The default
 implementation is equivalent to the function::
 
     def make_key(key, key_prefix, version):
-        return ':'.join([key_prefix, str(version), smart_str(key)])
+        return ':'.join([key_prefix, str(version), smart_bytes(key)])
 
 You may use any key function you want, as long as it has the same
 argument signature.
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 500a47c6f1..072eebf69f 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -1184,7 +1184,7 @@ Removes all values of arg from the given string.
 
 For example::
 
-    {{ value|cut:" "}}
+    {{ value|cut:" " }}
 
 If ``value`` is ``"String with spaces"``, the output will be
 ``"Stringwithspaces"``.
diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
index b9253e70b3..ffab647379 100644
--- a/docs/ref/unicode.txt
+++ b/docs/ref/unicode.txt
@@ -129,7 +129,7 @@ Conversion functions
 The ``django.utils.encoding`` module contains a few functions that are handy
 for converting back and forth between Unicode and bytestrings.
 
-* ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
+* ``smart_text(s, encoding='utf-8', strings_only=False, errors='strict')``
   converts its input to a Unicode string. The ``encoding`` parameter
   specifies the input encoding. (For example, Django uses this internally
   when processing form input data, which might not be UTF-8 encoded.) The
@@ -139,27 +139,27 @@ for converting back and forth between Unicode and bytestrings.
   that are accepted by Python's ``unicode()`` function for its error
   handling.
 
-  If you pass ``smart_unicode()`` an object that has a ``__unicode__``
+  If you pass ``smart_text()`` an object that has a ``__unicode__``
   method, it will use that method to do the conversion.
 
-* ``force_unicode(s, encoding='utf-8', strings_only=False,
-  errors='strict')`` is identical to ``smart_unicode()`` in almost all
+* ``force_text(s, encoding='utf-8', strings_only=False,
+  errors='strict')`` is identical to ``smart_text()`` in almost all
   cases. The difference is when the first argument is a :ref:`lazy
-  translation <lazy-translations>` instance. While ``smart_unicode()``
-  preserves lazy translations, ``force_unicode()`` forces those objects to a
+  translation <lazy-translations>` instance. While ``smart_text()``
+  preserves lazy translations, ``force_text()`` forces those objects to a
   Unicode string (causing the translation to occur). Normally, you'll want
-  to use ``smart_unicode()``. However, ``force_unicode()`` is useful in
+  to use ``smart_text()``. However, ``force_text()`` is useful in
   template tags and filters that absolutely *must* have a string to work
   with, not just something that can be converted to a string.
 
-* ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')``
-  is essentially the opposite of ``smart_unicode()``. It forces the first
+* ``smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')``
+  is essentially the opposite of ``smart_text()``. It forces the first
   argument to a bytestring. The ``strings_only`` parameter has the same
-  behavior as for ``smart_unicode()`` and ``force_unicode()``. This is
+  behavior as for ``smart_text()`` and ``force_text()``. This is
   slightly different semantics from Python's builtin ``str()`` function,
   but the difference is needed in a few places within Django's internals.
 
-Normally, you'll only need to use ``smart_unicode()``. Call it as early as
+Normally, you'll only need to use ``smart_text()``. Call it as early as
 possible on any input data that might be either Unicode or a bytestring, and
 from then on, you can treat the result as always being Unicode.
 
@@ -324,7 +324,7 @@ A couple of tips to remember when writing your own template tags and filters:
 * Always return Unicode strings from a template tag's ``render()`` method
   and from template filters.
 
-* Use ``force_unicode()`` in preference to ``smart_unicode()`` in these
+* Use ``force_text()`` in preference to ``smart_text()`` in these
   places. Tag rendering and filter calls occur as the template is being
   rendered, so there is no advantage to postponing the conversion of lazy
   translation objects into strings. It's easier to work solely with Unicode
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index c2f2025bc3..b6cb1035d3 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -178,33 +178,53 @@ The functions defined in this module share the following properties:
 
 .. class:: StrAndUnicode
 
-    A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8
-    bytestring. Useful as a mix-in.
+    A class that derives ``__str__`` from ``__unicode__``.
 
-.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+    On Python 2, ``__str__`` returns the output of ``__unicode__`` encoded as
+    a UTF-8 bytestring. On Python 3, ``__str__`` returns the output of
+    ``__unicode__``.
+
+    Useful as a mix-in. If you support Python 2 and 3 with a single code base,
+    you can inherit this mix-in and just define ``__unicode__``.
+
+.. function:: smart_text(s, encoding='utf-8', strings_only=False, errors='strict')
 
-    Returns a ``unicode`` object representing ``s``. Treats bytestrings using
-    the 'encoding' codec.
+    .. versionadded:: 1.5
+
+    Returns a text object representing ``s`` -- ``unicode`` on Python 2 and
+    ``str`` on Python 3. Treats bytestrings using the ``encoding`` codec.
 
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
 
+.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    Historical name of :func:`smart_text`. Only available under Python 2.
+
 .. function:: is_protected_type(obj)
 
     Determine if the object instance is of a protected type.
 
     Objects of protected types are preserved as-is when passed to
-    ``force_unicode(strings_only=True)``.
+    ``force_text(strings_only=True)``.
 
-.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+.. function:: force_text(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    .. versionadded:: 1.5
 
-    Similar to ``smart_unicode``, except that lazy instances are resolved to
+    Similar to ``smart_text``, except that lazy instances are resolved to
     strings, rather than kept as lazy objects.
 
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
 
-.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')
+.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    Historical name of :func:`force_text`. Only available under Python 2.
+
+.. function:: smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    .. versionadded:: 1.5
 
     Returns a bytestring version of ``s``, encoded as specified in
     ``encoding``.
@@ -212,6 +232,14 @@ The functions defined in this module share the following properties:
     If ``strings_only`` is ``True``, don't convert (some) non-string-like
     objects.
 
+.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')
+
+    Alias of :func:`smart_bytes` on Python 2 and :func:`smart_text` on Python
+    3. This function always returns a :class:`str`.
+
+    For instance, this is  suitable for writing to :attr:`sys.stdout` on
+    Python 2 and 3.
+
 .. function:: iri_to_uri(iri)
 
     Convert an Internationalized Resource Identifier (IRI) portion to a URI
@@ -406,7 +434,7 @@ escaping HTML.
 
     Returns the given text with ampersands, quotes and angle brackets encoded
     for use in HTML. The input is first passed through
-    :func:`~django.utils.encoding.force_unicode` and the output has
+    :func:`~django.utils.encoding.force_text` and the output has
     :func:`~django.utils.safestring.mark_safe` applied.
 
 .. function:: conditional_escape(text)
@@ -448,7 +476,7 @@ escaping HTML.
     interpolation, some of the formatting options provided by `str.format`_
     (e.g. number formatting) will not work, since all arguments are passed
     through :func:`conditional_escape` which (ultimately) calls
-    :func:`~django.utils.encoding.force_unicode` on the values.
+    :func:`~django.utils.encoding.force_text` on the values.
 
 
 .. _str.format: http://docs.python.org/library/stdtypes.html#str.format
@@ -504,11 +532,13 @@ escaping HTML.
 
 .. function:: base36_to_int(s)
 
-    Converts a base 36 string to an integer.
+    Converts a base 36 string to an integer. On Python 2 the output is
+    guaranteed to be an :class:`int` and not a :class:`long`.
 
 .. function:: int_to_base36(i)
 
-    Converts a positive integer less than sys.maxint to a base 36 string.
+    Converts a positive integer to a base 36 string. On Python 2 ``i`` must be
+    smaller than :attr:`sys.maxint`.
 
 ``django.utils.safestring``
 ===========================