[full-history] Trunk merge from [3577]

git-svn-id: http://code.djangoproject.com/svn/django/branches/full-history@3580 bcc190cf-cafb-0310-a4f2-bffc1f526a37

9 files changed, 244 insertions, 19 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index a7cf30813d..bd178dbd7d 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -718,12 +718,12 @@ The ``DoesNotExist`` exception inherits from
 A convenience method for creating an object and saving it all in one step.  Thus::
 
     p = Person.objects.create(first_name="Bruce", last_name="Springsteen")
-    
+
 and::
 
     p = Person(first_name="Bruce", last_name="Springsteen")
     p.save()
-    
+
 are equivalent.
 
 ``get_or_create(**kwargs)``
@@ -1471,11 +1471,12 @@ the ``ForeignKey`` ``Manager`` has these additional methods:
           b.entry_set.remove(e) # Disassociates Entry e from Blog b.
 
       In order to prevent database inconsistency, this method only exists on
-      ``ForeignKey``s where ``null=True``. If the related field can't be set to
-      ``None`` (``NULL``), then an object can't be removed from a relation
-      without being added to another. In the above example, removing ``e`` from
-      ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because
-      the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid.
+      ``ForeignKey`` objects where ``null=True``. If the related field can't be
+      set to ``None`` (``NULL``), then an object can't be removed from a
+      relation without being added to another. In the above example, removing
+      ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``,
+      and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this
+      is invalid.
 
     * ``clear()``: Removes all objects from the related object set.
 
@@ -1559,13 +1560,13 @@ Queries over related objects
 ----------------------------
 
 Queries involving related objects follow the same rules as queries involving
-normal value fields. When specifying the the value for a query to match, you 
-may use either an object instance itself, or the primary key value for the 
+normal value fields. When specifying the the value for a query to match, you
+may use either an object instance itself, or the primary key value for the
 object.
 
 For example, if you have a Blog object ``b`` with ``id=5``, the following
 three queries would be identical::
-     
+
     Entry.objects.filter(blog=b) # Query using object instance
     Entry.objects.filter(blog=b.id) # Query using id from instance
     Entry.objects.filter(blog=5) # Query using id directly
diff --git a/docs/documentation.txt b/docs/documentation.txt
new file mode 100644
index 0000000000..bacfb176b1
--- /dev/null
+++ b/docs/documentation.txt
@@ -0,0 +1,148 @@
+====================================
+How to read the Django documentation
+====================================
+
+We've put a lot of effort into making Django's documentation useful, easy to
+read and as complete as possible. Here are a few tips on how to make the best
+of it, along with some style guidelines.
+
+(Yes, this is documentation about documentation. Rest assured we have no plans
+to write a document about how to read the document about documentation.)
+
+How documentation is updated
+============================
+
+Just as the Django code base is developed and improved on a daily basis, our
+documentation is consistently improving. We improve documentation for several
+reasons:
+
+    * To make content fixes, such as grammar/typo corrections.
+    * To add information and/or examples to existing sections that need to be
+      expanded.
+    * To document Django features that aren't yet documented. (The list of
+      such features is shrinking but exists nonetheless.)
+    * To add documentation for new features as new features get added, or as
+      Django APIs or behaviors change.
+
+Django's documentation is kept in the same source control system as its code.
+It lives in the `django/trunk/docs`_ directory of our Subversion repository.
+Each document is a separate text file that covers a narrowly focused topic,
+such as the "generic views" framework or how to construct a database model.
+
+.. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs
+
+Where to get it
+===============
+
+You can read Django documentation in several ways. They are, in order of
+preference:
+
+On the Web
+----------
+
+The most recent version of the Django documentation lives at
+http://www.djangoproject.com/documentation/ . These HTML pages are generated
+automatically from the text files in source control every 15 minutes. That
+means they reflect the "latest and greatest" in Django -- they include the very
+latest corrections and additions, and they discuss the latest Django features,
+which may only be available to users of the Django development version. (See
+"Differences between versions" below.)
+
+A key advantage of the Web-based documentation is the comment section at the
+bottom of each document. This is an area for anybody to submit changes,
+corrections and suggestions about the given document. The Django developers
+frequently monitor the comments there and use them to improve the documentation
+for everybody.
+
+We encourage you to help improve the docs: it's easy! Note, however, that
+comments should explicitly relate to the documentation, rather than asking
+broad tech-support questions. If you need help with your particular Django
+setup, try the `django-users mailing list`_ instead of posting a comment to the
+documentation.
+
+.. _django-users mailing list: http://groups.google.com/group/django-users
+
+In plain text
+-------------
+
+For offline reading, or just for convenience, you can read the Django
+documentation in plain text.
+
+If you're using an official release of Django, note that the zipped package
+(tarball) of the code includes a ``docs/`` directory, which contains all the
+documentation for that release.
+
+If you're using the development version of Django (aka the Subversion "trunk"),
+note that the ``docs/`` directory contains all of the documentation. You can
+``svn update`` it, just as you ``svn update`` the Python code, in order to get
+the latest changes.
+
+You can check out the latest Django documentation from Subversion using this
+shell command::
+
+    svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
+
+One low-tech way of taking advantage of the text documentation is by using the
+Unix ``grep`` utility to search for a phrase in all of the documentation. For
+example, this will show you each mention of the phrase "edit_inline" in any
+Django document::
+
+    grep edit_inline /path/to/django/docs/*.txt
+
+Formatting
+~~~~~~~~~~
+
+The text documentation is written in ReST (ReStructured Text) format. That
+means it's easy to read but is also formatted in a way that makes it easy to
+convert into other formats, such as HTML. If you're interested, the script that
+converts the ReST text docs into djangoproject.com's HTML lives at
+`djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ in
+the Django Subversion repository.
+
+.. _djangoproject.com/django_website/apps/docs/parts/build_documentation.py: http://code.djangoproject.com/browser/djangoproject.com/django_website/apps/docs/parts/build_documentation.py
+
+Differences between versions
+============================
+
+As previously mentioned, the text documentation in our Subversion repository
+contains the "latest and greatest" changes and additions. These changes often
+include documentation of new features added in the Django development version
+-- the Subversion ("trunk") version of Django. For that reason, it's worth
+pointing out our policy on keeping straight the documentation for various
+versions of the framework.
+
+We follow this policy:
+
+    * The primary documentation on djangoproject.com is an HTML version of the
+      latest docs in Subversion. These docs always correspond to the latest
+      official Django release, plus whatever features we've added/changed in
+      the framework *since* the latest release.
+
+    * As we add features to Django's development version, we try to update the
+      documentation in the same Subversion commit transaction.
+
+    * To distinguish feature changes/additions in the docs, we use the phrase
+      **New in Django development version**. In practice, this means that the
+      current documentation on djangoproject.com can be used by users of either
+      the latest release *or* the development version.
+
+    * Documentation for a particular Django release is frozen once the version
+      has been released officially. It remains a snapshot of the docs as of the
+      moment of the release. We will make exceptions to this rule in
+      the case of retroactive security updates or other such retroactive
+      changes. Once documentation is frozen, we add a note to the top of each
+      frozen document that says "These docs are frozen for Django version XXX"
+      and links to the current version of that document.
+
+    * Once a document is frozen for a Django release, we remove comments from
+      that page, in favor of having comments on the latest version of that
+      document. This is for the sake of maintainability and usability, so that
+      users have one, and only one, place to leave comments on a particular
+      document. We realize that some people may be stuck on a previous version
+      of Django, but we believe the usability problems with multiple versions
+      of a document the outweigh the benefits.
+
+    * The `main documentation Web page`_ includes links to documentation for
+      all previous versions.
+
+.. _main documentation Web page: http://www.djangoproject.com/documentation/
diff --git a/docs/faq.txt b/docs/faq.txt
index 36fb547cf1..3cd7090583 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -620,13 +620,10 @@ like to make should be possible by editing the stylesheet. We've got a
 How do I create users without having to edit password hashes?
 -------------------------------------------------------------
 
-We don't recommend you create users via the admin interface, because at the
-moment it requires you to edit password hashes manually. (Passwords are hashed
-using one-way hash algorithms for security; there's currently no Web interface
-for changing passwords by entering the actual password rather than the hash.)
+If you'd like to use the admin site to create users, upgrade to the Django
+development version, where this problem was fixed on Aug. 4, 2006.
 
-To create a user, you'll have to use the Python API. See `creating users`_ for
-full info.
+You can also use the Python API. See `creating users`_ for full info.
 
 .. _creating users: http://www.djangoproject.com/documentation/authentication/#creating-users
 
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index aab878467f..fdab97de27 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -127,7 +127,7 @@ If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
 This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``::
 
     urlpatterns = patterns('django.views.generic.simple',
-        ('^foo/(?p<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
+        ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
     )
 
 This example returns a 410 HTTP error for requests to ``/bar/``::
diff --git a/docs/model-api.txt b/docs/model-api.txt
index c369508c65..502ceaf7ff 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -223,6 +223,13 @@ steps:
        the absolute URL to your image in a template with ``{{
        object.get_mug_shot_url }}``.
 
+For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and
+``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of
+``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year,
+``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you
+upload a file on Jan. 15, 2007, it will be saved in the directory
+``/home/media/photos/2007/01/15``.
+
 .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
 
 ``FilePathField``
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 7480a6d3bb..1f3b9d5804 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -149,7 +149,7 @@ Methods
    Returns the ``path``, plus an appended query string, if applicable.
 
    Example: ``"/music/bands/the_beatles/?print=true"``
-    
+
 ``is_secure()``
    Returns ``True`` if the request is secure; that is, if it was made with
    HTTPS.
@@ -380,10 +380,14 @@ Methods
 
     .. _`cookie Morsel`: http://www.python.org/doc/current/lib/morsel-objects.html
 
-``delete_cookie(key)``
+``delete_cookie(key, path='/', domain=None)``
     Deletes the cookie with the given key. Fails silently if the key doesn't
     exist.
 
+    The ``path`` and ``domain`` arguments are new in the Django development version.
+    Due to the way cookies work, ``path`` and ``domain`` should be the same
+    values you used in ``set_cookie()`` -- otherwise the cookie may not be deleted.
+
 ``content``
     Returns the content as a Python string, encoding it from a Unicode object
     if necessary. Note this is a property, not a method, so use ``r.content``
diff --git a/docs/sessions.txt b/docs/sessions.txt
index c473d0a3db..d39f42c3bf 100644
--- a/docs/sessions.txt
+++ b/docs/sessions.txt
@@ -245,6 +245,17 @@ Default: ``'sessionid'``
 
 The name of the cookie to use for sessions. This can be whatever you want.
 
+SESSION_COOKIE_SECURE
+---------------------
+
+**New in Django development version**
+
+Default: ``False``
+
+Whether to use a secure cookie for the session cookie. If this is set to
+``True``, the cookie will be marked as "secure," which means browsers may
+ensure that the cookie is only sent under an HTTPS connection.
+
 SESSION_EXPIRE_AT_BROWSER_CLOSE
 -------------------------------
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 099196e56e..67e0498e1a 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -647,6 +647,18 @@ Default: ``'sessionid'``
 The name of the cookie to use for sessions. This can be whatever you want.
 See the `session docs`_.
 
+SESSION_COOKIE_SECURE
+---------------------
+
+**New in Django development version**
+
+Default: ``False``
+
+Whether to use a secure cookie for the session cookie. If this is set to
+``True``, the cookie will be marked as "secure," which means browsers may
+ensure that the cookie is only sent under an HTTPS connection.
+See the `session docs`_.
+
 SESSION_EXPIRE_AT_BROWSER_CLOSE
 -------------------------------
 
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 6158014fc8..00a7af027a 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -431,3 +431,48 @@ Note that extra options will *always* be passed to *every* line in the included
 URLconf, regardless of whether the line's view actually accepts those options
 as valid. For this reason, this technique is only useful if you're certain that
 every view in the the included URLconf accepts the extra options you're passing.
+
+Passing callable objects instead of strings
+===========================================
+
+**New in the Django development version.**
+
+Some developers find it more natural to pass the actual Python function object
+rather than a string containing the path to its module. This alternative is
+supported -- you can pass any callable object as the view.
+
+For example, given this URLconf in "string" notation::
+
+    urlpatterns = patterns('',
+        (r'^archive/$', 'mysite.views.archive'),
+        (r'^about/$', 'mysite.views.about'),
+        (r'^contact/$', 'mysite.views.contact'),
+    )
+
+You can accomplish the same thing by passing objects rather than strings. Just
+be sure to import the objects::
+
+    from mysite.views import archive, about, contact
+
+    urlpatterns = patterns('',
+        (r'^archive/$', archive),
+        (r'^about/$', about),
+        (r'^contact/$', contact),
+    )
+
+The following example is functionally identical. It's just a bit more compact
+because it imports the module that contains the views, rather than importing
+each view individually::
+
+    from mysite import views
+
+    urlpatterns = patterns('',
+        (r'^archive/$', views.archive),
+        (r'^about/$', views.about),
+        (r'^contact/$', views.contact),
+    )
+
+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.