Edited doc changes from [17244]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17302 bcc190cf-cafb-0310-a4f2-bffc1f526a37

3 files changed, 20 insertions, 16 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index b7bc647981..11e23c0250 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -376,20 +376,26 @@ query spans multiple tables, it's possible to get duplicate results when a
 
 .. versionadded:: 1.4
 
-The possibility to pass positional arguments (``*fields``) is new in Django 1.4.
-They are names of fields to which the ``DISTINCT`` should be limited. This
-translates to a ``SELECT DISTINCT ON`` SQL query. A ``DISTINCT ON`` query eliminates
-duplicate rows not by comparing all fields in a row, but by comparing only the given
-fields.
+As of Django 1.4, you can pass positional arguments (``*fields``) in order to
+specify the names of fields to which the ``DISTINCT`` should apply. This
+translates to a ``SELECT DISTINCT ON`` SQL query.
+
+Here's the difference. For a normal ``distinct()`` call, the database compares
+*each* field in each row when determining which rows are distinct. For a
+``distinct()`` call with specified field names, the database will only compare
+the specified field names.
 
 .. note::
-    Note that the ability to specify field names is only available in PostgreSQL.
+    This ability to specify field names is only available in PostgreSQL.
 
 .. note::
-    When using the ``DISTINCT ON`` functionality it is required that the columns given
-    to :meth:`distinct` match the first :meth:`order_by` columns. For example ``SELECT
-    DISTINCT ON (a)`` gives you the first row for each value in column ``a``. If you
-    don't specify an order, then you'll get some arbitrary row.
+    When you specify field names, you *must* provide an ``order_by()`` in the
+    QuerySet, and the fields in ``order_by()`` must start with the fields in
+    ``distinct()``, in the same order.
+
+    For example, ``SELECT DISTINCT ON (a)`` gives you the first row for each
+    value in column ``a``. If you don't specify an order, you'll get some
+    arbitrary row.
 
 Examples::
 
diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt
index 6e284bd405..52c8e75266 100644
--- a/docs/releases/1.4-alpha-1.txt
+++ b/docs/releases/1.4-alpha-1.txt
@@ -548,10 +548,9 @@ Django 1.4 also includes several smaller improvements worth noting:
 * Added support in the ORM for generating ``SELECT`` queries containing
   ``DISTINCT ON``.
 
-  The ``distinct()`` ``Queryset`` method now accepts an optional list of model
+  The ``distinct()`` ``QuerySet`` method now accepts an optional list of model
   field names. If specified, then the ``DISTINCT`` statement is limited to these
-  fields. PostgreSQL is the only database backend shipped with Django that
-  supports this new functionality.
+  fields. This is only supported in PostgreSQL.
 
   For more details, see the documentation for
   :meth:`~django.db.models.query.QuerySet.distinct`.
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index 1ab34d80bc..e228bc0b29 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -538,10 +538,9 @@ Django 1.4 also includes several smaller improvements worth noting:
 * Added support in the ORM for generating ``SELECT`` queries containing
   ``DISTINCT ON``.
 
-  The ``distinct()`` ``Queryset`` method now accepts an optional list of model
+  The ``distinct()`` ``QuerySet`` method now accepts an optional list of model
   field names. If specified, then the ``DISTINCT`` statement is limited to these
-  fields. PostgreSQL is the only database backend shipped with Django that
-  supports this new functionality.
+  fields. This is only supported in PostgreSQL.
 
   For more details, see the documentation for
   :meth:`~django.db.models.query.QuerySet.distinct`.