magic-removal: Merged to [1774]

git-svn-id: http://code.djangoproject.com/svn/django/branches/magic-removal@1775 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/authentication.txt

@@ -438,6 +438,15 @@ Authentication data in templates
 The currently logged-in user and his/her permissions are made available in the
 `template context`_ when you use ``DjangoContext``.
 
+.. admonition:: Technicality
+
+   Technically, these variables are only made available in the template context
+   if you use ``DjangoContext`` *and* your ``TEMPLATE_CONTEXT_PROCESSORS``
+   setting contains ``"django.core.context_processors.auth"``, which is default.
+   For more, see the `DjangoContext docs`_.
+
+   .. _DjangoContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext
+
 Users
 -----
 
@@ -454,7 +463,7 @@ Permissions
 -----------
 
 The currently logged-in user's permissions are stored in the template variable
-``{{ perms }}``. This is an instance of ``django.core.extensions.PermWrapper``,
+``{{ perms }}``. This is an instance of ``django.core.context_processors.PermWrapper``,
 which is a template-friendly proxy of permissions.
 
 In the ``{{ perms }}`` object, single-attribute lookup is a proxy to

docs/contributing.txt

@@ -120,6 +120,24 @@ Patch style
       it obvious that the ticket includes a patch, and it will add the ticket
       to the `list of tickets with patches`_.
 
+Submitting and maintaining translations
+=======================================
+
+Various parts of Django, such as the admin site and validator error messages,
+are internationalized. This means they display different text depending on a
+user's language setting.
+
+These translations are contributed by Django users worldwide. If you find an
+incorrect translation, or if you'd like to add a language that isn't yet
+translated, here's what to do:
+
+    * Join the `Django i18n mailing list`_ and introduce yourself.
+    * Create and submit translations using the methods described in the
+      `i18n documentation`_.
+
+.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
+.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/
+
 Coding style
 ============
 
@@ -205,15 +223,22 @@ trunk more than once.
 Using branches
 --------------
 
-To test a given branch, you can simply check out the entire branch. Or, if
-you've got a working directory you'd like to switch to use a branch, you can
-use::
+To test a given branch, you can simply check out the entire branch, like so::
+
+    svn co http://code.djangoproject.com/svn/django/branches/<branch>/
+
+Or, if you've got a working directory you'd like to switch to use a branch,
+you can use::
 
     svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
 
 ...in the root of your Django sandbox (the directory that contains ``django``,
 ``docs``, and ``tests``).
 
+The advantage of using ``svn switch`` instead of ``svn co`` is that the
+``switch`` command retains any changes you might have made to your local copy
+of the code. It attempts to merge those changes into the "switched" code.
+
 Official releases
 =================
 

docs/db-api.txt

@@ -243,7 +243,7 @@ The ``|`` symbol signifies an "OR", so this (roughly) translates into::
 You can use ``&`` and ``|`` operators together, and use parenthetical grouping.
 Example::
 
-    polls.get_object(complex=(Q(question__startswith='Who') & (Q(pub_date__exact=date(2005, 5, 2)) | pub_date__exact=date(2005, 5, 6)))
+    polls.get_object(complex=(Q(question__startswith='Who') & (Q(pub_date__exact=date(2005, 5, 2)) | Q(pub_date__exact=date(2005, 5, 6))))
 
 This roughly translates into::
 

docs/generic_views.txt

@@ -128,9 +128,14 @@ arguments:
 
     ``extra_context``        A dictionary of extra data to put into the
                              template's context.
+
+    ``processors``           **New in Django development version.** A tuple of
+                             processors to apply to the ``DjangoContext`` of
+                             this view's template. See the `DjangoContext docs`_
     =======================  ==================================================
 
-.. _`database API docs`: http://www.djangoproject.com/documentation/db_api/
+.. _database API docs: http://www.djangoproject.com/documentation/db_api/
+.. _DjangoContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext
 
 The date-based generic functions are:
 
@@ -247,7 +252,7 @@ The list-detail generic-view framework (in the
 except the former simply has two views: a list of objects and an individual
 object page.
 
-All these views take the same three optional arguments as the date-based ones
+All these views take the same four optional arguments as the date-based ones
 -- and, clearly, they don't accept the ``date_field`` argument.
 
 Individual views are:
@@ -371,4 +376,3 @@ The create/update/delete views are:
 
         object
             The object about to be deleted
-

docs/i18n.txt

@@ -361,8 +361,10 @@ That's it. Your translations are ready for use.
 .. admonition:: A note to translators
 
     If you've created a translation in a language Django doesn't yet support,
-    please let us know! We'll add it to the global list of available languages
-    in the global Django settings (``settings.LANGUAGES``).
+    please let us know! See `Submitting and maintaining translations`_ for
+    the steps to take.
+
+    .. _Submitting and maintaining translations: http://www.djangoproject.com/documentation/contributing/
 
 How Django discovers language preference
 ========================================

docs/settings.txt

@@ -547,6 +547,21 @@ The ID, as an integer, of the current site in the ``sites`` database. This is
 used so that application data can hook into specific site(s) and a single
 database can manage content for multiple sites.
 
+TEMPLATE_CONTEXT_PROCESSORS
+---------------------------
+
+Default::
+
+    ("django.core.context_processors.auth",
+    "django.core.context_processors.debug",
+    "django.core.context_processors.i18n")
+
+**Only available in Django development version.**
+
+A tuple of callables that are used to populate the context in ``DjangoContext``.
+These callables take a request object as their argument and return a dictionary
+of items to be merged into the context.
+
 TEMPLATE_DEBUG
 --------------
 

docs/templates_python.txt

@@ -246,21 +246,77 @@ Subclassing Context: DjangoContext
 
 Django comes with a special ``Context`` class,
 ``django.core.extensions.DjangoContext``, that acts slightly differently than
-the normal ``django.core.template.Context``. It takes an ``HttpRequest`` object
-as its first argument, and it automatically populates the context with a few
-variables:
+the normal ``django.core.template.Context``. The first difference is that takes
+an `HttpRequest object`_ as its first argument. For example::
+
+    c = DjangoContext(request, {
+        'foo': 'bar',
+    }
+
+The second difference is that it automatically populates the context with a few
+variables, according to your `TEMPLATE_CONTEXT_PROCESSORS setting`_.
+
+The ``TEMPLATE_CONTEXT_PROCESSORS`` setting is a tuple of callables that take a
+request object as their argument and return a dictionary of items to be merged
+into the context. By default, ``TEMPLATE_CONTEXT_PROCESSORS`` is set to::
+
+    ("django.core.context_processors.auth",
+    "django.core.context_processors.debug",
+    "django.core.context_processors.i18n")
+
+Each processor is applied in order. That means, if one processor adds a
+variable to the context and a second processor adds a variable with the same
+name, the second will override the first. The default processors are explained
+below.
+
+Also, you can give ``DjangoContext`` a list of additional processors, using the
+optional, third positional argument, ``processors``. In this example, the
+``DjangoContext`` instance gets a ``ip_address`` variable::
+
+    def ip_address_processor(request):
+        return {'ip_address': request.META['REMOTE_ADDR']}
+
+    def some_view(request):
+        # ...
+        return DjangoContext({
+            'foo': 'bar',
+        }, [ip_address_processor])
+
+Note: The concept of template-context processors is new in the Django
+development version. In Django 0.90, ``DjangoContext`` automatically populates
+the context with all of the values explained below, but it's not possible to
+add and remove processors.
+
+Here's what each of the default processors does:
+
+.. _HttpRequest object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
+.. _TEMPLATE_CONTEXT_PROCESSORS setting: http://www.djangoproject.com/documentation/settings/#template-context_processors
+
+django.core.context_processors.auth
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
+``DjangoContext`` will contain these three variables:
 
     * ``user`` -- An ``auth.User`` instance representing the currently
       logged-in user (or an ``AnonymousUser`` instance, if the client isn't
       logged in). See the `user authentication docs`.
     * ``messages`` -- A list of ``auth.Message`` objects for the currently
       logged-in user.
-    * ``perms`` -- An instance of ``django.core.extensions.PermWrapper``,
+    * ``perms`` -- An instance of ``django.core.context_processors.PermWrapper``,
       representing the permissions that the currently logged-in user has. See
       the `permissions docs`_.
 
-Also, if your ``DEBUG`` setting is set to ``True``, every ``DjangoContext``
-instance has the following two extra variables:
+.. _user authentication docs: http://www.djangoproject.com/documentation/models/authentication/#users
+.. _permissions docs: http://www.djangoproject.com/documentation/models/authentication/#permissions
+
+django.core.context_processors.debug
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
+``DjangoContext`` will contain these two variables -- but only if your
+``DEBUG`` setting is set to ``True`` and the request's IP address
+(``request.META['REMOTE_ADDR']``) is in the ``INTERNAL_IPS`` setting:
 
     * ``debug`` -- ``True``. You can use this in templates to test whether
       you're in ``DEBUG`` mode.
@@ -268,6 +324,25 @@ instance has the following two extra variables:
       representing every SQL query that has happened so far during the request
       and how long it took. The list is in order by query.
 
+django.core.context_processors.i18n
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
+``DjangoContext`` will contain these two variables:
+
+    * ``LANGUAGES`` -- The value of the `LANGUAGES setting`_.
+    * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise,
+      the value of the `LANGUAGE_CODE setting`_.
+
+See the `internationalization docs`_ for more.
+
+.. _LANGUAGES setting: http://www.djangoproject.com/documentation/settings/#languages
+.. _LANGUAGE_CODE setting: http://www.djangoproject.com/documentation/settings/#language-code
+.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/
+
+Subclassing Context: Custom subclasses
+--------------------------------------
+
 Feel free to subclass ``Context`` yourself if you find yourself wanting to give
 each template something "automatically." For instance, if you want to give
 every template automatic access to the current time, use something like this::
@@ -287,9 +362,6 @@ This technique has two caveats:
     * You'll have to be careful not to set the variable ``current_time`` when
       you populate this context. If you do, you'll override the other one.
 
-.. _user authentication docs: http://www.djangoproject.com/documentation/models/authentication/#users
-.. _permissions docs: http://www.djangoproject.com/documentation/models/authentication/#permissions
-
 Loading templates
 -----------------