i18n: merged up to [954] from trunk. contains the big load of admin reworking stuff from adrian.

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

9 files changed, 97 insertions, 136 deletions

diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index 0faabbfcca..ad7ee9d137 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -192,10 +192,10 @@ Available options
 
 Example usage::
 
-    django-admin.py init --settings='myproject.settings.main'
+    django-admin.py init --settings=myproject.settings
 
 Explicitly specifies the settings module to use. The settings module should be
-in Python path syntax, e.g. "myproject.settings.main". If this isn't provided,
+in Python path syntax, e.g. "myproject.settings". If this isn't provided,
 ``django-admin.py`` will use the DJANGO_SETTINGS_MODULE environment variable.
 
 --pythonpath
diff --git a/docs/faq.txt b/docs/faq.txt
index 712f7b26a8..062bce730b 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -348,8 +348,7 @@ things:
     * Set the ``SESSION_COOKIE_DOMAIN`` setting in your admin config file
       to match your domain. For example, if you're going to
       "http://www.mysite.com/admin/" in your browser, in
-      "myproject.settings.admin" you should set ``SESSION_COOKIE_DOMAIN =
-      'www.mysite.com'``.
+      "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.mysite.com'``.
 
     * Some browsers (Firefox?) don't like to accept cookies from domains that
       don't have dots in them. If you're running the admin site on "localhost"
diff --git a/docs/middleware.txt b/docs/middleware.txt
index 33cb1a38e4..d920e88370 100644
--- a/docs/middleware.txt
+++ b/docs/middleware.txt
@@ -27,30 +27,15 @@ name. For example, here's the default ``MIDDLEWARE_CLASSES`` created by
         "django.middleware.doc.XViewMiddleware",
     )
 
-The default admin site has the following ``MIDDLEWARE_CLASSES`` set::
-
-    MIDDLEWARE_CLASSES = (
-        "django.middleware.sessions.SessionMiddleware",
-        "django.middleware.admin.AdminUserRequired",
-        "django.middleware.common.CommonMiddleware",
-    )
-
 Django applies middleware in the order it's defined in ``MIDDLEWARE_CLASSES``.
 
-For a regular (i.e., non-admin) Django installation, no middleware is required,
-but it's strongly suggested that you use ``CommonMiddleware``. For a Django
-admin site, ``SessionMiddleware`` and ``AdminUserRequired`` (in that order) are
-required.
+A Django installation doesn't require any middleware -- e.g.,
+``MIDDLEWARE_CLASSES`` can be empty, if you'd like -- but it's strongly
+suggested that you use ``CommonMiddleware``.
 
 Available middleware
 ====================
 
-django.middleware.admin.AdminUserRequired
------------------------------------------
-
-Limits site access to valid users with the ``is_staff`` flag set. This is
-required by Django's admin, and this middleware requires ``SessionMiddleware``.
-
 django.middleware.cache.CacheMiddleware
 ---------------------------------------
 
diff --git a/docs/model-api.txt b/docs/model-api.txt
index ee5f9ee723..85d2e58aca 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -249,7 +249,7 @@ Here are all available field types:
 
     The admin represents this as an ``<input type="file">`` (a file-upload widget).
 
-    Using a `FieldField` or an ``ImageField`` (see below) in a model takes a few
+    Using a ``FileField` or an ``ImageField`` (see below) in a model takes a few
     steps:
 
         1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the
diff --git a/docs/modpython.txt b/docs/modpython.txt
index d24ea29018..13377ad2dd 100644
--- a/docs/modpython.txt
+++ b/docs/modpython.txt
@@ -25,12 +25,11 @@ Then edit your ``httpd.conf`` file and add the following::
     <Location "/mysite/">
         SetHandler python-program
         PythonHandler django.core.handlers.modpython
-        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
+        SetEnv DJANGO_SETTINGS_MODULE myproject.settings
         PythonDebug On
     </Location>
 
-...and replace ``myproject.settings.main`` with the Python path to your
-settings file.
+...and replace ``myproject.settings`` with the Python path to your settings file.
 
 This tells Apache: "Use mod_python for any URL at or under '/mysite/', using the
 Django mod_python handler." It passes the value of ``DJANGO_SETTINGS_MODULE``
@@ -55,17 +54,6 @@ full URL.
 When deploying Django sites on mod_python, you'll need to restart Apache each
 time you make changes to your Python code.
 
-Here's a template for an admin configuration::
-
-    <Location "/admin/">
-        SetHandler python-program
-        PythonHandler django.core.handlers.modpython
-        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
-        PythonDebug On
-    </Location>
-
-The only thing different here is the ``DJANGO_SETTINGS_MODULE``.
-
 Multiple Django installations on the same Apache
 ================================================
 
@@ -77,13 +65,13 @@ instance. Just use ``VirtualHost`` for that, like so::
     <VirtualHost *>
         ServerName www.example.com
         # ...
-        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
+        SetEnv DJANGO_SETTINGS_MODULE myproject.settings
     </VirtualHost>
 
     <VirtualHost *>
-        ServerName admin.example.com
+        ServerName www2.example.com
         # ...
-        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
+        SetEnv DJANGO_SETTINGS_MODULE myproject.other_settings
     </VirtualHost>
 
 If you need to put two Django installations within the same ``VirtualHost``,
@@ -95,13 +83,13 @@ mess things up. Use the ``PythonInterpreter`` directive to give different
         ServerName www.example.com
         # ...
         <Location "/something">
-            SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
-            PythonInterpreter myproject_main
+            SetEnv DJANGO_SETTINGS_MODULE myproject.settings
+            PythonInterpreter myproject
         </Location>
 
-        <Location "/admin">
-            SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
-            PythonInterpreter myproject_admin
+        <Location "/otherthing">
+            SetEnv DJANGO_SETTINGS_MODULE myproject.other_settings
+            PythonInterpreter myproject_other
         </Location>
     </VirtualHost>
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 4fd4959bf1..1d65d44c88 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -34,7 +34,7 @@ When you use Django, you have to tell it which settings you're using. Do this
 by using an environment variable, ``DJANGO_SETTINGS_MODULE``.
 
 The value of ``DJANGO_SETTINGS_MODULE`` should be in Python path syntax, e.g.
-``"myproject.settings.main"``. Note that the settings module should be on the
+``"myproject.settings"``. Note that the settings module should be on the
 Python `import search path`_.
 
 .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
@@ -47,17 +47,17 @@ once, or explicitly pass in the settings module each time you run the utility.
 
 Example (Unix Bash shell)::
 
-    export DJANGO_SETTINGS_MODULE=myproject.settings.main
+    export DJANGO_SETTINGS_MODULE=myproject.settings
     django-admin.py runserver
 
 Example (Windows shell)::
 
-    set DJANGO_SETTINGS_MODULE=myproject.settings.main
+    set DJANGO_SETTINGS_MODULE=myproject.settings
     django-admin.py runserver
 
 Use the ``--settings`` command-line argument to specify the settings manually::
 
-    django-admin.py runserver --settings=myproject.settings.main
+    django-admin.py runserver --settings=myproject.settings
 
 .. _django-admin.py: http://www.djangoproject.com/documentation/django_admin/
 
@@ -70,7 +70,7 @@ settings file to use. Do that with ``SetEnv``::
     <Location "/mysite/">
         SetHandler python-program
         PythonHandler django.core.handlers.modpython
-        SetEnv DJANGO_SETTINGS_MODULE myproject.settings.main
+        SetEnv DJANGO_SETTINGS_MODULE myproject.settings
     </Location>
 
 Read the `Django mod_python documentation`_ for more information.
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index d69afa7392..761b73466d 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -40,16 +40,10 @@ settings. Let's look at what ``startproject`` created::
         __init__.py
         apps/
             __init__.py
-        settings/
-            __init__.py
-            admin.py
-            main.py
-            urls/
-                __init__.py
-                admin.py
-                main.py
+        settings.py
+        urls.py
 
-First, edit ``myproject/settings/main.py``. It's a normal Python module with
+First, edit ``myproject/settings.py``. It's a normal Python module with
 module-level variables representing Django settings. Edit the file and change
 these settings to match your database's connection parameters:
 
@@ -69,11 +63,6 @@ these settings to match your database's connection parameters:
     point. Do that with "``CREATE DATABASE database_name;``" within your
     database's interactive prompt.
 
-    Also, note that MySQL and sqlite support is a recent development, and Django
-    hasn't been comprehensively tested with either database. If you find any
-    bugs in those bindings, please file them in `Django's ticket system`_ so we
-    can fix them immediately.
-
 Now, take a second to make sure ``myproject`` is on your Python path. You
 can do this by copying ``myproject`` to Python's ``site-packages`` directory,
 or you can do it by altering the ``PYTHONPATH`` environment variable. See the
@@ -84,7 +73,7 @@ or you can do it by altering the ``PYTHONPATH`` environment variable. See the
 
 Run the following command::
 
-    django-admin.py init --settings=myproject.settings.main
+    django-admin.py init --settings=myproject.settings
 
 The ``django-admin.py`` utility generally needs to know which settings module
 you're using. Here, we're doing that by specifying ``settings=`` on the command
@@ -92,11 +81,11 @@ line, but that can get tedious. If you don't want to type ``settings=`` each
 time, you can set the ``DJANGO_SETTINGS_MODULE`` environment variable. Here's
 how you do that in the Bash shell on Unix::
 
-    export DJANGO_SETTINGS_MODULE=myproject.settings.main
+    export DJANGO_SETTINGS_MODULE=myproject.settings
 
 On Windows, you'd use ``set`` instead::
 
-    set DJANGO_SETTINGS_MODULE=myproject.settings.main
+    set DJANGO_SETTINGS_MODULE=myproject.settings
 
 If you don't see any errors after running ``django-admin.py init``, you know it
 worked. That command initialized your database with Django's core database
@@ -221,7 +210,7 @@ But first we need to tell our project that the ``polls`` app is installed.
    projects, and you can distribute apps, because they don't have to be tied to
    a given Django installation.
 
-Edit the myproject/settings/main.py file again, and change the ``INSTALLED_APPS``
+Edit the myproject/settings.py file again, and change the ``INSTALLED_APPS``
 setting to include the string "myproject.apps.polls". So it'll look like this::
 
     INSTALLED_APPS = (
diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt
index b0b345ae36..e79c067ad5 100644
--- a/docs/tutorial02.txt
+++ b/docs/tutorial02.txt
@@ -24,15 +24,26 @@ application and will focus on Django's automatically-generated admin site.
     The admin isn't necessarily intended to be used by site visitors; it's for site
     managers.
 
+Activate the admin site
+=======================
+
+The Django admin site is not activated by default -- it's an opt-in thing. To
+activate the admin site for your installation, do these three things:
+
+    * Add ``"django.contrib.admin"`` to your ``INSTALLED_APPS`` setting.
+    * Run the command ``django-admin.py install admin``. This will create an
+      extra database table that the admin needs.
+    * Edit your ``myproject.urls`` file and uncomment the line below
+      "Uncomment this for admin:". This file is a URLconf; we'll dig into
+      URLconfs in the next tutorial. For now, all you need to know is that it
+      maps URL roots to applications.
+
 Create a user account
 =====================
 
 Run the following command to create a superuser account for your admin site::
 
-    django-admin.py createsuperuser --settings="myproject.settings.main"
-
-(Note: You can use either "myproject.settings.main" or "myproject.settings.admin"
-here. They both reference the same database.)
+    django-admin.py createsuperuser --settings=myproject.settings
 
 The script will prompt you for a username, e-mail address and password (twice).
 
@@ -45,36 +56,26 @@ server and explore the admin site.
 
 Just run the following command to start the server::
 
-    django-admin.py runserver --settings="myproject.settings.admin"
+    django-admin.py runserver --settings=myproject.settings
 
 It'll start a Web server running locally -- on port 8000, by default. If you
 want to change the server's port, pass it as a command-line argument::
 
-    django-admin.py runserver 8080 --settings="myproject.settings.admin"
+    django-admin.py runserver 8080 --settings=myproject.settings
 
 DON'T use this server in anything resembling a production environment. It's
 intended only for use while developing.
 
-Now, open a Web browser and go to "/admin/" on your domain. You should see the
-admin's login screen:
+Now, open a Web browser and go to "/admin/" on your local domain -- e.g.,
+http://127.0.0.1:8000/admin/. You should see the admin's login screen:
 
 .. image:: http://media.djangoproject.com/img/doc/tutorial/admin01.png
    :alt: Django admin login screen
 
-.. admonition:: Note
-
-    If you get an error telling you that the URL 'admin/' didn't match any of
-    your URLconf entries, you most likely used ``myproject.settings.main``
-    instead of ``myproject.settings.admin``.
-
 Enter the admin site
 ====================
 
-Now, try logging in.
-
-If it didn't work, read the `"I can't log in" questions`_ in the FAQ.
-
-If it worked, you should see the Django admin index page:
+Now, try logging in. You should see the Django admin index page:
 
 .. image:: http://media.djangoproject.com/img/doc/tutorial/admin02t.png
    :alt: Django admin index page
@@ -381,39 +382,47 @@ think they should.
 Customize the admin look and feel
 =================================
 
-Clearly having "Django administration" and "example.com" at the top of each
+Clearly, having "Django administration" and "example.com" at the top of each
 admin page is ridiculous. It's just placeholder text.
 
-That's easy to change, though, using Django's template system.
+That's easy to change, though, using Django's template system. The Django admin
+is powered by Django itself, and its interfaces use Django's own template
+system. (How meta!)
 
-Open your admin settings file and look at the ``TEMPLATE_DIRS`` setting.
-``TEMPLATE_DIRS`` is a tuple of filesystem directories to check when loading
-Django templates. It's a search path.
+Open your settings file (``myproject/settings.py``, remember) and look at the
+``TEMPLATE_DIRS`` setting. ``TEMPLATE_DIRS`` is a tuple of filesystem
+directories to check when loading Django templates. It's a search path.
 
-The ``django-admin.py startproject`` command automatically prepopulated
-this setting with the location of Django's default admin templates, according
-to where you have Django installed. But let's add an extra line to
-``TEMPLATE_DIRS`` so that it checks a custom directory first, before checking
-the default admin template directory::
+By default, ``TEMPLATE_DIRS`` is empty. So, let's add a line to it, to tell
+Django where our templates live::
 
     TEMPLATE_DIRS = (
-        "/home/mytemplates/admin",
-        "/usr/lib/python2.3/site-packages/django/conf/admin_templates",
+        "/home/mytemplates", # Change this to your own directory.
     )
 
-Again, note that you should edit the admin settings file, not the main settings
-file. That's because we're dealing with admin-site templates.
+Now copy the template ``admin/base_site.html`` from within the default Django
+admin template directory (``django/contrib/admin/templates``) into an ``admin``
+subdirectory of whichever directory you're using in ``TEMPLATE_DIRS``. For
+example, if your ``TEMPLATE_DIRS`` includes ``"/home/mytemplates"``, as above,
+then copy ``django/contrib/admin/templates/admin/base_site.html`` to
+``/home/mytemplates/admin/base_site.html``.
 
-Now copy the template ``base_site.html`` from within the default Django admin
-template directory, into ``/home/mytemplates/admin`` (or wherever you're
-putting your custom admin templates). Edit the file and replace the generic
-Django stuff with your own site's name as you see fit.
+Then, just edit the file and replace the generic Django text with your own
+site's name and URL as you see fit.
 
 Note that any of Django's default admin templates can be overridden. To
 override a template, just do the same thing you did with ``base_site.html`` --
 copy it from the default directory into your custom directory, and make
 changes.
 
+Astute readers will ask: But if ``TEMPLATE_DIRS`` was empty by default, how was
+Django finding the default admin templates? The answer is that, by default,
+Django automatically looks for a ``templates/`` subdirectory within each app
+package, for use as a fallback. See the `loader types documentation`_ for full
+information.
+
+.. _loader types documentation: http://www.djangoproject.com/documentation/templates_python/#loader-types
+
 Customize the admin index page
 ==============================
 
@@ -425,11 +434,11 @@ setting. But the order in which it displays things is random, and you may want
 to make significant changes to the layout. After all, the index is probably the
 most important page of the admin, and it should be easy to use.
 
-The template to customize is ``index.html``. (Do the same as with
-``base_site.html`` in the previous section -- copy it from the default directory
-to your custom template directory.) Edit the file, and you'll see it uses a
-template tag called ``{% get_admin_app_list as app_list %}``. That's the magic
-that retrieves every installed Django app. Instead of using that, you can
+The template to customize is ``admin/index.html``. (Do the same as with
+``admin/base_site.html`` in the previous section -- copy it from the default
+directory to your custom template directory.) Edit the file, and you'll see it
+uses a template tag called ``{% get_admin_app_list as app_list %}``. That's the
+magic that retrieves every installed Django app. Instead of using that, you can
 hard-code links to object-specific admin pages in whatever way you think is
 best.
 
diff --git a/docs/tutorial03.txt b/docs/tutorial03.txt
index f602bf2ebd..3b5e0e8d94 100644
--- a/docs/tutorial03.txt
+++ b/docs/tutorial03.txt
@@ -62,12 +62,12 @@ arguments from the dictionary (an optional third item in the tuple).
 For more on ``HTTPRequest`` objects, see the `request and response documentation`_.
 
 When you ran ``django-admin.py startproject myproject`` at the beginning of
-Tutorial 1, it created a default URLconf in ``myproject/settings/urls/main.py``.
-It also automatically set your ``ROOT_URLCONF`` setting to point at that file::
+Tutorial 1, it created a default URLconf in ``myproject/urls.py``. It also
+automatically set your ``ROOT_URLCONF`` setting to point at that file::
 
-    ROOT_URLCONF = 'myproject.settings.urls.main'
+    ROOT_URLCONF = 'myproject.urls'
 
-Time for an example. Edit ``myproject/settings/urls/main.py`` so it looks like
+Time for an example. Edit ``myproject/urls.py`` so it looks like
 this::
 
     from django.conf.urls.defaults import *
@@ -84,8 +84,8 @@ say, "/polls/23/", Django will load this Python module, because it's pointed to
 by the ``ROOT_URLCONF`` setting. It finds the variable named ``urlpatterns``
 and traverses the regular expressions in order. When it finds a regular
 expression that matches -- ``r'^polls/(?P<poll_id>\d+)/$'`` -- it loads the
-associated Python package/module: ``myproject.polls.views.polls.detail``. That
-corresponds to the function ``detail()`` in ``myproject/polls/views/polls.py``.
+associated Python package/module: ``myproject.apps.polls.views.polls.detail``. That
+corresponds to the function ``detail()`` in ``myproject/apps/polls/views/polls.py``.
 Finally, it calls that ``detail()`` function like so::
 
     detail(request=<HttpRequest object>, poll_id=23)
@@ -122,12 +122,7 @@ make sure Django is following the URLconf properly.
 
 Fire up the Django development Web server::
 
-    django-admin.py runserver --settings="myproject.settings.main"
-
-(If you're coming here straight from Tutorial 2, note that we're now running
-the server with ``--settings=myproject.settings.main`` instead of
-``--settings=myproject.settings.admin``. You'll need to restart the server to
-change the ``settings`` parameter.)
+    django-admin.py runserver --settings=myproject.settings
 
 Now go to "http://localhost:8000/polls/" on your domain in your Web browser.
 You should get a Python traceback with the following error message::
@@ -413,19 +408,15 @@ Our poll app is pretty decoupled at this point, thanks to the strict directory
 structure that ``django-admin.py startapp`` created, but one part of it is
 coupled to the Django settings: The URLconf.
 
-We've been editing the URLs in ``myproject/settings/urls/main.py``, but the
-URL design of an app is specific to the app, not to the Django installation --
-so let's move the URLs within the app directory.
-
-Create a directory ``myproject/apps/polls/urls/``, and put a blank file called
-``__init__.py`` into it. (The ``__init__.py`` file is necessary for Python to
-treat the directory as a package.) Then copy the file
-``myproject/settings/urls/main.py`` to ``myproject/apps/polls/urls/polls.py``.
+We've been editing the URLs in ``myproject/urls.py``, but the URL design of an
+app is specific to the app, not to the Django installation -- so let's move the
+URLs within the app directory.
 
-Then, change ``myproject/settings/urls/main.py`` to remove the poll-specific
-URLs and insert an ``include()``::
+Copy the file ``myproject/urls.py`` to ``myproject/apps/polls/urls.py``. Then,
+change ``myproject/urls.py`` to remove the poll-specific URLs and insert an
+``include()``::
 
-    (r'^polls/', include('myproject.apps.polls.urls.polls')),
+    (r'^polls/', include('myproject.apps.polls.urls')),
 
 ``include()``, simply, references another URLconf. Note that the regular
 expression doesn't have a ``$`` (end-of-string match character) but has the
@@ -437,12 +428,12 @@ Here's what happens if a user goes to "/polls/34/" in this system:
 
 * Django will find the match at ``'^polls/'``
 * It will strip off the matching text (``"polls/"``) and send the remaining
-  text -- ``"34/"`` -- to the 'myproject.apps.polls.urls.polls' urlconf for
+  text -- ``"34/"`` -- to the 'myproject.apps.polls.urls' urlconf for
   further processing.
 
 Now that we've decoupled that, we need to decouple the
-'myproject.apps.polls.urls.polls' urlconf by removing the leading "polls/"
-from each line::
+'myproject.apps.polls.urls' urlconf by removing the leading "polls/" from each
+line::
 
     urlpatterns = patterns('myproject.apps.polls.views.polls',
         (r'^$', 'index'),