queryset-refactor: Merged from trunk up to [6595].

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6597 bcc190cf-cafb-0310-a4f2-bffc1f526a37

15 files changed, 230 insertions, 72 deletions

diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt
index cab57fe6d5..859050e716 100644
--- a/docs/apache_auth.txt
+++ b/docs/apache_auth.txt
@@ -28,21 +28,21 @@ with the standard ``Auth*`` and ``Require`` directives::
         SetEnv DJANGO_SETTINGS_MODULE mysite.settings
         PythonAuthenHandler django.contrib.auth.handlers.modpython
     </Location>
-    
+
 .. admonition:: Using the authentication handler with Apache 2.2
 
     If you're using Apache 2.2, you'll need to take a couple extra steps.
-    
+
     You'll need to ensure that ``mod_auth_basic`` and ``mod_authz_user``
     are loaded. These might be compiled statically into Apache, or you might
     need to use ``LoadModule`` to load them dynamically (as shown in the
     example at the bottom of this note).
-        
+
     You'll also need to insert configuration directives that prevent Apache
     from trying to use other authentication modules. Depending on which other
     authentication modules you have loaded, you might need one or more of
     the following directives::
-    
+
         AuthBasicAuthoritative Off
         AuthDefaultAuthoritative Off
         AuthzLDAPAuthoritative Off
@@ -51,18 +51,18 @@ with the standard ``Auth*`` and ``Require`` directives::
         AuthzGroupFileAuthoritative Off
         AuthzOwnerAuthoritative Off
         AuthzUserAuthoritative Off
-        
+
     A complete configuration, with differences between Apache 2.0 and
     Apache 2.2 marked in bold, would look something like:
-    
+
     .. parsed-literal::
-    
+
         **LoadModule auth_basic_module modules/mod_auth_basic.so**
         **LoadModule authz_user_module modules/mod_authz_user.so**
-    
+
         ...
-    
-        <Location /exmaple/>
+
+        <Location /example/>
             AuthType Basic
             AuthName "example.com"
             **AuthBasicAuthoritative Off**
@@ -71,7 +71,7 @@ with the standard ``Auth*`` and ``Require`` directives::
             SetEnv DJANGO_SETTINGS_MODULE mysite.settings
             PythonAuthenHandler django.contrib.auth.handlers.modpython
         </Location>
-        
+
 By default, the authentication handler will limit access to the ``/example/``
 location to users marked as staff members.  You can use a set of
 ``PythonOption`` directives to modify this behavior:
diff --git a/docs/cache.txt b/docs/cache.txt
index 8ba0383909..d598915d1a 100644
--- a/docs/cache.txt
+++ b/docs/cache.txt
@@ -119,8 +119,8 @@ in your database that is in the proper format that Django's database-cache
 system expects.
 
 Once you've created that database table, set your ``CACHE_BACKEND`` setting to
-``"db://tablename/"``, where ``tablename`` is the name of the database table.
-In this example, the cache table's name is ``my_cache_table``:
+``"db://tablename"``, where ``tablename`` is the name of the database table.
+In this example, the cache table's name is ``my_cache_table``::
 
     CACHE_BACKEND = 'db://my_cache_table'
 
@@ -228,7 +228,7 @@ entire site. Just add ``'django.middleware.cache.CacheMiddleware'`` to your
         'django.middleware.common.CommonMiddleware',
     )
 
-(The order of ``MIDDLEWARE_CLASSES`` matters. See "Order of MIDDLEWARE_CLASSES"
+(The order of ``MIDDLEWARE_CLASSES`` matters. See `Order of MIDDLEWARE_CLASSES`_
 below.)
 
 Then, add the following required settings to your Django settings file:
@@ -288,6 +288,36 @@ Or, using Python 2.4's decorator syntax::
 above example, the result of the ``slashdot_this()`` view will be cached for 15
 minutes.
 
+Template fragment caching
+=========================
+
+If you're after even more control, you can also cache template fragments using
+the ``cache`` template tag. To give your template access to this tag, put ``{%
+load cache %}`` near the top of your template.
+
+The ``{% cache %}`` template tag caches the contents of the block for a given
+amount of time. It takes at least two arguments: the cache timeout, in
+seconds, and the name to give the cache fragment. For example::
+
+    {% load cache %}
+    {% cache 500 sidebar %}
+        .. sidebar ..
+    {% endcache %}
+
+Sometimes you might want to cache multiple copies of a fragment depending on
+some dynamic data that appears inside the fragment. For example you may want a
+separate cached copy of the sidebar used in the previous example for every user
+of your site. This can be easily achieved by passing additional arguments to
+the ``{% cache %}`` template tag to uniquely identify the cache fragment::
+
+    {% load cache %}
+    {% cache 500 sidebar request.user.username %}
+        .. sidebar for logged in user ..
+    {% endcache %}
+
+If you need more than one argument to identify the fragment that's fine, simply
+pass as many arguments to ``{% cache %}`` as you need!
+
 The low-level cache API
 =======================
 
@@ -326,6 +356,15 @@ get() can take a ``default`` argument::
     >>> cache.get('my_key', 'has expired')
     'has expired'
 
+To add a key only if it doesn't already exist, there is an add() method.  It
+takes the same parameters as set(), but will not attempt to update the cache
+if the key specified is already present::
+
+    >>> cache.set('add_key', 'Initial value')
+    >>> cache.add('add_key', 'New value')
+    >>> cache.get('add_key')
+    'Initial value'
+
 There's also a get_many() interface that only hits the cache once. get_many()
 returns a dictionary with all the keys you asked for that actually exist in the
 cache (and haven't expired)::
@@ -524,7 +563,7 @@ the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom
 ``max_age`` in a ``cache_control`` decorator, the decorator will take
 precedence, and the header values will be merged correctly.)
 
-If you want to use headers to disable caching altogether, 
+If you want to use headers to disable caching altogether,
 ``django.views.decorators.never_cache`` is a view decorator that adds
 headers to ensure the response won't be cached by browsers or other caches. Example::
 
@@ -556,8 +595,11 @@ within the ``MIDDLEWARE_CLASSES`` setting, because the cache middleware needs
 to know which headers by which to vary the cache storage. Middleware always
 adds something to the ``Vary`` response header when it can.
 
-Put the ``CacheMiddleware`` after any middlewares that might add something to
-the ``Vary`` header. The following middlewares do so:
+Put the ``CacheMiddleware`` *before* any other middleware that might add
+something to the ``Vary`` header (response middleware is applied in reverse
+order). The following middleware modules do so:
 
     * ``SessionMiddleware`` adds ``Cookie``
     * ``GZipMiddleware`` adds ``Accept-Encoding``
+    * ``LocaleMiddleware`` adds ``Accept-Language``
+
diff --git a/docs/contributing.txt b/docs/contributing.txt
index 3200a87012..a842f4477a 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -335,6 +335,10 @@ Please follow these coding standards when writing code for inclusion in Django:
 
     * Unless otherwise specified, follow `PEP 8`_.
 
+      You could use  a tool like `pep8.py`_ to check for some problems in this
+      area, but remember that PEP 8 is only a guide, so respect the style of
+      the surrounding code as a primary goal.
+
     * Use four spaces for indentation.
 
     * Use underscores, not camelCase, for variable, function and method names
@@ -924,5 +928,6 @@ requests for commit access are potential flame-war starters, and will be ignored
 .. _`#django`: irc://irc.freenode.net/django
 .. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
 .. _PEP 8: http://www.python.org/peps/pep-0008.html
+.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py
 .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
 .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases
diff --git a/docs/databases.txt b/docs/databases.txt
index 213c2d666c..4530a1b896 100644
--- a/docs/databases.txt
+++ b/docs/databases.txt
@@ -76,6 +76,14 @@ the ``mysql`` backend.
 If you are trying to use an older version of MySQL and the ``mysql_old``
 backend, then 1.2.0 *might* work for you.
 
+.. note::
+    If you see ``ImportError: cannot import name ImmutableSet`` when trying to
+    use Django, your MySQLdb installation may contain an outdated ``sets.py``
+    file that conflicts with the built-in module of the same name from Python
+    2.4 and later. To fix this, verify that you have installed MySQLdb version
+    1.2.1p2 or newer, then delete the ``sets.py`` file in the MySQLdb
+    directory that was left by an earlier version.
+
 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
 
 Creating your database
diff --git a/docs/flatpages.txt b/docs/flatpages.txt
index 1422f16b6b..d082090689 100644
--- a/docs/flatpages.txt
+++ b/docs/flatpages.txt
@@ -48,7 +48,7 @@ with the given URL with a site ID that corresponds to the SITE_ID_ setting.
 If it finds a match, it follows this algorithm:
 
     * If the flatpage has a custom template, it loads that template. Otherwise,
-      it loads the template ``flatpages/default``.
+      it loads the template ``flatpages/default.html``.
     * It passes that template a single context variable, ``flatpage``, which is
       the flatpage object. It uses RequestContext_ in rendering the template.
 
diff --git a/docs/install.txt b/docs/install.txt
index 95aa82b2e3..519bf2674c 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -63,7 +63,10 @@ installed.
 * If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher.
   You will also want to read the database-specific notes for the `MySQL backend`_.
 
-* If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher.
+* If you're using SQLite and either Python 2.3 or Python 2.4, you'll need
+  pysqlite_. Use version 2.0.3 or higher. Python 2.5 ships with an sqlite
+  wrapper in the standard library, so you don't need to install anything extra
+  in that case.
 
 * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher.
   You will also want to read the database-specific notes for the `Oracle backend`_.
diff --git a/docs/middleware.txt b/docs/middleware.txt
index 63ba8c6999..30a4899a3e 100644
--- a/docs/middleware.txt
+++ b/docs/middleware.txt
@@ -178,8 +178,9 @@ request, before Django decides which view to execute.
 ``process_request()`` should return either ``None`` or an ``HttpResponse``
 object. If it returns ``None``, Django will continue processing this request,
 executing any other middleware and, then, the appropriate view. If it returns
-an ``HttpResponse`` object, Django won't bother calling ANY other middleware or
-the appropriate view; it'll return that ``HttpResponse``.
+an ``HttpResponse`` object, Django won't bother calling ANY other request,
+view or exception middleware, or the appropriate view; it'll return that
+``HttpResponse``. Response middleware is always called on every response.
 
 process_view
 ------------
@@ -197,8 +198,9 @@ arguments that will be passed to the view. Neither ``view_args`` nor
 return either ``None`` or an ``HttpResponse`` object. If it returns ``None``,
 Django will continue processing this request, executing any other
 ``process_view()`` middleware and, then, the appropriate view. If it returns an
-``HttpResponse`` object, Django won't bother calling ANY other middleware or
-the appropriate view; it'll return that ``HttpResponse``.
+``HttpResponse`` object, Django won't bother calling ANY other request, view
+or exception middleware, or the appropriate view; it'll return that
+``HttpResponse``. Response middleware is always called on every response.
 
 process_response
 ----------------
@@ -236,7 +238,8 @@ Guidelines
 
     * Feel free to look at Django's available middleware for examples. The
       core Django middleware classes are in ``django/middleware/`` in the
-      Django distribution. The session middleware is in ``django/contrib/sessions``.
+      Django distribution. The session middleware is in
+      ``django/contrib/sessions``.
 
     * If you write a middleware component that you think would be useful to
       other people, contribute to the community! Let us know, and we'll
diff --git a/docs/model-api.txt b/docs/model-api.txt
index a0844ea961..b49963d8f5 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -149,7 +149,7 @@ and in Django's validation.
 Django veterans: Note that the argument is now called ``max_length`` to
 provide consistency throughout Django. There is full legacy support for
 the old ``maxlength`` argument, but ``max_length`` is preferred.
-	
+
 ``CommaSeparatedIntegerField``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -678,7 +678,9 @@ set.
 
 If ``True``, this field must be unique throughout the table.
 
-This is enforced at the database level and at the Django admin-form level.
+This is enforced at the database level and at the Django admin-form level. If
+you try to add save a model with a duplicate value in a ``unique`` field, a
+``django.db.IntegrityError`` will be raised by the model's ``save()`` method.
 
 ``unique_for_date``
 ~~~~~~~~~~~~~~~~~~~
@@ -1584,8 +1586,8 @@ Finally, note that in order to use ``list_display_links``, you must define
 
 Set ``list_filter`` to activate filters in the right sidebar of the change list
 page of the admin. This should be a list of field names, and each specified
-field should be either a ``BooleanField``, ``CharField``, ``DateField``, 
-``DateTimeField``, ``IntegerField`` or ``ForeignKey``. 
+field should be either a ``BooleanField``, ``CharField``, ``DateField``,
+``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
 
 This example, taken from the ``django.contrib.auth.models.User`` model, shows
 how both ``list_display`` and ``list_filter`` work::
diff --git a/docs/modpython.txt b/docs/modpython.txt
index 4a8c169a51..5b20046168 100644
--- a/docs/modpython.txt
+++ b/docs/modpython.txt
@@ -87,17 +87,19 @@ lived under the ``weblog/`` directory, you would *also* need to add
 **parent directories** of anything you import directly must be on the Python
 path.
 
-.. caution::
+.. note::
 
-    If you're using Windows, remember that the path will contain backslashes.
-    This string is passed through Python's string parser twice, so you need to
-    escape each backslash **twice**::
+    If you're using Windows, it is still recommended that you use forward
+    slashes in the pathnames, even though Windows normally uses backslashes
+    for its native separator. Apache knows how to convert from the forward
+    slash format to the native format, so this approach is portable and easier
+    to read (it avoids tricky problems with having to double-escape
+    backslashes).
 
-        PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path"
+    This is valid even on a Windows system::
 
-    Or, use raw strings::
+        PythonPath "['c:/path/to/project'] + sys.path"
 
-        PythonPath "[r'c:\\path\\to\\project'] + sys.path"
 
 You can also add directives such as ``PythonAutoReload Off`` for performance.
 See the `mod_python documentation`_ for a full list of options.
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 2005adeec8..5e33a478ee 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -100,7 +100,7 @@ Start with this basic ``Form`` subclass, which we'll call ``ContactForm``::
         subject = forms.CharField(max_length=100)
         message = forms.CharField()
         sender = forms.EmailField()
-        cc_myself = forms.BooleanField()
+        cc_myself = forms.BooleanField(required=False)
 
 A form is composed of ``Field`` objects. In this case, our form has four
 fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. We'll explain
@@ -860,6 +860,23 @@ classes::
     <li>Instrument: <input type="text" name="instrument" /></li>
     <li>Haircut type: <input type="text" name="haircut_type" /></li>
 
+
+Prefixes for forms
+------------------
+
+You can put several Django forms inside one ``<form>`` tag. To give each
+``Form`` its own namespace you need to use the ``prefix`` keyword argument::
+
+    >>> mother = PersonForm(prefix="mother")
+    >>> father = PersonForm(prefix="father")
+    >>> print mother.as_ul()
+    <li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li>
+    <li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li>
+    >>> print father.as_ul()
+    <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
+    <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>
+
+
 Fields
 ======
 
@@ -1043,7 +1060,7 @@ fields. We've specified ``auto_id=False`` to simplify the output::
     ...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
     ...     message = forms.CharField()
     ...     sender = forms.EmailField(help_text='A valid e-mail address, please.')
-    ...     cc_myself = forms.BooleanField()
+    ...     cc_myself = forms.BooleanField(required=False)
     >>> f = HelpTextContactForm(auto_id=False)
     >>> print f.as_table()
     <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
@@ -1122,9 +1139,20 @@ For each field, we describe the default widget used if you don't specify
 ~~~~~~~~~~~~~~~~
 
     * Default widget: ``CheckboxInput``
-    * Empty value: ``None``
+    * Empty value: ``False``
     * Normalizes to: A Python ``True`` or ``False`` value.
-    * Validates nothing (i.e., it never raises a ``ValidationError``).
+    * Validates that the check box is checked (i.e. the value is ``True``) if
+      the field has ``required=True``.
+
+**New in Django development version:** The empty value for a ``CheckboxInput``
+(and hence the standard ``BooleanField``) has changed to return ``False``
+instead of ``None`` in the development version.
+
+.. note::
+    Since all ``Field`` subclasses have ``required=True`` by default, the
+    validation condition here is important. If you want to include a checkbox
+    in your form that can be either checked or unchecked, you must remember to
+    pass in ``required=False`` when creating the ``BooleanField``.
 
 ``CharField``
 ~~~~~~~~~~~~~
@@ -1132,7 +1160,8 @@ For each field, we describe the default widget used if you don't specify
     * Default widget: ``TextInput``
     * Empty value: ``''`` (an empty string)
     * Normalizes to: A Unicode object.
-    * Validates nothing, unless ``max_length`` or ``min_length`` is provided.
+    * Validates ``max_length`` or ``min_length``, if they are provided.
+      Otherwise, all inputs are valid.
 
 Has two optional arguments for validation, ``max_length`` and ``min_length``.
 If provided, these arguments ensure that the string is at most or at least the
@@ -1172,7 +1201,7 @@ If no ``input_formats`` argument is provided, the default input formats are::
 ``DateTimeField``
 ~~~~~~~~~~~~~~~~~
 
-    * Default widget: ``TextInput``
+    * Default widget: ``DateTimeInput``
     * Empty value: ``None``
     * Normalizes to: A Python ``datetime.datetime`` object.
     * Validates that the given value is either a ``datetime.datetime``,
@@ -1193,6 +1222,9 @@ If no ``input_formats`` argument is provided, the default input formats are::
     '%m/%d/%y %H:%M',        # '10/25/06 14:30'
     '%m/%d/%y',              # '10/25/06'
 
+**New in Django development version:** The ``DateTimeField`` used to use a
+``TextInput`` widget by default. This has now changed.
+
 ``DecimalField``
 ~~~~~~~~~~~~~~~~
 
@@ -1508,7 +1540,7 @@ like so::
         subject = forms.CharField(max_length=100)
         message = forms.CharField()
         senders = MultiEmailField()
-        cc_myself = forms.BooleanField()
+        cc_myself = forms.BooleanField(required=False)
 
 Widgets
 =======
@@ -1529,6 +1561,7 @@ commonly used groups of widgets:
     ``MultipleHiddenInput``       Multiple ``<input type='hidden' ...``
                                   instances.
     ``FileInput``                 ``<input type='file' ...``
+    ``DateTimeInput``             ``<input type='text' ...``
     ``Textarea``                  ``<textarea>...</textarea>``
     ``CheckboxInput``             ``<input type='checkbox' ...``
     ``Select``                    ``<select><option ...``
@@ -1542,6 +1575,9 @@ commonly used groups of widgets:
                                   one for the Date, and one for the Time.
     ============================  ===========================================
 
+**New in Django development version:** The ``DateTimeInput`` has been added
+since the last release.
+
 Specifying widgets
 ------------------
 
@@ -2033,7 +2069,7 @@ have a ``Message`` model that holds each contact submission. Something like::
         subject = models.CharField(max_length=100)
         message = models.TextField()
         sender = models.EmailField()
-        cc_myself = models.BooleanField()
+        cc_myself = models.BooleanField(required=False)
 
 You could use this model to create a form (using ``form_for_model()``). You
 could also use existing ``Message`` instances to create a form for editing
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 7806886841..8da00cdf09 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -381,8 +381,8 @@ Methods
     ``mimetype``. Historically, the parameter was only called ``mimetype``,
     but since this is actually the value included in the HTTP ``Content-Type``
     header, it can also include the character set encoding, which makes it
-    more than just a MIME type specification. If ``mimetype`` is specifiedi
-    (not None), that value is used.  Otherwise, ``content_type`` is used. If
+    more than just a MIME type specification. If ``mimetype`` is specified
+    (not None), that value is used. Otherwise, ``content_type`` is used. If
     neither is given, the ``DEFAULT_CONTENT_TYPE`` setting is used.
 
 ``__setitem__(header, value)``
diff --git a/docs/settings.txt b/docs/settings.txt
index 7ad1f6441d..6241749753 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -172,7 +172,7 @@ of the case of the actual model class name.
 ADMIN_FOR
 ---------
 
-Default: ``()`` (Empty list)
+Default: ``()`` (Empty tuple)
 
 Used for admin-site settings modules, this should be a tuple of settings
 modules (in the format ``'foo.bar.baz'``) for which this site is an admin.
@@ -475,7 +475,7 @@ FIXTURE_DIRS
 Default: ``()`` (Empty tuple)
 
 List of locations of the fixture data files, in search order. Note that
-these paths should use Unix-style forward slashes, even on Windows. See 
+these paths should use Unix-style forward slashes, even on Windows. See
 `Testing Django Applications`_.
 
 .. _Testing Django Applications: ../testing/
@@ -578,6 +578,17 @@ strings for translation, but the translation won't happen at runtime -- so
 you'll have to remember to wrap the languages in the *real* ``gettext()`` in
 any code that uses ``LANGUAGES`` at runtime.
 
+LOCALE_PATHS
+------------
+
+Default: ``()`` (Empty tuple)
+
+A list of directories where Django looks for translation files.
+See the `internationalization docs section`_ explaining the variable and the
+default behavior.
+
+.. _internationalization docs section: ../i18n/#using-translations-in-your-own-projects
+
 LOGIN_REDIRECT_URL
 ------------------
 
@@ -720,8 +731,8 @@ SERIALIZATION_MODULES
 
 Default: Not defined.
 
-A dictionary of modules containing serializer definitions (provided as 
-strings), keyed by a string identifier for that serialization type. For 
+A dictionary of modules containing serializer definitions (provided as
+strings), keyed by a string identifier for that serialization type. For
 example, to define a YAML serializer, use::
 
     SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' }
@@ -743,10 +754,10 @@ Default: ``django.contrib.sessions.backends.db``
 
 Controls where Django stores session data. Valid values are:
 
-    * ``'django.contrib.sessions.backends.db'``      
-    * ``'django.contrib.sessions.backends.file'``    
+    * ``'django.contrib.sessions.backends.db'``
+    * ``'django.contrib.sessions.backends.file'``
     * ``'django.contrib.sessions.backends.cache'``
-    
+
 See the `session docs`_ for more details.
 
 SESSION_COOKIE_AGE
@@ -773,6 +784,18 @@ Default: ``'sessionid'``
 The name of the cookie to use for sessions. This can be whatever you want.
 See the `session docs`_.
 
+SESSION_COOKIE_PATH
+-------------------
+
+**New in Django development version**
+
+Default: ``'/'``
+
+The path set on the session cookie. Should match the URL path of your Django
+installation (or be parent of that path). This is useful if you have multiple
+Django instances running under the same hostname; they can use different
+cookie paths and each instance will only see its own session cookie.
+
 SESSION_COOKIE_SECURE
 ---------------------
 
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index 393572f3e2..30943591b8 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -547,6 +547,22 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas
 
         copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
 
+        # TTL -- One of the following three is optional. The framework looks
+        # for them in this order. Ignored for Atom feeds.
+
+        def ttl(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            TTL (Time to live) as a normal Python string.
+            """
+
+        def ttl(self):
+            """
+            Returns the feed's ttl as a normal Python string.
+            """
+
+        ttl = 600 # Hard-coded Time to live.
+
         # ITEMS -- One of the following three is required. The framework looks
         # for them in this order.
 
diff --git a/docs/templates.txt b/docs/templates.txt
index cd436a987d..5d5f657747 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -2,13 +2,35 @@
 The Django template language: For template authors
 ==================================================
 
+This document explains the language syntax of the Django template system.  If
+you're looking for a more technical perspective on how it works and how to
+extend it, see `The Django template language: For Python programmers`_.
+
 Django's template language is designed to strike a balance between power and
 ease. It's designed to feel comfortable to those used to working with HTML. If
 you have any exposure to other text-based template languages, such as Smarty_
 or CheetahTemplate_, you should feel right at home with Django's templates.
 
+.. admonition:: Philosophy
+
+    If you have a background in programming, or if you're used to languages
+    like PHP which mix programming code directly into HTML, you'll want to
+    bear in mind that the Django template system is not simply Python embedded
+    into HTML. This is by design: the template system is meant to express
+    presentation, not program logic.
+
+    The Django template system provides tags which function similarly to some
+    programming constructs -- an ``{% if %}`` tag for boolean tests, a ``{%
+    for %}`` tag for looping, etc. -- but these are not simply executed as the
+    corresponding Python code, and the template system will not execute
+    arbitrary Python expressions. Only the tags, filters and syntax listed
+    below are supported by default (although you can add `your own
+    extensions`_ to the template language as needed).
+
+.. _`The Django template language: For Python programmers`: ../templates_python/
 .. _Smarty: http://smarty.php.net/
 .. _CheetahTemplate: http://www.cheetahtemplate.org/
+.. _your own extensions: ../templates_python/#extending-the-template-system
 
 Templates
 =========
@@ -377,7 +399,7 @@ loop::
             ...
         </tr>
     {% endfor %}
- 
+
 Outside of a loop, give the values a unique name the first time you call it,
 then use that name each successive time through::
 
@@ -385,16 +407,16 @@ then use that name each successive time through::
         <tr class="{% cycle rowcolors %}">...</tr>
         <tr class="{% cycle rowcolors %}">...</tr>
 
-You can use any number of values, separated by spaces. Values enclosed in 
-single (') or double quotes (") are treated as string literals, while values 
-without quotes are assumed to refer to context variables. 
+You can use any number of values, separated by spaces. Values enclosed in
+single (') or double quotes (") are treated as string literals, while values
+without quotes are assumed to refer to context variables.
 
 You can also separate values with commas::
 
     {% cycle row1,row2,row3 %}
-    
-In this syntax, each value will be interpreted as literal text. The 
-comma-based syntax exists for backwards-compatibility, and should not be 
+
+In this syntax, each value will be interpreted as literal text. The
+comma-based syntax exists for backwards-compatibility, and should not be
 used for new projects.
 
 debug
@@ -454,6 +476,11 @@ This is equivalent to::
         {{ var3 }}
     {% endif %}{% endif %}{% endif %}
 
+You can also use a literal string as a fallback value in case all
+passed variables are False::
+
+    {% firstof var1 var2 var3 "fallback value" %}
+
 for
 ~~~
 
@@ -472,13 +499,13 @@ You can loop over a list in reverse by using ``{% for obj in list reversed %}``.
 If you need to loop over a list of lists, you can unpack the values
 in eachs sub-list into a set of known names. For example, if your context contains
 a list of (x,y) coordinates called ``points``, you could use the following
-to output the list of points:: 
+to output the list of points::
 
     {% for x, y in points %}
         There is a point at {{ x }},{{ y }}
     {% endfor %}
-    
-This can also be useful if you need to access the items in a dictionary. 
+
+This can also be useful if you need to access the items in a dictionary.
 For example, if your context contained a dictionary ``data``, the following
 would display the keys and values of the dictionary::
 
@@ -1438,12 +1465,3 @@ A collection of template tags that can be useful while designing a website,
 such as a generator of Lorem Ipsum text. See the `webdesign documentation`_.
 
 .. _webdesign documentation: ../webdesign/
-
-Next steps
-==========
-
-Read the document `The Django template language: For Python programmers`_ if
-you're interested in learning the template system from a technical
-perspective -- how it works and how to extend it.
-
-.. _The Django template language\: For Python programmers: ../templates_python/
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 4e97dcd541..9e0c287346 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -41,7 +41,7 @@ From the command line, ``cd`` into a directory where you'd like to store your
 code, then run the command ``django-admin.py startproject mysite``. This
 will create a ``mysite`` directory in your current directory.
 
-.. admonition:: Max OS X permissions
+.. admonition:: Mac OS X permissions
    
    If you're using Mac OS X, you may see the message "permission
    denied" when you try to run ``django-admin.py startproject``. This