boulder-oracle-sprint: Merged to [4905].

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

10 files changed, 206 insertions, 58 deletions

diff --git a/docs/faq.txt b/docs/faq.txt
index 33e8ef01b4..b5150a0967 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -328,8 +328,9 @@ Do I have to use mod_python?
 
 Although we recommend mod_python for production use, you don't have to use it,
 thanks to the fact that Django uses an arrangement called WSGI_. Django can
-talk to any WSGI-enabled server. The most common non-mod_python deployment
-setup is FastCGI. See `How to use Django with FastCGI`_ for full information.
+talk to any WSGI-enabled server. Other non-mod_python deployment setups are
+FastCGI, SCGI or AJP. See `How to use Django with FastCGI, SCGI or AJP`_ for
+full information.
 
 Also, see the `server arrangements wiki page`_ for other deployment strategies.
 
@@ -337,7 +338,7 @@ If you just want to play around and develop things on your local computer, use
 the development Web server that comes with Django. Things should Just Work.
 
 .. _WSGI: http://www.python.org/peps/pep-0333.html
-.. _How to use Django with FastCGI: ../fastcgi/
+.. _How to use Django with FastCGI, SCGI or AJP: ../fastcgi/
 .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
 
 How do I install mod_python on Windows?
diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt
index 5ecaac8666..119688096f 100644
--- a/docs/fastcgi.txt
+++ b/docs/fastcgi.txt
@@ -1,11 +1,17 @@
-==============================
-How to use Django with FastCGI
-==============================
+===========================================
+How to use Django with FastCGI, SCGI or AJP
+===========================================
 
 Although the `current preferred setup`_ for running Django is Apache_ with
-`mod_python`_, many people use shared hosting, on which FastCGI is the only
-viable option. In some setups, FastCGI also allows better security -- and,
-possibly, better performance -- than mod_python.
+`mod_python`_, many people use shared hosting, on which protocols such as
+FastCGI, SCGI or AJP are the only viable options. In some setups, these protocols
+also allow better security -- and, possibly, better performance -- than mod_python.
+
+.. admonition:: Note
+
+    This document primarily focuses on FastCGI. Other protocols, such as SCGI
+    and AJP, are also supported, through the ``flup`` Python package. See the
+    "Protocols" section below for specifics about SCGI and AJP.
 
 Essentially, FastCGI is an efficient way of letting an external application
 serve pages to a Web server. The Web server delegates the incoming Web requests
@@ -74,10 +80,26 @@ your ``manage.py`` is), and then run ``manage.py`` with the ``runfcgi`` option::
 If you specify ``help`` as the only option after ``runfcgi``, it'll display a
 list of all the available options.
 
-You'll need to specify either a ``socket`` or both ``host`` and ``port``. Then,
-when you set up your Web server, you'll just need to point it at the host/port
+You'll need to specify either a ``socket``, ``protocol`` or both ``host`` and ``port``.
+Then, when you set up your Web server, you'll just need to point it at the host/port
 or socket you specified when starting the FastCGI server.
 
+Protocols
+---------
+
+Django supports all the protocols that flup_ does, namely fastcgi_, `SCGI`_ and
+`AJP1.3`_ (the Apache JServ Protocol, version 1.3). Select your preferred
+protocol by using the ``protocol=<protocol_name>`` option with
+``./manage.py runfcgi`` -- where ``<protocol_name>`` may be one of: ``fcgi``
+(the default), ``scgi`` or ``ajp``. For example::
+
+    ./manage.py runfcgi --protocol=scgi
+
+.. _flup: http://www.saddi.com/software/flup/
+.. _fastcgi: http://www.fastcgi.com/
+.. _SCGI: http://python.ca/scgi/protocol.txt
+.. _AJP1.3: http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html
+
 Examples
 --------
 
diff --git a/docs/forms.txt b/docs/forms.txt
index f76f6d27ef..ce1010235f 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -517,10 +517,10 @@ to put punctuation at the end of your validation messages.
 When are validators called?
 ---------------------------
 
-After a form has been submitted, Django first checks to see that all the
-required fields are present and non-empty. For each field that passes that
-test *and if the form submission contained data* for that field, all the
-validators for that field are called in turn. The emphasized portion in the
+After a form has been submitted, Django validates each field in turn. First, 
+if the field is required, Django checks that it is present and non-empty. Then,
+if that test passes *and the form submission contained data* for that field, all
+the validators for that field are called in turn. The emphasized portion in the
 last sentence is important: if a form field is not submitted (because it
 contains no data -- which is normal HTML behavior), the validators are not
 run against the field.
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 7659a428c5..0496a58691 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -222,7 +222,7 @@ In addition to ``extra_context``, the template's context will be:
       by ``date_field``. For example, if ``num_latest`` is ``10``, then
       ``latest`` will be a list of the latest 10 objects in ``queryset``.
 
-.. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext
+.. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext
 
 ``django.views.generic.date_based.archive_year``
 ------------------------------------------------
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 155ef63271..a03ed09eb2 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -1307,13 +1307,13 @@ A few special cases to note about ``list_display``:
     * Usually, elements of ``list_display`` that aren't actual database fields
       can't be used in sorting (because Django does all the sorting at the
       database level).
-      
+
       However, if an element of ``list_display`` represents a certain database
       field, you can indicate this fact by setting the ``admin_order_field``
       attribute of the item.
-      
+
       For example::
-      
+
         class Person(models.Model):
             first_name = models.CharField(maxlength=50)
             color_code = models.CharField(maxlength=6)
@@ -1325,7 +1325,7 @@ A few special cases to note about ``list_display``:
                 return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
             colored_first_name.allow_tags = True
             colored_first_name.admin_order_field = 'first_name'
-    
+
       The above will tell Django to order by the ``first_name`` field when
       trying to sort by ``colored_first_name`` in the admin.
 
@@ -1758,16 +1758,38 @@ slightly violates the DRY principle: the URL for this object is defined both
 in the URLConf file and in the model.
 
 You can further decouple your models from the URLconf using the ``permalink``
-decorator. This decorator is passed the view function and any parameters you
-would use for accessing this instance directly. Django then works out the
-correct full URL path using the URLconf. For example::
+decorator. This decorator is passed the view function, a list of positional
+parameters and (optionally) a dictionary of named parameters. Django then
+works out the correct full URL path using the URLconf, substituting the
+parameters you have given into the URL. For example, if your URLconf
+contained a line such as::
+
+    (r'^/people/(\d+)/$', 'people.views.details'),
+
+...your model could have a ``get_absolute_url`` method that looked like this::
 
     from django.db.models import permalink
 
     def get_absolute_url(self):
-        return ('people.views.details', str(self.id))
+        return ('people.views.details', [str(self.id)])
     get_absolute_url = permalink(get_absolute_url)
 
+Similarly, if you had a URLconf entry that looked like::
+
+    (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view)
+
+...you could reference this using ``permalink()`` as follows::
+
+    def get_absolute_url(self):
+        return ('archive_view', (), {
+            'year': self.created.year,
+            'month': self.created.month,
+            'day': self.created.day})
+    get_absolute_url = permalink(get_absolute_url)
+
+Notice that we specify an empty sequence for the second argument in this case,
+because we only want to pass keyword arguments, not named arguments.
+
 In this way, you're tying the model's absolute URL to the view that is used
 to display it, without repeating the URL information anywhere. You can still
 use the ``get_absolute_url`` method in templates, as before.
diff --git a/docs/modpython.txt b/docs/modpython.txt
index 2c999753c7..31ec1efe49 100644
--- a/docs/modpython.txt
+++ b/docs/modpython.txt
@@ -13,14 +13,15 @@ other server arrangements.
 Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
 `prefork MPM`_, as opposed to the `worker MPM`_.
 
-You may also be interested in `How to use Django with FastCGI`_.
+You may also be interested in `How to use Django with FastCGI, SCGI or AJP`_
+(which also covers SCGI and AJP).
 
 .. _Apache: http://httpd.apache.org/
 .. _mod_python: http://www.modpython.org/
 .. _mod_perl: http://perl.apache.org/
 .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html
 .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html
-.. _How to use Django with FastCGI: ../fastcgi/
+.. _How to use Django with FastCGI, SCGI or AJP: ../fastcgi/
 
 Basic configuration
 ===================
@@ -37,7 +38,8 @@ Then edit your ``httpd.conf`` file and add the following::
         PythonDebug On
     </Location>
 
-...and replace ``mysite.settings`` with the Python path to your settings file.
+...and replace ``mysite.settings`` with the Python import path to your Django
+project's 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``
@@ -53,6 +55,19 @@ on it, you'll need to tell mod_python::
 
     PythonPath "['/path/to/project'] + sys.path"
 
+.. caution::
+
+    Is you are using Windows, remember that the path will contain backslashes.
+    This string is passed through Python's string parser twice, so you need to
+    escape each backslash **twice**::
+
+        PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path"
+
+    or use raw strings::
+
+        PythonPath "[r'c:\\path\\to\\project'] + sys.path"
+
+
 You can also add directives such as ``PythonAutoReload Off`` for performance.
 See the `mod_python documentation`_ for a full list of options.
 
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 2b79903d13..40f06c859f 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -416,6 +416,10 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in
     The constructor doesn't take any arguments. Use this to designate that a
     page hasn't been modified since the user's last request.
 
+``HttpResponseBadRequest``
+    **New in Django development version.**
+    Acts just like ``HttpResponse`` but uses a 400 status code.
+
 ``HttpResponseNotFound``
     Acts just like ``HttpResponse`` but uses a 404 status code.
 
diff --git a/docs/templates.txt b/docs/templates.txt
index 36da8dff07..d93ee49ac1 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -625,31 +625,6 @@ Load a custom template tag set.
 
 See `Custom tag and filter libraries`_ for more information.
 
-lorem
-~~~~~
-
-Display random latin text useful for providing sample data in templates.
-
-Usage format: ``{% lorem [count] [method] [random] %}``
-
-    ===========  =============================================================
-    Argument     Description
-    ===========  =============================================================
-    ``count``    A number (or variable) containing the number of paragraphs or
-                 words to generate (default is 1).
-    ``method``   Either ``w`` for words, ``p`` for HTML paragraphs or ``b``
-                 for plain-text paragraph blocks (default is ``b``).
-    ``random``   The word ``random``, which if given, does not use the common
-                 paragraph ("Lorem ipsum dolor sit amet...") when generating
-                 text.
-
-Examples:
-
-    * ``{% lorem %}`` will output the common "lorem ipsum" paragraph.
-    * ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph
-      and two random paragraphs each wrapped in HTML ``<p>`` tags.
-    * ``{% lorem 2 w random %}`` will output two random latin words.
-
 now
 ~~~
 
@@ -782,7 +757,7 @@ i.e.::
 spaceless
 ~~~~~~~~~
 
-Normalizes whitespace between HTML tags to a single space. This includes tab
+Removes whitespace between HTML tags. This includes tab
 characters and newlines.
 
 Example usage::
@@ -795,9 +770,9 @@ Example usage::
 
 This example would return this HTML::
 
-    <p> <a href="foo/">Foo</a> </p>
+    <p><a href="foo/">Foo</a></p>
 
-Only space between *tags* is normalized -- not space between tags and text. In
+Only space between *tags* is removed -- not space between tags and text. In
 this example, the space around ``Hello`` won't be stripped::
 
     {% spaceless %}
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 85c87de680..e6e1cb6cbf 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -185,10 +185,25 @@ The first argument to ``patterns()`` is a string ``prefix``. See
 
 The remaining arguments should be tuples in this format::
 
-    (regular expression, Python callback function [, optional dictionary])
+    (regular expression, Python callback function [, optional dictionary [, optional name]])
 
-...where ``optional dictionary`` is optional. (See
-_`Passing extra options to view functions` below.)
+...where ``optional dictionary`` and ``optional name`` are optional. (See
+`Passing extra options to view functions`_ below.)
+
+url
+---
+**New in development version**
+
+The ``url()`` function can be used instead of a tuple as an argument to
+``patterns()``. This is convenient if you wish to specify a name without the
+optional extra arguments dictionary. For example::
+
+    urlpatterns = patterns('',
+        url(r'/index/$', index_view, name="main-view"),
+        ...
+    )
+
+See `Naming URL patterns`_ for why the ``name`` parameter is useful.
 
 handler404
 ----------
@@ -479,3 +494,44 @@ The style you use is up to you.
 
 Note that if you use this technique -- passing objects rather than strings --
 the view prefix (as explained in "The view prefix" above) will have no effect.
+
+Naming URL patterns
+===================
+
+**New in development version**
+
+It is fairly common to use the same view function in multiple URL patterns in
+your URLConf. This leads to problems when you come to do reverse URL matching,
+because the ``permalink()`` decorator and ``{% url %}`` template tag use the
+name of the view function to find a match.
+
+To solve this problem, you can give a name to each of your URL patterns in
+order to distinguish them from other patterns using the same views and
+parameters. You can then use this name wherever you would otherwise use the
+name of the view function. For example, if you URLConf contains::
+
+    urlpatterns = patterns('',
+        url(r'/archive/(\d{4})/$', archive, name="full-archive"),
+        url(r'/archive-summary/(\d{4})/$', archive, {'summary': True}, "arch-summary"),
+    )
+
+...you could refer to either the summary archive view in a template as::
+
+    {% url arch-summary 1945 %}
+
+Even though both URL patterns refer to the ``archive`` view here, using the
+``name`` parameter to ``url()`` allows you to tell them apart in templates.
+
+The string used for the URL name can contain any characters you like. You are
+not restricted to valid Python names.
+
+.. note::
+
+    Make sure that when you name your URLs, you use names that are unlikely to
+    clash with any other application's choice of names. If you call your URL
+    pattern *comment* and another application does the same thing, there is no
+    guarantee which URL will be inserted into your template when you use this
+    name. Putting a prefix on your URL names, perhaps derived from
+    the application name, will decrease the chances of collision. Something
+    like *myapp-comment* is recommended over simply *comment*.
+
diff --git a/docs/webdesign.txt b/docs/webdesign.txt
new file mode 100644
index 0000000000..8e6eae89dd
--- /dev/null
+++ b/docs/webdesign.txt
@@ -0,0 +1,53 @@
+========================
+django.contrib.webdesign
+========================
+
+The ``django.contrib.webdesign`` package, part of the `"django.contrib" add-ons`_,
+provides various Django helpers that are particularly useful to Web *designers*
+(as opposed to developers).
+
+At present, the package contains only a single template tag. If you have ideas
+for Web-designer-friendly functionality in Django, please `suggest them`_.
+
+.. _"django.contrib" add-ons: ../add_ons/
+.. _suggest them: ../contributing/
+
+Template tags
+=============
+
+To use these template tags, add ``'django.contrib.webdesign'`` to your
+``INSTALLED_APPS`` setting. Once you've done that, use
+``{% load webdesign %}`` in a template to give your template access to the tags.
+
+
+lorem
+=====
+
+Displays random "lorem ipsum" Latin text. This is useful for providing sample
+data in templates.
+
+Usage::
+
+    {% lorem [count] [method] [random] %}
+
+The ``{% lorem %}`` tag can be used with zero, one, two or three arguments.
+The arguments are:
+
+    ===========  =============================================================
+    Argument     Description
+    ===========  =============================================================
+    ``count``    A number (or variable) containing the number of paragraphs or
+                 words to generate (default is 1).
+    ``method``   Either ``w`` for words, ``p`` for HTML paragraphs or ``b``
+                 for plain-text paragraph blocks (default is ``b``).
+    ``random``   The word ``random``, which if given, does not use the common
+                 paragraph ("Lorem ipsum dolor sit amet...") when generating
+                 text.
+    ===========  =============================================================
+
+Examples:
+
+    * ``{% lorem %}`` will output the common "lorem ipsum" paragraph.
+    * ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph
+      and two random paragraphs each wrapped in HTML ``<p>`` tags.
+    * ``{% lorem 2 w random %}`` will output two random Latin words.