boulder-oracle-sprint: Merged to [5258]

git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@5259 bcc190cf-cafb-0310-a4f2-bffc1f526a37

3 files changed, 38 insertions, 26 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 9d2f09daf3..de612e0e3d 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -143,8 +143,8 @@ or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django
 follows this algorithm:
 
     * If the object's primary key attribute is set to a value that evaluates to
-      ``True`` (i.e., a value other than ``None`` or the empty string), Django 
-      executes a ``SELECT`` query to determine whether a record with the given 
+      ``True`` (i.e., a value other than ``None`` or the empty string), Django
+      executes a ``SELECT`` query to determine whether a record with the given
       primary key already exists.
     * If the record with the given primary key does already exist, Django
       executes an ``UPDATE`` query.
@@ -525,19 +525,19 @@ Examples::
     [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
     >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
     [datetime.datetime(2005, 3, 20)]
-    
+
 ``none()``
 ~~~~~~~~~~
 
 **New in Django development version**
 
-Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to 
+Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to
 an empty list. This can be used in cases where you know that you should
 return an empty result set and your caller is expecting a ``QuerySet``
 object (instead of returning an empty list, for example.)
 
 Examples::
-    
+
     >>> Entry.objects.none()
     []
 
@@ -610,7 +610,7 @@ follow::
     c = p.hometown       # Requires a database call.
 
 The ``depth`` argument is new in the Django development version.
-    
+
 ``extra(select=None, where=None, params=None, tables=None)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1136,7 +1136,7 @@ such as January 3, July 3, etc.
 isnull
 ~~~~~~
 
-Takes either ``True`` or ``False``, which correspond to SQL queries of 
+Takes either ``True`` or ``False``, which correspond to SQL queries of
 ``IS NULL`` and ``IS NOT NULL``, respectively.
 
 Example::
@@ -1149,10 +1149,10 @@ SQL equivalent::
 
 .. admonition:: ``__isnull=True`` vs ``__exact=None``
 
-    There is an important difference between ``__isnull=True`` and 
+    There is an important difference between ``__isnull=True`` and
     ``__exact=None``. ``__exact=None`` will *always* return an empty result
-    set, because SQL requires that no value is equal to ``NULL``. 
-    ``__isnull`` determines if the field is currently holding the value 
+    set, because SQL requires that no value is equal to ``NULL``.
+    ``__isnull`` determines if the field is currently holding the value
     of ``NULL`` without performing a comparison.
 
 search
@@ -1181,7 +1181,7 @@ The pk lookup shortcut
 ----------------------
 
 For convenience, Django provides a ``pk`` lookup type, which stands for
-"primary_key". 
+"primary_key".
 
 In the example ``Blog`` model, the primary key is the ``id`` field, so these
 three statements are equivalent::
@@ -1190,14 +1190,14 @@ three statements are equivalent::
     Blog.objects.get(id=14) # __exact is implied
     Blog.objects.get(pk=14) # pk implies id__exact
 
-The use of ``pk`` isn't limited to ``__exact`` queries -- any query term 
+The use of ``pk`` isn't limited to ``__exact`` queries -- any query term
 can be combined with ``pk`` to perform a query on the primary key of a model::
 
     # Get blogs entries  with id 1, 4 and 7
     Blog.objects.filter(pk__in=[1,4,7])
     # Get all blog entries with id > 14
-    Blog.objects.filter(pk__gt=14) 
-    
+    Blog.objects.filter(pk__gt=14)
+
 ``pk`` lookups also work across joins. For example, these three statements are
 equivalent::
 
@@ -1754,19 +1754,19 @@ get_object_or_404()
 -------------------
 
 One common idiom to use ``get()`` and raise ``Http404`` if the
-object doesn't exist. This idiom is captured by ``get_object_or_404()``. 
-This function takes a Django model as its first argument and an 
-arbitrary number of keyword arguments, which it passes to the manager's 
+object doesn't exist. This idiom is captured by ``get_object_or_404()``.
+This function takes a Django model as its first argument and an
+arbitrary number of keyword arguments, which it passes to the manager's
 ``get()`` function. It raises ``Http404`` if the object doesn't
-exist. For example:: 
-    
+exist. For example::
+
     # Get the Entry with a primary key of 3
     e = get_object_or_404(Entry, pk=3)
 
-When you provide a model to this shortcut function, the default manager 
-is used to execute the underlying ``get()`` query. If you don't want to 
-use the default manager, or you want to search a list of related objects, 
-you can provide ``get_object_or_404()`` with a manager object, instead. 
+When you provide a model to this shortcut function, the default manager
+is used to execute the underlying ``get()`` query. If you don't want to
+use the default manager, or if you want to search a list of related objects,
+you can provide ``get_object_or_404()`` with a manager object instead.
 For example::
 
     # Get the author of blog instance `e` with a name of 'Fred'
@@ -1779,8 +1779,8 @@ For example::
 get_list_or_404()
 -----------------
 
-``get_list_or_404`` behaves the same was as ``get_object_or_404()`` 
--- except the it uses using ``filter()`` instead of ``get()``. It raises 
+``get_list_or_404`` behaves the same way as ``get_object_or_404()``
+-- except that it uses ``filter()`` instead of ``get()``. It raises
 ``Http404`` if the list is empty.
 
 Falling back to raw SQL
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 961269aebd..e7afbfd13a 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1759,6 +1759,15 @@ But this template code is good::
 
     <a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
 
+.. note::
+    The string you return from ``get_absolute_url()`` must be use only ASCII
+    characters (required by the URI spec, `RFC 2396`_) that has been
+    URL-encoded, if necessary. Code and templates using ``get_absolute_url()``
+    should be able to use the result directly without needing to do any
+    further processing.
+
+.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt
+
 The ``permalink`` decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index d9d4f53b88..2a03e6d5a6 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -146,7 +146,10 @@ put into those elements.
       exist, it tries calling a method ``item_link()`` in the ``Feed`` class,
       passing it a single parameter, ``item``, which is the object itself.
       Both ``get_absolute_url()`` and ``item_link()`` should return the item's
-      URL as a normal Python string.
+      URL as a normal Python string. As with ``get_absolute_url()``, the
+      result of ``item_link()`` will be included directly in the URL, so you
+      are responsible for doing all necessary URL quoting and conversion to
+      ASCII inside the method itself.
 
     * For the LatestEntries example above, we could have very simple feed templates: