boulder-oracle-sprint: Merged to [5078]

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

17 files changed, 83 insertions, 43 deletions

diff --git a/docs/api_stability.txt b/docs/api_stability.txt
index 3fd793b0fd..cfaffeac6b 100644
--- a/docs/api_stability.txt
+++ b/docs/api_stability.txt
@@ -100,14 +100,14 @@ change:
      
 .. _caching: ../cache/
 .. _custom template tags and libraries: ../templates_python/
-.. _database lookup: ../db_api/
+.. _database lookup: ../db-api/
 .. _django-admin utility: ../django-admin/
 .. _fastcgi integration: ../fastcgi/
 .. _flatpages: ../flatpages/
 .. _generic views: ../generic_views/
 .. _internationalization: ../i18n/
 .. _legacy database integration: ../legacy_databases/
-.. _model definition: ../model_api/
+.. _model definition: ../model-api/
 .. _mod_python integration: ../modpython/
 .. _redirects: ../redirects/
 .. _request/response objects: ../request_response/
diff --git a/docs/authentication.txt b/docs/authentication.txt
index aff336f67a..14ca581877 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -144,7 +144,7 @@ custom methods:
       Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site
       doesn't allow profiles.
 
-.. _Django model: ../model_api/
+.. _Django model: ../model-api/
 .. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email
 
 Manager functions
@@ -204,9 +204,11 @@ The ``password`` attribute of a ``User`` object is a string in this format::
 
 That's hashtype, salt and hash, separated by the dollar-sign character.
 
-Hashtype is either ``sha1`` (default) or ``md5`` -- the algorithm used to
-perform a one-way hash of the password. Salt is a random string used to salt
-the raw password to create the hash.
+Hashtype is either ``sha1`` (default), ``md5`` or ``crypt`` -- the algorithm
+used to perform a one-way hash of the password. Salt is a random string used
+to salt the raw password to create the hash. Note that the ``crypt`` method is
+only supported on platforms that have the standard Python ``crypt`` module
+available.
 
 For example::
 
@@ -387,14 +389,15 @@ introduced in Python 2.4::
 
 ``login_required`` does the following:
 
-    * If the user isn't logged in, redirect to ``/accounts/login/``, passing
-      the current absolute URL in the query string as ``next``. For example:
+    * If the user isn't logged in, redirect to ``settings.LOGIN_URL``
+      (``/accounts/login/`` by default), passing the current absolute URL
+      in the query string as ``next``. For example:
       ``/accounts/login/?next=/polls/3/``.
     * If the user is logged in, execute the view normally. The view code is
       free to assume the user is logged in.
 
-Note that you'll need to map the appropriate Django view to ``/accounts/login/``.
-To do this, add the following line to your URLconf::
+Note that you'll need to map the appropriate Django view to ``settings.LOGIN_URL``.
+For example, using the defaults, add the following line to your URLconf::
 
     (r'^accounts/login/$', 'django.contrib.auth.views.login'),
 
@@ -405,9 +408,9 @@ Here's what ``django.contrib.auth.views.login`` does:
 
     * If called via ``POST``, it tries to log the user in. If login is
       successful, the view redirects to the URL specified in ``next``. If
-      ``next`` isn't provided, it redirects to ``/accounts/profile/`` (which is
-      currently hard-coded). If login isn't successful, it redisplays the login
-      form.
+      ``next`` isn't provided, it redirects to ``settings.LOGIN_REDIRECT_URL``
+      (which defaults to ``/accounts/profile/``). If login isn't successful,
+      it redisplays the login form.
 
 It's your responsibility to provide the login form in a template called
 ``registration/login.html`` by default. This template gets passed three
@@ -487,7 +490,7 @@ Logs a user out, then redirects to the login page.
 **Optional arguments:**
 
     * ``login_url``: The URL of the login page to redirect to. This
-      will default to ``/accounts/login/`` if not supplied.
+      will default to ``settings.LOGIN_URL`` if not supplied.
 
 ``django.contrib.auth.views.password_change``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -569,7 +572,7 @@ successful login.
 **Optional arguments:**
 
     * ``login_url``: The URL of the login page to redirect to. This
-      will default to ``/accounts/login/`` if not supplied.
+      will default to ``settings.LOGIN_URL`` if not supplied.
 
 Built-in manipulators
 ---------------------
@@ -636,7 +639,7 @@ Note that ``user_passes_test`` does not automatically check that the ``User``
 is not anonymous.
 
 ``user_passes_test()`` takes an optional ``login_url`` argument, which lets you
-specify the URL for your login page (``/accounts/login/`` by default).
+specify the URL for your login page (``settings.LOGIN_URL`` by default).
 
 Example in Python 2.3 syntax::
 
@@ -680,7 +683,7 @@ parameter. Example::
     my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view)
 
 As in the ``login_required`` decorator, ``login_url`` defaults to
-``'/accounts/login/'``.
+``settings.LOGIN_URL``.
 
 Limiting access to generic views
 --------------------------------
@@ -757,7 +760,7 @@ This example model creates three custom permissions::
 The only thing this does is create those extra permissions when you run
 ``syncdb``.
 
-.. _model Meta attribute: ../model_api/#meta-options
+.. _model Meta attribute: ../model-api/#meta-options
 
 API reference
 -------------
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 64db3def96..d2aa6b8bb3 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -6,7 +6,7 @@ Once you've created your `data models`_, Django automatically gives you a
 database-abstraction API that lets you create, retrieve, update and delete
 objects. This document explains that API.
 
-.. _`data models`: ../model_api/
+.. _`data models`: ../model-api/
 
 Throughout this reference, we'll refer to the following models, which comprise
 a weblog application::
@@ -85,7 +85,7 @@ There's no way to tell what the value of an ID will be before you call
 unless you explicitly specify ``primary_key=True`` on a field. See the
 `AutoField documentation`_.)
 
-.. _AutoField documentation: ../model_api/#autofield
+.. _AutoField documentation: ../model-api/#autofield
 
 Explicitly specifying auto-primary-key values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1801,4 +1801,4 @@ interface to your database. You can access your database via other tools,
 programming languages or database frameworks; there's nothing Django-specific
 about your database.
 
-.. _Executing custom SQL: ../model_api/#executing-custom-sql
+.. _Executing custom SQL: ../model-api/#executing-custom-sql
diff --git a/docs/faq.txt b/docs/faq.txt
index f61af9cd92..d7d8f41146 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -513,7 +513,7 @@ type, create an initial data file and put something like this in it::
 As explained in the `SQL initial data file`_ documentation, this SQL file can
 contain arbitrary SQL, so you can make any sorts of changes you need to make.
 
-.. _SQL initial data file: ../model_api/#providing-initial-sql-data
+.. _SQL initial data file: ../model-api/#providing-initial-sql-data
 
 Why is Django leaking memory?
 -----------------------------
diff --git a/docs/flatpages.txt b/docs/flatpages.txt
index cb910e812d..1422f16b6b 100644
--- a/docs/flatpages.txt
+++ b/docs/flatpages.txt
@@ -84,9 +84,9 @@ Flatpages are represented by a standard `Django model`_, which lives in
 `django/contrib/flatpages/models.py`_. You can access flatpage objects via the
 `Django database API`_.
 
-.. _Django model: ../model_api/
+.. _Django model: ../model-api/
 .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
-.. _Django database API: ../db_api/
+.. _Django database API: ../db-api/
 
 Flatpage templates
 ==================
diff --git a/docs/forms.txt b/docs/forms.txt
index ce1010235f..144b70f13b 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -691,5 +691,5 @@ fails. If no message is passed in, a default message is used.
     document for more details).
 
 .. _`generic views`: ../generic_views/
-.. _`models API`: ../model_api/
+.. _`models API`: ../model-api/
 .. _settings: ../settings/
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 5f7a669652..bb5f7320f6 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -71,7 +71,7 @@ are first evaluated, so if you want to pass in a QuerySet via
 ``extra_context`` that is always fresh you need to wrap it in a function or
 lambda that returns the QuerySet.
 
-.. _database API docs: ../db_api/
+.. _database API docs: ../db-api/
 
 "Simple" generic views
 ======================
diff --git a/docs/i18n.txt b/docs/i18n.txt
index 4a05e53ddf..56e6f7e02c 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -175,7 +175,7 @@ class, though::
             verbose_name = _('my thing')
             verbose_name_plural = _('mythings')
 
-.. _Django models: ../model_api/
+.. _Django models: ../model-api/
 
 Pluralization
 ~~~~~~~~~~~~~
diff --git a/docs/model-api.txt b/docs/model-api.txt
index b71668e37f..a14c469661 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -194,14 +194,23 @@ This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to
 ``FileField``
 ~~~~~~~~~~~~~
 
-A file-upload field.
+A file-upload field. Has one **required** argument:
 
-Has an extra required argument, ``upload_to``, a local filesystem path to
-which files should be upload. This path may contain `strftime formatting`_,
-which will be replaced by the date/time of the file upload (so that
-uploaded files don't fill up the given directory).
+    ======================  ===================================================
+    Argument                Description
+    ======================  ===================================================
+    ``upload_to``           A local filesystem path that will be appended to
+                            your ``MEDIA_ROOT`` setting to determine the
+                            output of the ``get_<fieldname>_url()`` helper
+                            function.
+    ======================  ===================================================
+
+This path may contain `strftime formatting`_, which will be replaced by the
+date/time of the file upload (so that uploaded files don't fill up the given
+directory).
 
-The admin represents this as an ``<input type="file">`` (a file-upload widget).
+The admin represents this field as an ``<input type="file">`` (a file-upload
+widget).
 
 Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few
 steps:
@@ -246,7 +255,7 @@ visiting its URL on your site. Don't allow that.
 
 A field whose choices are limited to the filenames in a certain directory
 on the filesystem. Has three special arguments, of which the first is
-required:
+**required**:
 
     ======================  ===================================================
     Argument                Description
diff --git a/docs/redirects.txt b/docs/redirects.txt
index 5f84f28097..4df60d473f 100644
--- a/docs/redirects.txt
+++ b/docs/redirects.txt
@@ -66,6 +66,6 @@ Redirects are represented by a standard `Django model`_, which lives in
 `django/contrib/redirects/models.py`_. You can access redirect
 objects via the `Django database API`_.
 
-.. _Django model: ../model_api/
+.. _Django model: ../model-api/
 .. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py
-.. _Django database API: ../db_api/
+.. _Django database API: ../db-api/
diff --git a/docs/request_response.txt b/docs/request_response.txt
index c0272461ca..0b985d563b 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -93,6 +93,7 @@ All attributes except ``session`` should be considered read-only.
         * ``CONTENT_TYPE``
         * ``HTTP_ACCEPT_ENCODING``
         * ``HTTP_ACCEPT_LANGUAGE``
+        * ``HTTP_HOST`` -- The HTTP Host header sent by the client.
         * ``HTTP_REFERER`` -- The referring page, if any.
         * ``HTTP_USER_AGENT`` -- The client's user-agent string.
         * ``QUERY_STRING`` -- The query string, as a single (unparsed) string.
diff --git a/docs/serialization.txt b/docs/serialization.txt
index 48ab46f0f9..8af4da26a8 100644
--- a/docs/serialization.txt
+++ b/docs/serialization.txt
@@ -27,7 +27,7 @@ data to (see `Serialization formats`_) and a QuerySet_ to serialize.
 (Actually, the second argument can be any iterator that yields Django objects,
 but it'll almost always be a QuerySet).
 
-.. _QuerySet: ../db_api/#retrieving-objects
+.. _QuerySet: ../db-api/#retrieving-objects
 
 You can also use a serializer object directly::
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 9ade249f24..5315c683c7 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -562,6 +562,21 @@ 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.
 
+LOGIN_URL
+---------
+
+Default: ``'/accounts/login/'``
+
+The URL where requests are redirected for login, specially when using the
+`@login_required`_ decorator.
+
+LOGOUT_URL
+----------
+
+Default: ``'/accounts/logout/'``
+
+LOGIN_URL counterpart.
+
 MANAGERS
 --------
 
@@ -620,6 +635,16 @@ locales have different formats. For example, U.S. English would say
 See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT,
 TIME_FORMAT and YEAR_MONTH_FORMAT.
 
+LOGIN_REDIRECT_URL
+------------------
+
+Default: ``'/accounts/profile/'``
+
+The URL where requests are redirected after login when the
+``contrib.auth.login`` view gets no ``next`` parameter.
+
+This is used by the `@login_required`_ decorator, for example.
+
 PREPEND_WWW
 -----------
 
@@ -874,7 +899,7 @@ Default: ``Django/<version> (http://www.djangoproject.com/)``
 The string to use as the ``User-Agent`` header when checking to see if URLs
 exist (see the ``verify_exists`` option on URLField_).
 
-.. _URLField: ../model_api/#urlfield
+.. _URLField: ../model-api/#urlfield
 
 USE_ETAGS
 ---------
@@ -1012,6 +1037,8 @@ Also, it's an error to call ``configure()`` more than once, or to call
 It boils down to this: Use exactly one of either ``configure()`` or
 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
 
+.. _@login_required: ../authentication/#the-login-required-decorator
+
 Error reporting via e-mail
 ==========================
 
diff --git a/docs/sites.txt b/docs/sites.txt
index 7497d7dd80..12259b04c3 100644
--- a/docs/sites.txt
+++ b/docs/sites.txt
@@ -276,8 +276,8 @@ you want your admin site to have access to all objects (not just site-specific
 ones), put ``objects = models.Manager()`` in your model, before you define
 ``CurrentSiteManager``.
 
-.. _manager: ../model_api/#managers
-.. _manager documentation: ../model_api/#managers
+.. _manager: ../model-api/#managers
+.. _manager documentation: ../model-api/#managers
 
 How Django uses the sites framework
 ===================================
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index 2a09307e09..c3b02b5d3f 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -159,7 +159,7 @@ put into those elements.
              {{ obj.description }}
 
 .. _chicagocrime.org: http://www.chicagocrime.org/
-.. _object-relational mapper: ../db_api/
+.. _object-relational mapper: ../db-api/
 .. _Django templates: ../templates/
 
 A complex example
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 7657bc7bf7..c40b051b19 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -577,5 +577,5 @@ For full details on the database API, see our `Database API reference`_.
 When you're comfortable with the API, read `part 2 of this tutorial`_ to get
 Django's automatic admin working.
 
-.. _Database API reference: ../db_api/
+.. _Database API reference: ../db-api/
 .. _part 2 of this tutorial: ../tutorial02/
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index e3d5d4dfc5..6fee842f8b 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -219,7 +219,7 @@ template. Note that we use ``dict()`` to return an altered dictionary in place.
     If you'd like to know more about how that works, The Django database API
     documentation `explains the lazy nature of QuerySet objects`_.
 
-.. _explains the lazy nature of QuerySet objects: ../db_api/#querysets-are-lazy
+.. _explains the lazy nature of QuerySet objects: ../db-api/#querysets-are-lazy
 
 In previous parts of the tutorial, the templates have been provided with a context
 that contains the ``poll`` and ``latest_poll_list`` context variables. However,