[multi-db] Merge trunk to [3354]

git-svn-id: http://code.djangoproject.com/svn/django/branches/multiple-db-support@3355 bcc190cf-cafb-0310-a4f2-bffc1f526a37

5 files changed, 125 insertions, 26 deletions

diff --git a/docs/i18n.txt b/docs/i18n.txt
index 1382d6df0c..da6983dd59 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -224,6 +224,13 @@ block::
     This will have {{ myvar }} inside.
     {% endblocktrans %}
 
+If you need to bind more than one expression inside a ``blocktrans`` tag,
+separate the pieces with ``and``::
+
+    {% blocktrans with book|title as book_t and author|title as author_t %}
+    This is {{ book_t }} by {{ author_t }}
+    {% endblocktrans %}
+
 To pluralize, specify both the singular and plural forms with the
 ``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and
 ``{% endblocktrans %}``. Example::
@@ -306,7 +313,7 @@ marked for translation. It creates (or updates) a message file in the directory
 ``conf/locale``. In the ``de`` example, the file will be
 ``conf/locale/de/LC_MESSAGES/django.po``.
 
-If run over your project source tree or your appliation source tree, it will
+If run over your project source tree or your application source tree, it will
 do the same, but the location of the locale directory is ``locale/LANG/LC_MESSAGES``
 (note the missing ``conf`` prefix).
 
@@ -349,7 +356,7 @@ A quick explanation:
 Long messages are a special case. There, the first string directly after the
 ``msgstr`` (or ``msgid``) is an empty string. Then the content itself will be
 written over the next few lines as one string per line. Those strings are
-directlyconcatenated. Don't forget trailing spaces within the strings;
+directly concatenated. Don't forget trailing spaces within the strings;
 otherwise, they'll be tacked together without whitespace!
 
 .. admonition:: Mind your charset
@@ -452,7 +459,7 @@ Notes:
       ``de``.
     * Only languages listed in the `LANGUAGES setting`_ can be selected. If
       you want to restrict the language selection to a subset of provided
-      languages (because your appliaction doesn't provide all those languages),
+      languages (because your application doesn't provide all those languages),
       set ``LANGUAGES`` to a list of languages. For example::
 
           LANGUAGES = (
@@ -465,6 +472,30 @@ Notes:
       en-us).
 
       .. _LANGUAGES setting: http://www.djangoproject.com/documentation/settings/#languages
+
+    * If you define a custom ``LANGUAGES`` setting, as explained in the
+      previous bullet, it's OK to mark the languages as translation strings
+      -- but use a "dummy" ``gettext()`` function, not the one in
+      ``django.utils.translation``. You should *never* import
+      ``django.utils.translation`` from within your settings file, because that
+      module in itself depends on the settings, and that would cause a circular
+      import.
+
+      The solution is to use a "dummy" ``gettext()`` function. Here's a sample
+      settings file::
+
+          gettext = lambda s: s
+
+          LANGUAGES = (
+              ('de', gettext('German')),
+              ('en', gettext('English')),
+          )
+
+      With this arrangement, ``make-messages.py`` will still find and mark
+      these 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.
+
     * The ``LocaleMiddleware`` can only select languages for which there is a
       Django-provided base translation. If you want to provide translations
       for your application that aren't already in the set of translations
@@ -623,7 +654,7 @@ The ``javascript_catalog`` view
 -------------------------------
 
 The main solution to these problems is the ``javascript_catalog`` view, which
-sends out a JavaScript code library with functions that mimick the ``gettext``
+sends out a JavaScript code library with functions that mimic the ``gettext``
 interface, plus an array of translation strings. Those translation strings are
 taken from the application, project or Django core, according to what you
 specify in either the {{{info_dict}}} or the URL.
@@ -641,7 +672,7 @@ You hook it up like this::
 Each string in ``packages`` should be in Python dotted-package syntax (the
 same format as the strings in ``INSTALLED_APPS``) and should refer to a package
 that contains a ``locale`` directory. If you specify multiple packages, all
-those catalogs aremerged into one catalog. This is useful if you have
+those catalogs are merged into one catalog. This is useful if you have
 JavaScript that uses strings from different applications.
 
 You can make the view dynamic by putting the packages into the URL pattern::
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 0dc98416a3..c4d57bf8c4 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1225,6 +1225,33 @@ A few special cases to note about ``list_display``:
                   return self.birthday.strftime('%Y')[:3] + "0's"
               decade_born_in.short_description = 'Birth decade'
 
+``list_display_links``
+----------------------
+
+Set ``list_display_links`` to control which fields in ``list_display`` should
+be linked to the "change" page for an object.
+
+By default, the change list page will link the first column -- the first field
+specified in ``list_display`` -- to the change page for each item. But
+``list_display_links`` lets you change which columns are linked. Set
+``list_display_links`` to a list or tuple of field names (in the same format as
+``list_display``) to link.
+
+``list_display_links`` can specify one or many field names. As long as the
+field names appear in ``list_display``, Django doesn't care how many (or how
+few) fields are linked. The only requirement is: If you want to use
+``list_display_links``, you must define ``list_display``.
+
+In this example, the ``first_name`` and ``last_name`` fields will be linked on
+the change list page::
+
+    class Admin:
+        list_display = ('first_name', 'last_name', 'birthday')
+        list_display_links = ('first_name', 'last_name')
+
+Finally, note that in order to use ``list_display_links``, you must define
+``list_display``, too.
+
 ``list_filter``
 ---------------
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 9e1c6b529b..099196e56e 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -501,6 +501,28 @@ specifies which languages are available for language selection. See the
 Generally, the default value should suffice. Only set this setting if you want
 to restrict language selection to a subset of the Django-provided languages.
 
+If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
+translation strings (as in the default value displayed above) -- but use a
+"dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
+You should *never* import ``django.utils.translation`` from within your
+settings file, because that module in itself depends on the settings, and that
+would cause a circular import.
+
+The solution is to use a "dummy" ``gettext()`` function. Here's a sample
+settings file::
+
+    gettext = lambda s: s
+
+    LANGUAGES = (
+        ('de', gettext('German')),
+        ('en', gettext('English')),
+    )
+
+With this arrangement, ``make-messages.py`` will still find and mark these
+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.
+
 MANAGERS
 --------
 
@@ -738,6 +760,13 @@ Note that this is the time zone to which Django will convert all dates/times --
 not necessarily the timezone of the server. For example, one server may serve
 multiple Django-powered sites, each with a separate time-zone setting.
 
+Normally, Django sets the ``os.environ['TZ']`` variable to the time zone you
+specify in the  ``TIME_ZONE`` setting. Thus, all your views and models will
+automatically operate in the correct time zone. However, if you're using the
+manual configuration option (see below), Django will *not* touch the ``TZ``
+environment variable, and it'll be up to you to ensure your processes are
+running in the correct environment.
+
 USE_ETAGS
 ---------
 
@@ -815,6 +844,15 @@ uppercase, with the same name as the settings described above. If a particular
 setting is not passed to ``configure()`` and is needed at some later point,
 Django will use the default setting value.
 
+Configuring Django in this fashion is mostly necessary -- and, indeed,
+recommended -- when you're using a piece of the framework inside a larger
+application.
+
+Consequently, when configured via ``settings.configure()``, Django will not
+make any modifications to the process environment variables. (See the
+explanation of ``TIME_ZONE``, above, for why this would normally occur.) It's
+assumed that you're already in full control of your environment in these cases.
+
 Custom default settings
 -----------------------
 
diff --git a/docs/templates.txt b/docs/templates.txt
index 4ba52b3263..6117bf7b84 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -47,7 +47,7 @@ explained later in this document.::
     JavaScript and CSV. You can use the template language for any text-based
     format.
 
-    Oh, and one more thing: Making humans edit XML is masochistic!
+    Oh, and one more thing: Making humans edit XML is sadistic!
 
 Variables
 =========
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 2fa837e424..d353abb5bc 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -643,7 +643,7 @@ the current date/time, formatted according to a parameter given in the tag, in
 `strftime syntax`_. It's a good idea to decide the tag syntax before anything
 else. In our case, let's say the tag should be used like this::
 
-    <p>The time is {% current_time "%Y-%M-%d %I:%M %p" %}.</p>
+    <p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>
 
 .. _`strftime syntax`: http://www.python.org/doc/current/lib/module-time.html#l2h-1941
 
@@ -653,10 +653,10 @@ object::
     from django import template
     def do_current_time(parser, token):
         try:
-            # Splitting by None == splitting by spaces.
-            tag_name, format_string = token.contents.split(None, 1)
+            # split_contents() knows not to split quoted strings.
+            tag_name, format_string = token.split_contents()
         except ValueError:
-            raise template.TemplateSyntaxError, "%r tag requires an argument" % token.contents[0]
+            raise template.TemplateSyntaxError, "%r tag requires a single argument" % token.contents[0]
         if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
             raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name
         return CurrentTimeNode(format_string[1:-1])
@@ -667,7 +667,13 @@ Notes:
       example.
 
     * ``token.contents`` is a string of the raw contents of the tag. In our
-      example, it's ``'current_time "%Y-%M-%d %I:%M %p"'``.
+      example, it's ``'current_time "%Y-%m-%d %I:%M %p"'``.
+
+    * The ``token.split_contents()`` method separates the arguments on spaces
+      while keeping quoted strings together. The more straightforward
+      ``token.contents.split()`` wouldn't be as robust, as it would naively
+      split on *all* spaces, including those within quoted strings. It's a good
+      idea to always use ``token.split_contents()``.
 
     * This function is responsible for raising
       ``django.template.TemplateSyntaxError``, with helpful messages, for
@@ -681,7 +687,7 @@ Notes:
 
     * The function returns a ``CurrentTimeNode`` with everything the node needs
       to know about this tag. In this case, it just passes the argument --
-      ``"%Y-%M-%d %I:%M %p"``. The leading and trailing quotes from the
+      ``"%Y-%m-%d %I:%M %p"``. The leading and trailing quotes from the
       template tag are removed in ``format_string[1:-1]``.
 
     * The parsing is very low-level. The Django developers have experimented
@@ -766,27 +772,24 @@ registers it with the template system.
 
 Our earlier ``current_time`` function could thus be written like this::
 
-    # This version of do_current_time takes only a single argument and returns
-    # a string.
+    def current_time(format_string):
+        return datetime.datetime.now().strftime(format_string)
 
-    def do_current_time(token):
-        try:
-            # Splitting by None == splitting by spaces.
-            tag_name, format_string = token.contents.split(None, 1)
-        except ValueError:
-            raise template.TemplateSyntaxError, "%r tag requires an argument" % token.contents[0]
-        if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
-            raise template.TemplateSyntaxError, "%r tag's argument should be in quotes" % tag_name
-        return datetime.datetime.now().strftime(self.format_string[1:-1])
-
-    register.simple_tag(do_current_time)
+    register.simple_tag(current_time)
 
 In Python 2.4, the decorator syntax also works::
 
     @register.simple_tag
-    def do_current_time(token):
+    def current_time(token):
         ...
 
+A couple of things to note about the ``simple_tag`` helper function:
+    * Only the (single) argument is passed into our 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,
+      so we just receive a plain string.
+
 Inclusion tags
 ~~~~~~~~~~~~~~