unicode: Merged from trunk up to [5080].

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

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/

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
 -------------

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

docs/faq.txt

@@ -512,7 +512,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?
 -----------------------------

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
 ==================

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/

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
 ======================

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
 ~~~~~~~~~~~~~

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.
+    ======================  ===================================================
 
-The admin represents this as an ``<input type="file">`` (a file-upload widget).
+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 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

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/

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.

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::
 

docs/settings.txt

@@ -570,6 +570,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
 --------
 
@@ -628,6 +643,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
 -----------
 
@@ -882,7 +907,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
 ---------
@@ -1020,6 +1045,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
 ==========================
 

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
 ===================================

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

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/

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,