gis: Merged revisions 7643-7662,7667-7668,7672-7682,7686-7693,7695-7698,7700-7702,7704-7706,7710,7712-7729,7731-7732,7738-7758,7760-7766 via svnmerge from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@7768 bcc190cf-cafb-0310-a4f2-bffc1f526a37

13 files changed, 173 insertions, 69 deletions

diff --git a/docs/cache.txt b/docs/cache.txt
index e7e1cdd791..3318b2ad4a 100644
--- a/docs/cache.txt
+++ b/docs/cache.txt
@@ -336,6 +336,17 @@ template tag to uniquely identify the cache fragment::
 It's perfectly fine to specify more than one argument to identify the fragment.
 Simply pass as many arguments to ``{% cache %}`` as you need.
 
+The cache timeout can be a template variable, as long as the template variable
+resolves to an integer value. For example, if the template variable
+``my_timeout`` is set to the value ``600``, then the following two examples are
+equivalent::
+
+    {% cache 600 sidebar %} ... {% endcache %}
+    {% cache my_timeout sidebar %} ... {% endcache %}
+
+This feature is useful in avoiding repetition in templates. You can set the
+timeout in a variable, in one place, and just reuse that value.
+
 The low-level cache API
 =======================
 
diff --git a/docs/contributing.txt b/docs/contributing.txt
index c5f98bec11..686c440c96 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -238,14 +238,14 @@ Since a picture is worth a thousand words, let's start there:
 
 We've got two official roles here:
 
-    * Core developers: people with commit access who make the big decisions 
+    * Core developers: people with commit access who make the big decisions
       and write the bulk of the code.
 
     * Ticket triagers: trusted community members with a proven history of
       working with the Django community. As a result of this history, they
       have been entrusted by the core developers to make some of the smaller
       decisions about tickets.
-     
+
 Second, note the five triage stages:
 
     1. A ticket starts as "Unreviewed", meaning that nobody has examined
@@ -254,7 +254,7 @@ Second, note the five triage stages:
     2. "Design decision needed" means "this concept requires a design
        decision," which should be discussed either in the ticket comments or on
        `django-developers`_. The "Design decision needed" step will generally
-       only be used for feature requests. It can also be used for issues 
+       only be used for feature requests. It can also be used for issues
        that *might* be bugs, depending on opinion or interpretation. Obvious
        bugs (such as crashes, incorrect query results, or non-compliance with a
        standard) skip this step and move straight to "Accepted".
@@ -317,7 +317,7 @@ A ticket can be resolved in a number of ways:
         tickets, we keep all the discussion in one place, which helps everyone.
 
     "worksforme"
-        Used when the the ticket doesn't contain enough detail to replicate 
+        Used when the the ticket doesn't contain enough detail to replicate
         the original bug.
 
 If you believe that the ticket was closed in error -- because you're
@@ -332,50 +332,49 @@ reopen tickets that have been marked as "wontfix" by core developers.
 Triage by the general community
 -------------------------------
 
-Although the Core Developers and Ticket Triagers make the big decisions in
-the ticket triage process, there is also a lot that general community 
+Although the core developers and ticket triagers make the big decisions in
+the ticket triage process, there's also a lot that general community
 members can do to help the triage process. In particular, you can help out by:
 
-    * Closing "Unreviewed" tickets as "invalid", "worksforme", or "duplicate".
+    * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
 
-    * Promoting "Unreviewed" tickets to "Design Decision Required" if there
-      is a design decision that needs to be made, or "Accepted" if they are
-      an obvious bug.
+    * Promoting "Unreviewed" tickets to "Design decision needed" if a design
+      decision needs to be made, or "Accepted" in case of obvious bugs.
 
-    * Correcting the "Needs Tests", "Needs documentation", or "Has Patch" flags
+    * Correcting the "Needs tests", "Needs documentation", or "Has patch" flags
       for tickets where they are incorrectly set.
- 
+
     * Checking that old tickets are still valid. If a ticket hasn't seen
       any activity in a long time, it's possible that the problem has been
-      fixed, but the ticket hasn't been closed. 
+      fixed but the ticket hasn't yet been closed.
 
-    * Contact the owners of tickets that have been claimed, but have not seen 
-      any recent activity. If the owner doesn't respond after a week or so, 
+    * Contacting the owners of tickets that have been claimed but have not seen
+      any recent activity. If the owner doesn't respond after a week or so,
       remove the owner's claim on the ticket.
 
     * Identifying trends and themes in the tickets. If there a lot of bug reports
-      about a particular part of Django, it possibly indicates that we need
-      to consider refactoring that part of the code. If a trend is emerging,
-      you should raise it for discussion (referencing the relevant tickets)
-      on `django-developers`_.
+      about a particular part of Django, it may indicate we should consider
+      refactoring that part of the code. If a trend is emerging, you should
+      raise it for discussion (referencing the relevant tickets) on
+      `django-developers`_.
 
-However, we do ask that as a general community member working in the
-ticket database:
+However, we do ask the following of all general community members working in
+the ticket database:
 
-    * Please **don't** close tickets as "wontfix". The core developers will 
-      make the final determination of the fate of a ticket, usually after  
+    * Please **don't** close tickets as "wontfix." The core developers will
+      make the final determination of the fate of a ticket, usually after
       consultation with the community.
-    
+
     * Please **don't** promote tickets to "Ready for checkin" unless they are
-      *trivial* changes - for example, spelling mistakes or
-      broken links in documentation. 
+      *trivial* changes -- for example, spelling mistakes or broken links in
+      documentation.
 
-    * Please **don't** reverse a decision that has been made by a core 
-      developer. If you disagree with a discussion that has been made, 
+    * Please **don't** reverse a decision that has been made by a core
+      developer. If you disagree with a discussion that has been made,
       please post a message to `django-developers`_.
 
     * Please be conservative in your actions. If you're unsure if you should
-      be making a change, don't make the change - leave a comment with your 
+      be making a change, don't make the change -- leave a comment with your
       concerns on the ticket, or post a message to `django-developers`_.
 
 Submitting and maintaining translations
@@ -702,13 +701,8 @@ Django tarball. It's our policy to make sure all tests pass at all times.
 The tests cover:
 
     * Models and the database API (``tests/modeltests/``).
-    * The cache system (``tests/regressiontests/cache.py``).
-    * The ``django.utils.dateformat`` module (``tests/regressiontests/dateformat/``).
-    * Database typecasts (``tests/regressiontests/db_typecasts/``).
-    * The template system (``tests/regressiontests/templates/`` and
-      ``tests/regressiontests/defaultfilters/``).
-    * ``QueryDict`` objects (``tests/regressiontests/httpwrappers/``).
-    * Markup template tags (``tests/regressiontests/markup/``).
+    * Everything else in core Django code (``tests/regressiontests``)
+    * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
 
 We appreciate any and all contributions to the test suite!
 
@@ -744,6 +738,24 @@ If you're using another backend:
       deleted when the tests are finished. This means your user account needs
       permission to execute ``CREATE DATABASE``.
 
+If you want to run the full suite of tests, you'll need to install a number of
+dependencies:
+
+    *  PyYAML_
+    *  Markdown_
+    *  Textile_
+    *  Docutils_
+    *  setuptools_
+
+Each of these dependencies is optional. If you're missing any of them, the
+associated tests will be skipped.
+
+.. _PyYAML: http://pyyaml.org/wiki/PyYAML
+.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
+.. _Textile: http://pypi.python.org/pypi/textile
+.. _docutils: http://pypi.python.org/pypi/docutils/0.4
+.. _setuptools: http://pypi.python.org/pypi/setuptools/
+
 To run a subset of the unit tests, append the names of the test modules to the
 ``runtests.py`` command line. See the list of directories in
 ``tests/modeltests`` and ``tests/regressiontests`` for module names.
@@ -755,6 +767,22 @@ for generic relations and internationalization, type::
     PYTHONPATH=..
     ./runtests.py --settings=settings generic_relations i18n
 
+Contrib apps
+------------
+
+Tests for apps in ``django/contrib/`` go in their respective directories under
+``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
+multiple modules by using a ``tests`` directory in the normal Python way.)
+
+For the tests to be found, a ``models.py`` file must exist (it doesn't
+have to have anything in it). If you have URLs that need to be
+mapped, put them in ``tests/urls.py``.
+
+To run tests for just one contrib app (e.g. ``markup``), use the same
+method as above::
+
+    ./runtests.py --settings=settings markup
+
 Requesting features
 ===================
 
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 4e1c2c5791..f80d63797a 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -382,7 +382,7 @@ Pickling QuerySets
 
 If you pickle_ a ``QuerySet``, this will also force all the results to be
 loaded into memory prior to pickling. This is because pickling is usually used
-as a precursor to caching and when the cached queryset is reloaded, you want
+as a precursor to caching and when the cached ``QuerySet`` is reloaded, you want
 the results to already be present. This means that when you unpickle a
 ``QuerySet``, it contains the results at the moment it was pickled, rather
 than the results that are currently in the database.
@@ -1382,7 +1382,7 @@ and then converted into a query using the ``query`` attribute::
 
 This queryset will be evaluated as subselect statement::
 
-    SELET ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')
+    SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')
 
 startswith
 ~~~~~~~~~~
@@ -2040,7 +2040,7 @@ automatically saved to the database.
 One-to-one relationships
 ------------------------
 
-One-to-one relationships are very similar to Many-to-one relationships.
+One-to-one relationships are very similar to many-to-one relationships.
 If you define a OneToOneField on your model, instances of that model will have 
 access to the related object via a simple attribute of the model.
 
@@ -2053,8 +2053,8 @@ For example::
     ed = EntryDetail.objects.get(id=2)
     ed.entry # Returns the related Entry object.
 
-The difference comes in reverse queries. The related model in a One-to-one
-relationship also has access to a ``Manager`` object; however, that ``Manager``
+The difference comes in "reverse" queries. The related model in a one-to-one
+relationship also has access to a ``Manager`` object, but that ``Manager``
 represents a single object, rather than a collection of objects::
 
     e = Entry.objects.get(id=2)
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index 1d4dbf10be..309166fe94 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -438,6 +438,10 @@ means any Python code changes you make while the server is running will *not*
 take effect if the particular Python modules have already been loaded into
 memory.
 
+Example usage::
+
+    django-admin.py runserver --noreload
+
 Examples of using different ports and addresses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -467,14 +471,6 @@ documentation.
 
 .. _serving static files: ../static_files/
 
-Turning off auto-reload
-~~~~~~~~~~~~~~~~~~~~~~~
-
-To disable auto-reloading of code while the development server is running, use the
-``--noreload`` option, like so::
-
-    django-admin.py runserver --noreload
-
 shell
 -----
 
@@ -760,6 +756,17 @@ variable.
 Note that this option is unnecessary in ``manage.py``, because it uses
 ``settings.py`` from the current project by default.
 
+--traceback
+-----------
+
+Example usage::
+
+    django-admin.py syncdb --traceback
+
+By default, ``django-admin.py`` will show a simple error message whenever an
+error occurs. If you specify ``--traceback``, ``django-admin.py``  will
+output a full stack trace whenever an exception is raised.
+
 Extra niceties
 ==============
 
diff --git a/docs/form_preview.txt b/docs/form_preview.txt
index e6f9b05f25..e03de36187 100644
--- a/docs/form_preview.txt
+++ b/docs/form_preview.txt
@@ -69,12 +69,10 @@ How to use ``FormPreview``
 
        ...and add the following line to the appropriate model in your URLconf::
 
-           (r'^post/$', SomeModelFormPreview(forms.models.form_for_model(SomeModel))),
-
-       Or, if you already have a Form class defined for the model::
-
            (r'^post/$', SomeModelFormPreview(SomeModelForm)),
 
+       where ``SomeModelForm`` is a Form or ModelForm class for the model.
+
     4. Run the Django server and visit ``/post/`` in your browser.
 
 .. _template loader docs: ../templates_python/#loader-types
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 4ed4ede97a..1bed4ee818 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -662,8 +662,8 @@ Django will automatically add this field::
 Thus, you don't need to set ``primary_key=True`` on any of your fields
 unless you want to override the default primary-key behavior.
 
-``primary_key=True`` implies ``blank=False``, ``null=False`` and
-``unique=True``. Only one primary key is allowed on an object.
+``primary_key=True`` implies ``null=False`` and ``unique=True``. Only
+one primary key is allowed on an object.
 
 ``radio_admin``
 ~~~~~~~~~~~~~~~
@@ -681,7 +681,7 @@ 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. If
-you try to add save a model with a duplicate value in a ``unique`` field, a
+you try to 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``
@@ -822,7 +822,7 @@ relationship should work. All are optional:
     =======================  ============================================================
     Argument                 Description
     =======================  ============================================================
-    ``edit_inline``          If not ``False``, this related object is edited
+    ``edit_inline``          If ``True``, this related object is edited
                              "inline" on the related object's page. This means
                              that the object will not have its own admin
                              interface. Use either ``models.TABULAR`` or ``models.STACKED``,
@@ -2005,6 +2005,36 @@ In this way, you're tying the model's absolute URL to the view that is used
 to display it, without repeating the URL information anywhere. You can still
 use the ``get_absolute_url`` method in templates, as before.
 
+In some cases, such as the use of generic views or the re-use of
+custom views for multiple models, specifying the view function may
+confuse the reverse URL matcher (because multiple patterns point to
+the same view).
+
+For that problem, Django has **named URL patterns**. Using a named
+URL pattern, it's possible to give a name to a pattern, and then
+reference the name rather than the view function. A named URL
+pattern is defined by replacing the pattern tuple by a call to
+the ``url`` function)::
+
+    from django.conf.urls.defaults import *
+
+    url(r'^people/(\d+)/$',
+        'django.views.generic.list_detail.object_detail',
+        name='people_view'),
+
+...and then using that name to perform the reverse URL resolution instead
+of the view name::
+
+    from django.db.models import permalink
+
+    def get_absolute_url(self):
+        return ('people_view', [str(self.id)])
+    get_absolute_url = permalink(get_absolute_url)
+
+More details on named URL patterns are in the `URL dispatch documentation`_.
+
+.. _URL dispatch documentation: ../url_dispatch/#naming-url-patterns
+
 Executing custom SQL
 --------------------
 
diff --git a/docs/modelforms.txt b/docs/modelforms.txt
index a76d797527..73335a03a2 100644
--- a/docs/modelforms.txt
+++ b/docs/modelforms.txt
@@ -182,6 +182,13 @@ supplied, ``save()`` will update that instance. If it's not supplied,
     # Create a form to edit an existing Article.
     >>> a = Article.objects.get(pk=1)
     >>> f = ArticleForm(instance=a)
+    >>> f.save()
+
+    # Create a form to edit an existing Article, but use
+    # POST data to populate the form.
+    >>> a = Article.objects.get(pk=1)
+    >>> f = ArticleForm(request.POST, instance=a)
+    >>> f.save()
 
 Note that ``save()`` will raise a ``ValueError`` if the data in the form
 doesn't validate -- i.e., ``if form.errors``.
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 25d80fda54..04e4c1aaa0 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1382,6 +1382,20 @@ extra arguments:
                                 as choices.
     ==============  ==========  ===============================================
 
+``FloatField`` 
+~~~~~~~~~~~~~~ 
+
+    * Default widget: ``TextInput`` 
+    * Empty value: ``None`` 
+    * Normalizes to: A Python float. 
+    * Validates that the given value is an float. Leading and trailing 
+      whitespace is allowed, as in Python's ``float()`` function. 
+    * Error message keys: ``required``, ``invalid``, ``max_value``, 
+      ``min_value`` 
+	 
+Takes two optional arguments for validation, ``max_value`` and ``min_value``. 
+These control the range of values permitted in the field.
+
 ``ImageField``
 ~~~~~~~~~~~~~~
 
diff --git a/docs/sessions.txt b/docs/sessions.txt
index da083b7713..0c47f0deed 100644
--- a/docs/sessions.txt
+++ b/docs/sessions.txt
@@ -112,7 +112,7 @@ It also has these methods:
 
       Sets a test cookie to determine whether the user's browser supports
       cookies. Due to the way cookies work, you won't be able to test this
-      until the user's next page request. See "Setting test cookies" below for
+      until the user's next page request. See `Setting test cookies`_ below for
       more information.
 
     * ``test_cookie_worked()``
@@ -120,7 +120,7 @@ It also has these methods:
       Returns either ``True`` or ``False``, depending on whether the user's
       browser accepted the test cookie. Due to the way cookies work, you'll
       have to call ``set_test_cookie()`` on a previous, separate page request.
-      See "Setting test cookies" below for more information.
+      See `Setting test cookies`_ below for more information.
 
     * ``delete_test_cookie()``
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 02e458fcda..3fe999d0d2 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -388,8 +388,13 @@ be able to give backtraces without seeing sensitive (or offensive) settings.
 
 Still, note that there are always going to be sections of your debug output that
 are inappropriate for public consumption. File paths, configuration options, and
-the like all give attackers extra information about your server. Never deploy a
-site with ``DEBUG`` turned on.
+the like all give attackers extra information about your server. 
+
+It is also important to remember that when running with ``DEBUG`` turned on, Django
+will remember every SQL query it executes. This is useful when you are debugging,
+but on a production server, it will rapidly consume memory.
+
+Never deploy a site into production with ``DEBUG`` turned on.
 
 DEBUG_PROPAGATE_EXCEPTIONS
 --------------------------
@@ -958,7 +963,10 @@ See the `template documentation`_.
 TEMPLATE_LOADERS
 ----------------
 
-Default: ``('django.template.loaders.filesystem.load_template_source',)``
+Default::
+
+     ('django.template.loaders.filesystem.load_template_source',
+      'django.template.loaders.app_directories.load_template_source')
 
 A tuple of callables (as strings) that know how to import templates from
 various sources. See the `template documentation`_.
diff --git a/docs/templates.txt b/docs/templates.txt
index ea9f3fb6b2..3a557c1476 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -346,7 +346,7 @@ To avoid this problem, you have two options:
 
     * One, you can make sure to run each untrusted variable through the
       ``escape`` filter (documented below), which converts potentially harmful
-      HTML characters to unharmful ones. This was default the default solution
+      HTML characters to unharmful ones. This was the default solution
       in Django for its first few years, but the problem is that it puts the
       onus on *you*, the developer / template author, to ensure you're escaping
       everything. It's easy to forget to escape data.
@@ -819,7 +819,7 @@ The 'ifchanged' block tag is used within a loop. It has two possible uses.
 
 2. If given a variable, check whether that variable has changed. For
    example, the following shows the date every time it changes, but
-   only shows the hour if both the hour and the date has changed::
+   only shows the hour if both the hour and the date have changed::
 
         {% for date in days %}
             {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 43ef016ed4..a03ea215d2 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -1059,8 +1059,8 @@ Passing template variables to the tag
 
 Although you can pass any number of arguments to a template tag using
 ``token.split_contents()``, the arguments are all unpacked as
-string literals. A little more work is required in order to dynamic content (a
-template variable) to a template tag as an argument.
+string literals. A little more work is required in order to pass dynamic
+content (a template variable) to a template tag as an argument.
 
 While the previous examples have formatted the current time into a string and
 returned the string, suppose you wanted to pass in a ``DateTimeField`` from an
@@ -1169,10 +1169,11 @@ Our earlier ``current_time`` function could thus be written like this::
 In Python 2.4, the decorator syntax also works::
 
     @register.simple_tag
-    def current_time(token):
+    def current_time(format_string):
         ...
 
 A couple of things to note about the ``simple_tag`` helper function:
+
     * Checking for the required number of arguments, etc, has already been
       done by the time our function is called, so we don't need to do that.
     * The quotes around the argument (if any) have already been stripped away,
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index b84ecd5f7e..04863cc7fd 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -22,8 +22,8 @@ installed.
 .. admonition:: Where to get help:
 
     If you're having trouble going through this tutorial, please post a message
-    to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll
-    try to help.
+    to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` to chat
+    with other Django users who might be able to help.
 
 .. _django-users: http://groups.google.com/group/django-users
 .. _#django: irc://irc.freenode.net/django