boulder-oracle-sprint: Merged to [4989]

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

9 files changed, 122 insertions, 91 deletions

diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index b6028dc2a0..52ee823cc3 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -29,6 +29,9 @@ Generally, when working on a single Django project, it's easier to use
 ``--settings`` command line option, if you need to switch between multiple
 Django settings files.
 
+The command-line examples throughout this document use ``django-admin.py`` to
+be consistent, but any example can use ``manage.py`` just as well.
+
 Usage
 =====
 
@@ -100,23 +103,24 @@ if you're ever curious to see the full list of defaults.
 dumpdata [appname appname ...]
 ------------------------------
 
-Output to standard output all data in the database associated with the named 
+Output to standard output all data in the database associated with the named
 application(s).
 
 By default, the database will be dumped in JSON format. If you want the output
-to be in another format, use the ``--format`` option (e.g., ``format=xml``). 
-You may specify any Django serialization backend (including any user specified 
-serialization backends named in the ``SERIALIZATION_MODULES`` setting).
+to be in another format, use the ``--format`` option (e.g., ``format=xml``).
+You may specify any Django serialization backend (including any user specified
+serialization backends named in the ``SERIALIZATION_MODULES`` setting). The
+``--indent`` option can be used to pretty-print the output.
 
 If no application name is provided, all installed applications will be dumped.
 
-The output of ``dumpdata`` can be used as input for ``loaddata``. 
+The output of ``dumpdata`` can be used as input for ``loaddata``.
 
 flush
 -----
 
-Return the database to the state it was in immediately after syncdb was 
-executed. This means that all data will be removed from the database, any 
+Return the database to the state it was in immediately after syncdb was
+executed. This means that all data will be removed from the database, any
 post-synchronization handlers will be re-executed, and the ``initial_data``
 fixture will be re-installed.
 
@@ -178,37 +182,37 @@ Django will search in three locations for fixtures:
    3. In the literal path named by the fixture
 
 Django will load any and all fixtures it finds in these locations that match
-the provided fixture names. 
+the provided fixture names.
 
-If the named fixture has a file extension, only fixtures of that type 
+If the named fixture has a file extension, only fixtures of that type
 will be loaded. For example::
 
     django-admin.py loaddata mydata.json
-    
-would only load JSON fixtures called ``mydata``. The fixture extension 
-must correspond to the registered name of a serializer (e.g., ``json`` or 
+
+would only load JSON fixtures called ``mydata``. The fixture extension
+must correspond to the registered name of a serializer (e.g., ``json`` or
 ``xml``).
 
-If you omit the extension, Django will search all available fixture types 
+If you omit the extension, Django will search all available fixture types
 for a matching fixture. For example::
 
     django-admin.py loaddata mydata
-    
+
 would look for any fixture of any fixture type called ``mydata``. If a fixture
 directory contained ``mydata.json``, that fixture would be loaded
-as a JSON fixture. However, if two fixtures with the same name but different 
-fixture type are discovered (for example, if ``mydata.json`` and 
-``mydata.xml`` were found in the same fixture directory), fixture 
-installation will be aborted, and any data installed in the call to 
+as a JSON fixture. However, if two fixtures with the same name but different
+fixture type are discovered (for example, if ``mydata.json`` and
+``mydata.xml`` were found in the same fixture directory), fixture
+installation will be aborted, and any data installed in the call to
 ``loaddata`` will be removed from the database.
 
-The fixtures that are named can include directory components. These 
+The fixtures that are named can include directory components. These
 directories will be included in the search path. For example::
 
     django-admin.py loaddata foo/bar/mydata.json
- 
-would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed 
-application,  ``<dirname>/foo/bar/mydata.json`` for each directory in 
+
+would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
+application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
 ``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
 
 Note that the order in which fixture files are processed is undefined. However,
@@ -217,16 +221,18 @@ one fixture can reference data in another fixture. If the database backend
 supports row-level constraints, these constraints will be checked at the
 end of the transaction.
 
+The ``dumpdata`` command can be used to generate input for ``loaddata``.
+
 .. admonition:: MySQL and Fixtures
 
-    Unfortunately, MySQL isn't capable of completely supporting all the 
+    Unfortunately, MySQL isn't capable of completely supporting all the
     features of Django fixtures. If you use MyISAM tables, MySQL doesn't
-    support transactions or constraints, so you won't get a rollback if 
-    multiple transaction files are found, or validation of fixture data. 
-    If you use InnoDB tables, you won't be able to have any forward 
-    references in your data files - MySQL doesn't provide a mechanism to 
-    defer checking of row constraints until a transaction is committed.    
-    
+    support transactions or constraints, so you won't get a rollback if
+    multiple transaction files are found, or validation of fixture data.
+    If you use InnoDB tables, you won't be able to have any forward
+    references in your data files - MySQL doesn't provide a mechanism to
+    defer checking of row constraints until a transaction is committed.
+
 reset [appname appname ...]
 ---------------------------
 Executes the equivalent of ``sqlreset`` for the given appnames.
@@ -366,7 +372,7 @@ Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given appnames.
 sqlsequencereset [appname appname ...]
 ----------------------------------------------
 
-Prints the SQL statements for resetting PostgreSQL sequences for the given
+Prints the SQL statements for resetting sequences for the given
 appnames.
 
 See http://simon.incutio.com/archive/2004/04/21/postgres for more information.
@@ -397,8 +403,8 @@ this command to install the default apps.
 If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
 give you the option of creating a superuser immediately.
 
-``syncdb`` will also search for and install any fixture named ``initial_data``. 
-See the documentation for ``loaddata`` for details on the specification of 
+``syncdb`` will also search for and install any fixture named ``initial_data``.
+See the documentation for ``loaddata`` for details on the specification of
 fixture data files.
 
 test
@@ -471,7 +477,7 @@ Example usage::
 
     django-admin.py dumpdata --indent=4
 
-Specifies the number of spaces that will be used for indentation when 
+Specifies the number of spaces that will be used for indentation when
 pretty-printing output. By default, output will *not* be pretty-printed.
 Pretty-printing will only be enabled if the indent option is provided.
 
@@ -512,7 +518,8 @@ and `2` is verbose output.
 ------------
 
 Example usage::
-    django-admin.py manage.py --adminmedia=/tmp/new-admin-style/
+
+    django-admin.py --adminmedia=/tmp/new-admin-style/
 
 Tells Django where to find the various CSS and JavaScript files for the admin
 interface when running the development server. Normally these files are served
diff --git a/docs/documentation.txt b/docs/documentation.txt
index bacfb176b1..e72dd47ba1 100644
--- a/docs/documentation.txt
+++ b/docs/documentation.txt
@@ -42,25 +42,25 @@ 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,
+automatically from the text files in source control. 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 by submitting changes, corrections
+and suggestions in the `ticket system`_. The Django developers actively monitor
+the ticket system and use your feedback 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.
+Note, however, that tickets 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`_ or the
+`#django IRC channel`_ instead.
 
+.. _ticket system: http://code.djangoproject.com/simpleticket?component=Documentation
 .. _django-users mailing list: http://groups.google.com/group/django-users
+.. _#django IRC channel: irc://irc.freenode.net/django
 
 In plain text
 -------------
@@ -134,14 +134,6 @@ We follow this policy:
       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.
 
diff --git a/docs/legacy_databases.txt b/docs/legacy_databases.txt
index 8230c11f61..3e2753baca 100644
--- a/docs/legacy_databases.txt
+++ b/docs/legacy_databases.txt
@@ -39,11 +39,11 @@ Auto-generate the models
 Django comes with a utility that can create models by introspecting an existing
 database. You can view the output by running this command::
 
-    django-admin.py inspectdb --settings=path.to.settings
+    python manage.py inspectdb
 
 Save this as a file by using standard Unix output redirection::
 
-    django-admin.py inspectdb --settings=path.to.settings > models.py
+    python manage.py inspectdb > models.py
 
 This feature is meant as a shortcut, not as definitive model generation. See
 the `django-admin.py documentation`_ for more information.
@@ -60,7 +60,7 @@ Install the core Django tables
 Next, run the ``manage.py syncdb`` command to install any extra needed database
 records such as admin permissions and content types::
 
-    django-admin.py init --settings=path.to.settings
+    python manage.py syncdb
 
 See whether it worked
 =====================
diff --git a/docs/model-api.txt b/docs/model-api.txt
index a03ed09eb2..400617a012 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -734,10 +734,10 @@ relationship should work. All are optional:
     ``limit_choices_to``     A dictionary of lookup arguments and values (see
                              the `Database API reference`_) that limit the
                              available admin choices for this object. Use this
-                             with ``models.LazyDate`` to limit choices of objects
-                             by date. For example::
+                             with functions from the Python ``datetime`` module 
+                             to limit choices of objects by date. For example::
 
-                                limit_choices_to = {'pub_date__lte': models.LazyDate()}
+                                limit_choices_to = {'pub_date__lte': datetime.now}
 
                              only allows the choice of related objects with a
                              ``pub_date`` before the current date/time to be
diff --git a/docs/modpython.txt b/docs/modpython.txt
index 31ec1efe49..37909a09fd 100644
--- a/docs/modpython.txt
+++ b/docs/modpython.txt
@@ -57,17 +57,16 @@ on it, you'll need to tell mod_python::
 
 .. caution::
 
-    Is you are using Windows, remember that the path will contain backslashes.
+    If you're 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::
+    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.
 
@@ -161,7 +160,7 @@ If, however, you have no option but to serve media files on the same Apache
 ``VirtualHost`` as Django, here's how you can turn off mod_python for a
 particular part of the site::
 
-    <Location "/media/">
+    <Location "/media">
         SetHandler None
     </Location>
 
@@ -178,7 +177,7 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or
         SetEnv DJANGO_SETTINGS_MODULE mysite.settings
     </Location>
 
-    <Location "media">
+    <Location "/media">
         SetHandler None
     </Location>
 
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 40f06c859f..c0272461ca 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -483,8 +483,8 @@ In order to use the ``Http404`` exception to its fullest, you should create a
 template that is displayed when a 404 error is raised. This template should be
 called ``404.html`` and located in the top level of your template tree.
 
-Customing error views
----------------------
+Customizing error views
+-----------------------
 
 The 404 (page not found) view
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index a64914de3f..2a09307e09 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -114,6 +114,9 @@ Note:
       `object-relational mapper`_, ``items()`` doesn't have to return model
       instances. Although you get a few bits of functionality "for free" by
       using Django models, ``items()`` can return any type of object you want.
+    * If you're creating an Atom feed, rather than an RSS feed, set the
+      ``subtitle`` attribute instead of the ``description`` attribute. See
+      `Publishing Atom and RSS feeds in tandem`_, later, for an example.
 
 One thing's left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
 ``<link>`` and ``<description>``. We need to tell the framework what data to
@@ -298,7 +301,7 @@ Publishing Atom and RSS feeds in tandem
 ---------------------------------------
 
 Some developers like to make available both Atom *and* RSS versions of their
-feeds. That's easy to do with Django: Just create a subclass of your ``feed``
+feeds. That's easy to do with Django: Just create a subclass of your ``Feed``
 class and set the ``feed_type`` to something different. Then update your
 URLconf to add the extra versions.
 
@@ -318,6 +321,20 @@ Here's a full example::
 
     class AtomSiteNewsFeed(RssSiteNewsFeed):
         feed_type = Atom1Feed
+        subtitle = RssSiteNewsFeed.description
+
+.. Note::
+    In this example, the RSS feed uses a ``description`` while the Atom feed
+    uses a ``subtitle``. That's because Atom feeds don't provide for a
+    feed-level "description," but they *do* provide for a "subtitle."
+
+    If you provide a ``description`` in your ``Feed`` class, Django will *not*
+    automatically put that into the ``subtitle`` element, because a subtitle
+    and description are not necessarily the same thing. Instead, you should
+    define a ``subtitle`` attribute.
+
+    In the above example, we simply set the Atom feed's ``subtitle`` to the
+    RSS feed's ``description``, because it's quite short already.
 
 And the accompanying URLconf::
 
diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt
index 2eabae96f0..e9523ebfd5 100644
--- a/docs/tutorial02.txt
+++ b/docs/tutorial02.txt
@@ -61,8 +61,8 @@ tutorial, remember?) You should see the Django admin index page:
    :alt: Django admin index page
    :target: http://media.djangoproject.com/img/doc/tutorial/admin02.png
 
-By default, you should see two types of editable content: groups and users.
-These are core features Django ships with by default.
+You should see a few other types of editable content, including groups, users
+and sites. These are core features Django ships with by default.
 
 .. _"I can't log in" questions: ../faq/#the-admin-site
 
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index e6e1cb6cbf..39eed0625b 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -192,10 +192,11 @@ The remaining arguments should be tuples in this format::
 
 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
+**New in Django development version**
+
+You can use the ``url()`` function, instead of a tuple, as an argument to
+``patterns()``. This is convenient if you want to specify a name without the
 optional extra arguments dictionary. For example::
 
     urlpatterns = patterns('',
@@ -498,26 +499,40 @@ the view prefix (as explained in "The view prefix" above) will have no effect.
 Naming URL patterns
 ===================
 
-**New in development version**
+**New in Django development version**
+
+It's fairly common to use the same view function in multiple URL patterns in
+your URLconf. For example, these two URL patterns both point to the ``archive``
+view::
+
+    urlpatterns = patterns('',
+        (r'/archive/(\d{4})/$', archive),
+        (r'/archive-summary/(\d{4})/$', archive, {'summary': True}),
+    )
+
+This is completely valid, but it leads to problems when you try to do reverse
+URL matching (through the ``permalink()`` decorator or the ``{% url %}``
+template tag). Continuing this example, if you wanted to retrieve the URL for
+the ``archive`` view, Django's reverse URL matcher would get confused, because
+*two* URLpatterns point at that view.
 
-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, Django supports **named URL patterns**. That is, you can
+give a name to a URL pattern in order to distinguish it from other patterns
+using the same view and parameters. Then, you can use this name in reverse URL
+matching.
 
-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::
+Here's the above example, rewritten to used named URL patterns::
 
     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::
+With these names in place (``full-archive`` and ``arch-summary``), you can
+target each pattern individually by using its name::
 
     {% url arch-summary 1945 %}
+    {% url full-archive 2007 %}
 
 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.
@@ -527,11 +542,12 @@ 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*.
+    When you name your URL patterns, make sure 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's
+    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. We recommend something like
+    ``myapp-comment`` instead of ``comment``.