schema-evolution: update from HEAD (v5821)

git-svn-id: http://code.djangoproject.com/svn/django/branches/schema-evolution@5822 bcc190cf-cafb-0310-a4f2-bffc1f526a37

22 files changed, 268 insertions, 124 deletions

diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index ffc4f7420f..8682208970 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -214,7 +214,7 @@ A framework for generating syndication feeds, in RSS and Atom, quite easily.
 
 See the `syndication documentation`_.
 
-.. _syndication documentation: ../syndication/
+.. _syndication documentation: ../syndication_feeds/
 
 Other add-ons
 =============
diff --git a/docs/api_stability.txt b/docs/api_stability.txt
index cfaffeac6b..5ccf104327 100644
--- a/docs/api_stability.txt
+++ b/docs/api_stability.txt
@@ -82,9 +82,6 @@ that 90% of Django can be considered forwards-compatible at this point.
 That said, these APIs should *not* be considered stable, and are likely to
 change:
 
-   - `Forms and validation`_ will most likely be completely rewritten to
-     deemphasize Manipulators in favor of validation-aware models.
-
    - `Serialization`_ is under heavy development; changes are likely.
 
    - The `authentication`_ framework is changing to be far more flexible, and
@@ -114,7 +111,7 @@ change:
 .. _sending email: ../email/
 .. _sessions: ../sessions/
 .. _settings: ../settings/
-.. _syndication: ../syndication/
+.. _syndication: ../syndication_feeds/
 .. _template language: ../templates/
 .. _transactions: ../transactions/
 .. _url dispatch: ../url_dispatch/
diff --git a/docs/authentication.txt b/docs/authentication.txt
index a05624db68..589e8c9f1b 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -234,7 +234,7 @@ the setting and checking of these values behind the scenes.
 
 Previous Django versions, such as 0.90, used simple MD5 hashes without password
 salts. For backwards compatibility, those are still supported; they'll be
-converted automatically to the new style the first time ``check_password()``
+converted automatically to the new style the first time ``User.check_password()``
 works correctly for a given user.
 
 Anonymous users
diff --git a/docs/contributing.txt b/docs/contributing.txt
index 9dbb865a58..faa4c113f1 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -340,14 +340,14 @@ Model style
       Do this::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
 
       Don't do this::
 
           class Person(models.Model):
-              FirstName = models.CharField(maxlength=20)
-              Last_Name = models.CharField(maxlength=40)
+              FirstName = models.CharField(max_length=20)
+              Last_Name = models.CharField(max_length=40)
 
     * The ``class Meta`` should appear *after* the fields are defined, with
       a single blank line separating the fields and the class definition.
@@ -355,8 +355,8 @@ Model style
       Do this::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
 
               class Meta:
                   verbose_name_plural = 'people'
@@ -364,8 +364,8 @@ Model style
       Don't do this::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
               class Meta:
                   verbose_name_plural = 'people'
 
@@ -375,8 +375,8 @@ Model style
               class Meta:
                   verbose_name_plural = 'people'
 
-              first_name = models.CharField(maxlength=20)
-              last_name = models.CharField(maxlength=40)
+              first_name = models.CharField(max_length=20)
+              last_name = models.CharField(max_length=40)
 
     * The order of model inner classes and standard methods should be as
       follows (noting that these are not all required):
diff --git a/docs/databases.txt b/docs/databases.txt
index b73f39843c..ed0cb61bc3 100644
--- a/docs/databases.txt
+++ b/docs/databases.txt
@@ -124,7 +124,7 @@ Several other MySQLdb connection options may be useful, such as ``ssl``,
 ``use_unicode``, ``init_command``, and ``sql_mode``. Consult the
 `MySQLdb documentation`_ for more details.
 
-.. _settings documentation: http://www.djangoproject.com/documentation/settings/#database-engine
+.. _settings documentation: ../settings/#database-engine
 .. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html
 .. _MySQLdb documentation: http://mysql-python.sourceforge.net/
 
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 975a166b6b..766a6ae519 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -12,14 +12,14 @@ Throughout this reference, we'll refer to the following models, which comprise
 a weblog application::
 
     class Blog(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         tagline = models.TextField()
 
         def __unicode__(self):
             return self.name
 
     class Author(models.Model):
-        name = models.CharField(maxlength=50)
+        name = models.CharField(max_length=50)
         email = models.EmailField()
 
         def __unicode__(self):
@@ -27,7 +27,7 @@ a weblog application::
 
     class Entry(models.Model):
         blog = models.ForeignKey(Blog)
-        headline = models.CharField(maxlength=255)
+        headline = models.CharField(max_length=255)
         body_text = models.TextField()
         pub_date = models.DateTimeField()
         authors = models.ManyToManyField(Author)
@@ -1503,7 +1503,7 @@ precede the definition of any keyword arguments. For example::
 
 See the `OR lookups examples page`_ for more examples.
 
-.. _OR lookups examples page: http://www.djangoproject.com/documentation/models/or_lookups/
+.. _OR lookups examples page: ../models/or_lookups/
 
 Related objects
 ===============
@@ -1806,8 +1806,8 @@ following model::
         ('F', 'Female'),
     )
     class Person(models.Model):
-        name = models.CharField(maxlength=20)
-        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+        name = models.CharField(max_length=20)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
 
 ...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
 
@@ -1834,7 +1834,7 @@ Note that in the case of identical date values, these methods will use the ID
 as a fallback check. This guarantees that no records are skipped or duplicated.
 For a full example, see the `lookup API sample model`_.
 
-.. _lookup API sample model: http://www.djangoproject.com/documentation/models/lookup/
+.. _lookup API sample model: ../models/lookup/
 
 get_FOO_filename()
 ------------------
diff --git a/docs/email.txt b/docs/email.txt
index 50dafaf8df..97bdec0037 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -314,7 +314,7 @@ To send a text and HTML combination, you could write::
 
     subject, from_email, to = 'hello', 'from@example.com', 'to@example.com'
     text_content = 'This is an important message.'
-    html_content = '<p>This is an <strong>important</strong> message.'
+    html_content = '<p>This is an <strong>important</strong> message.</p>'
     msg = EmailMultiAlternatives(subject, text_content, from_email, to)
     msg.attach_alternative(html_content, "text/html")
     msg.send()
diff --git a/docs/faq.txt b/docs/faq.txt
index 67ed8a49a5..844ea77809 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -42,7 +42,10 @@ Listen to his music. You'll like it.
 
 Django is pronounced **JANG**-oh. Rhymes with FANG-oh. The "D" is silent.
 
+We've also recorded an `audio clip of the pronunciation`_.
+
 .. _Django Reinhardt: http://en.wikipedia.org/wiki/Django_Reinhardt
+.. _audio clip of the pronunciation: http://red-bean.com/~adrian/django_pronunciation.mp3
 
 Is Django stable?
 -----------------
diff --git a/docs/forms.txt b/docs/forms.txt
index 18d3d3fcbe..18d322a8eb 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -37,11 +37,11 @@ this document, we'll be working with the following model, a "place" object::
     )
 
     class Place(models.Model):
-        name = models.CharField(maxlength=100)
-        address = models.CharField(maxlength=100, blank=True)
-        city = models.CharField(maxlength=50, blank=True)
+        name = models.CharField(max_length=100)
+        address = models.CharField(max_length=100, blank=True)
+        city = models.CharField(max_length=50, blank=True)
         state = models.USStateField()
-        zip_code = models.CharField(maxlength=5, blank=True)
+        zip_code = models.CharField(max_length=5, blank=True)
         place_type = models.IntegerField(choices=PLACE_TYPES)
 
         class Admin:
@@ -388,7 +388,7 @@ for a "contact" form on a website::
         def __init__(self):
             self.fields = (
                 forms.EmailField(field_name="from", is_required=True),
-                forms.TextField(field_name="subject", length=30, maxlength=200, is_required=True),
+                forms.TextField(field_name="subject", length=30, max_length=200, is_required=True),
                 forms.SelectField(field_name="urgency", choices=urgency_choices),
                 forms.LargeTextField(field_name="contents", is_required=True),
             )
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 6a706c57cb..3b634de1d8 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -22,7 +22,7 @@ A companion to this document is the `official repository of model examples`_.
 ``tests/modeltests`` directory.)
 
 .. _Database API reference: ../db-api/
-.. _official repository of model examples: http://www.djangoproject.com/documentation/models/
+.. _official repository of model examples: ../models/
 
 Quick example
 =============
@@ -33,8 +33,8 @@ This example model defines a ``Person``, which has a ``first_name`` and
     from django.db import models
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=30)
-        last_name = models.CharField(maxlength=30)
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
 
 ``first_name`` and ``last_name`` are *fields* of the model. Each field is
 specified as a class attribute, and each attribute maps to a database column.
@@ -69,13 +69,13 @@ attributes.
 Example::
 
     class Musician(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
-        instrument = models.CharField(maxlength=100)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+        instrument = models.CharField(max_length=100)
 
     class Album(models.Model):
         artist = models.ForeignKey(Musician)
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         release_date = models.DateField()
         num_stars = models.IntegerField()
 
@@ -142,14 +142,18 @@ For large amounts of text, use ``TextField``.
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 
-``CharField`` has an extra required argument, ``maxlength``, the maximum length
-(in characters) of the field. The maxlength is enforced at the database level
+``CharField`` has an extra required argument, ``max_length``, the maximum length
+(in characters) of the field. The max_length is enforced at the database level
 and in Django's validation.
 
-``CommaSeparatedIntegerField``
+Django veterans: Note that the argument is now called ``max_length`` to
+provide consistency throughout Django. There is full legacy support for
+the old ``maxlength`` argument, but ``max_length`` is prefered.
+	
+ ``CommaSeparatedIntegerField``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A field of integers separated by commas. As in ``CharField``, the ``maxlength``
+A field of integers separated by commas. As in ``CharField``, the ``max_length``
 argument is required.
 
 ``DateField``
@@ -217,7 +221,7 @@ The admin represents this as an ``<input type="text">`` (a single-line input).
 ~~~~~~~~~~~~~~
 
 A ``CharField`` that checks that the value is a valid e-mail address.
-This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to
+This doesn't accept ``max_length``; its ``max_length`` is automatically set to
 75.
 
 ``FileField``
@@ -400,7 +404,7 @@ Like a ``PositiveIntegerField``, but only allows values under a certain
 containing only letters, numbers, underscores or hyphens. They're generally
 used in URLs.
 
-Like a CharField, you can specify ``maxlength``. If ``maxlength`` is
+Like a CharField, you can specify ``max_length``. If ``max_length`` is
 not specified, Django will use a default length of 50.
 
 Implies ``db_index=True``.
@@ -447,9 +451,9 @@ and doesn't give a 404 response).
 
 The admin represents this as an ``<input type="text">`` (a single-line input).
 
-``URLField`` takes an optional argument, ``maxlength``, the maximum length (in
-characters) of the field. The maxlength is enforced at the database level and
-in Django's validation. If you don't specify ``maxlength``, a default of 200
+``URLField`` takes an optional argument, ``max_length``, the maximum length (in
+characters) of the field. The maximum length is enforced at the database level and
+in Django's validation. If you don't specify ``max_length``, a default of 200
 is used.
 
 ``USStateField``
@@ -536,7 +540,7 @@ The choices list can be defined either as part of your model class::
             ('M', 'Male'),
             ('F', 'Female'),
         )
-        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
 
 or outside your model class altogether::
 
@@ -545,7 +549,7 @@ or outside your model class altogether::
         ('F', 'Female'),
     )
     class Foo(models.Model):
-        gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
 
 For each model field that has ``choices`` set, Django will add a method to
 retrieve the human-readable name for the field's current value. See
@@ -620,6 +624,12 @@ Extra "help" text to be displayed under the field on the object's admin
 form. It's useful for documentation even if your object doesn't have an
 admin form.
 
+Note that this value is *not* HTML-escaped when it's displayed in the admin
+interface. This lets you include HTML in ``help_text`` if you so desire. For
+example::
+
+	help_text="Please use the following format: <em>YYYY-MM-DD</em>."
+
 ``primary_key``
 ~~~~~~~~~~~~~~~
 
@@ -698,11 +708,11 @@ it using the field's attribute name, converting underscores to spaces.
 
 In this example, the verbose name is ``"Person's first name"``::
 
-    first_name = models.CharField("Person's first name", maxlength=30)
+    first_name = models.CharField("Person's first name", max_length=30)
 
 In this example, the verbose name is ``"first name"``::
 
-    first_name = models.CharField(maxlength=30)
+    first_name = models.CharField(max_length=30)
 
 ``ForeignKey``, ``ManyToManyField`` and ``OneToOneField`` require the first
 argument to be a model class, so use the ``verbose_name`` keyword argument::
@@ -775,7 +785,7 @@ You can, of course, call the field whatever you want. For example::
 
 See the `Many-to-one relationship model example`_ for a full example.
 
-.. _Many-to-one relationship model example: http://www.djangoproject.com/documentation/models/many_to_one/
+.. _Many-to-one relationship model example: ../models/many_to_one/
 
 ``ForeignKey`` fields take a number of extra arguments for defining how the
 relationship should work. All are optional:
@@ -902,7 +912,7 @@ set up above, the ``Pizza`` admin form would let users select the toppings.
 
 See the `Many-to-many relationship model example`_ for a full example.
 
-.. _Many-to-many relationship model example: http://www.djangoproject.com/documentation/models/many_to_many/
+.. _Many-to-many relationship model example: ../models/many_to_many/
 
 ``ManyToManyField`` objects take a number of extra arguments for defining how
 the relationship should work. All are optional:
@@ -979,7 +989,7 @@ as a read-only field when you edit an object in the admin interface:
 
 See the `One-to-one relationship model example`_ for a full example.
 
-.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
+.. _One-to-one relationship model example: ../models/one_to_one/
 
 Custom field types
 ------------------
@@ -1027,8 +1037,8 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
 ``Field`` type::
 
     class Person(models.Model):
-        name = models.CharField(maxlength=80)
-        gender = models.CharField(maxlength=1)
+        name = models.CharField(max_length=80)
+        gender = models.CharField(max_length=1)
         something_else = MytypeField()
 
 If you aim to build a database-agnostic application, you should account for
@@ -1074,12 +1084,12 @@ time -- i.e., when the class is instantiated. To do that, just implement
 
     # This is a much more flexible example.
     class BetterCharField(models.Field):
-        def __init__(self, maxlength, *args, **kwargs):
-            self.maxlength = maxlength
+        def __init__(self, max_length, *args, **kwargs):
+            self.max_length = max_length
             super(BetterCharField, self).__init__(*args, **kwargs)
 
         def db_type(self):
-            return 'char(%s)' % self.maxlength
+            return 'char(%s)' % self.max_length
 
     # In the model:
     class MyModel(models.Model):
@@ -1096,7 +1106,7 @@ Meta options
 Give your model metadata by using an inner ``class Meta``, like so::
 
     class Foo(models.Model):
-        bar = models.CharField(maxlength=30)
+        bar = models.CharField(max_length=30)
 
         class Meta:
             # ...
@@ -1186,7 +1196,7 @@ See `Specifying ordering`_ for more examples.
 Note that, regardless of how many fields are in ``ordering``, the admin
 site uses only the first field.
 
-.. _Specifying ordering: http://www.djangoproject.com/documentation/models/ordering/
+.. _Specifying ordering: ../models/ordering/
 
 ``permissions``
 ---------------
@@ -1270,8 +1280,8 @@ If you want your model to be visible to Django's admin site, give your model an
 inner ``"class Admin"``, like so::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=30)
-        last_name = models.CharField(maxlength=30)
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
 
         class Admin:
             # Admin options go here
@@ -1430,7 +1440,7 @@ A few special cases to note about ``list_display``:
       Here's a full example model::
 
           class Person(models.Model):
-              name = models.CharField(maxlength=50)
+              name = models.CharField(max_length=50)
               birthday = models.DateField()
 
               class Admin:
@@ -1447,9 +1457,9 @@ A few special cases to note about ``list_display``:
       Here's a full example model::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=50)
-              last_name = models.CharField(maxlength=50)
-              color_code = models.CharField(maxlength=6)
+              first_name = models.CharField(max_length=50)
+              last_name = models.CharField(max_length=50)
+              color_code = models.CharField(max_length=6)
 
               class Admin:
                   list_display = ('first_name', 'last_name', 'colored_name')
@@ -1465,7 +1475,7 @@ A few special cases to note about ``list_display``:
       Here's a full example model::
 
           class Person(models.Model):
-              first_name = models.CharField(maxlength=50)
+              first_name = models.CharField(max_length=50)
               birthday = models.DateField()
 
               class Admin:
@@ -1493,8 +1503,8 @@ A few special cases to note about ``list_display``:
       For example::
 
         class Person(models.Model):
-            first_name = models.CharField(maxlength=50)
-            color_code = models.CharField(maxlength=6)
+            first_name = models.CharField(max_length=50)
+            color_code = models.CharField(max_length=6)
 
             class Admin:
                 list_display = ('first_name', 'colored_first_name')
@@ -1744,13 +1754,13 @@ returns a list of all ``OpinionPoll`` objects, each with an extra
             return result_list
 
     class OpinionPoll(models.Model):
-        question = models.CharField(maxlength=200)
+        question = models.CharField(max_length=200)
         poll_date = models.DateField()
         objects = PollManager()
 
     class Response(models.Model):
         poll = models.ForeignKey(Poll)
-        person_name = models.CharField(maxlength=50)
+        person_name = models.CharField(max_length=50)
         response = models.TextField()
 
 With this example, you'd use ``OpinionPoll.objects.with_counts()`` to return
@@ -1766,8 +1776,8 @@ A ``Manager``'s base ``QuerySet`` returns all objects in the system. For
 example, using this model::
 
     class Book(models.Model):
-        title = models.CharField(maxlength=100)
-        author = models.CharField(maxlength=50)
+        title = models.CharField(max_length=100)
+        author = models.CharField(max_length=50)
 
 ...the statement ``Book.objects.all()`` will return all books in the database.
 
@@ -1785,8 +1795,8 @@ all objects, and one that returns only the books by Roald Dahl::
 
     # Then hook it into the Book model explicitly.
     class Book(models.Model):
-        title = models.CharField(maxlength=100)
-        author = models.CharField(maxlength=50)
+        title = models.CharField(max_length=100)
+        author = models.CharField(max_length=50)
 
         objects = models.Manager() # The default manager.
         dahl_objects = DahlBookManager() # The Dahl-specific manager.
@@ -1819,9 +1829,9 @@ For example::
             return super(FemaleManager, self).get_query_set().filter(sex='F')
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
-        sex = models.CharField(maxlength=1, choices=(('M', 'Male'), ('F', 'Female')))
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+        sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))
         people = models.Manager()
         men = MaleManager()
         women = FemaleManager()
@@ -1851,11 +1861,11 @@ model.
 For example, this model has a few custom methods::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
         birth_date = models.DateField()
-        address = models.CharField(maxlength=100)
-        city = models.CharField(maxlength=50)
+        address = models.CharField(max_length=100)
+        city = models.CharField(max_length=50)
         state = models.USStateField() # Yes, this is America-centric...
 
         def baby_boomer_status(self):
@@ -1897,8 +1907,8 @@ Although this isn't required, it's strongly encouraged (see the description of
 For example::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
 
         def __str__(self):
             # Note use of django.utils.encoding.smart_str() here because
@@ -1915,8 +1925,8 @@ method for your model. The example in the previous section could be written
 more simply as::
 
     class Person(models.Model):
-        first_name = models.CharField(maxlength=50)
-        last_name = models.CharField(maxlength=50)
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
 
         def __unicode__(self):
             return u'%s %s' % (self.first_name, self.last_name)
@@ -1942,10 +1952,12 @@ Django uses this in its admin interface. If an object defines
 link that will jump you directly to the object's public view, according to
 ``get_absolute_url()``.
 
-Also, a couple of other bits of Django, such as the syndication-feed framework,
+Also, a couple of other bits of Django, such as the `syndication feed framework`_,
 use ``get_absolute_url()`` as a convenience to reward people who've defined the
 method.
 
+.. syndication feed framework: ../syndication_feeds/
+
 It's good practice to use ``get_absolute_url()`` in templates, instead of
 hard-coding your objects' URLs. For example, this template code is bad::
 
@@ -2056,7 +2068,7 @@ A classic use-case for overriding the built-in methods is if you want something
 to happen whenever you save an object. For example::
 
     class Blog(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         tagline = models.TextField()
 
         def save(self):
@@ -2067,7 +2079,7 @@ to happen whenever you save an object. For example::
 You can also prevent saving::
 
     class Blog(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         tagline = models.TextField()
 
         def save(self):
diff --git a/docs/newforms.txt b/docs/newforms.txt
index a51317343f..4f63411875 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -641,7 +641,7 @@ the "Outputting forms as HTML" section above.
 The simplest way to display a form's HTML is to use the variable on its own,
 like this::
 
-    <form method="post">
+    <form method="post" action="">
     <table>{{ form }}</table>
     <input type="submit" />
     </form>
@@ -653,7 +653,7 @@ class' ``__str__()`` method calls its ``as_table()`` method.
 
 The following is equivalent but a bit more explicit::
 
-    <form method="post">
+    <form method="post" action="">
     <table>{{ form.as_table }}</table>
     <input type="submit" />
     </form>
@@ -675,7 +675,7 @@ individual fields for complete template control over the form's design.
 The easiest way is to iterate over the form's fields, with
 ``{% for field in form %}``. For example::
 
-    <form method="post">
+    <form method="post" action="">
     <dl>
     {% for field in form %}
         <dt>{{ field.label }}</dt>
@@ -696,7 +696,7 @@ Alternatively, you can arrange the form's fields explicitly, by name. Do that
 by accessing ``{{ form.fieldname }}``, where ``fieldname`` is the field's name.
 For example::
 
-    <form method="post">
+    <form method="post" action="">
     <ul class="myformclass">
         <li>{{ form.sender.label }} {{ form.sender }}</li>
         <li class="helptext">{{ form.sender.help_text }}</li>
@@ -710,6 +710,49 @@ For example::
     </ul>
     </form>
 
+Binding uploaded files to a form
+--------------------------------
+
+**New in Django development version**
+
+Dealing with forms that have ``FileField`` and ``ImageField`` fields
+is a little more complicated than a normal form.
+
+Firstly, in order to upload files, you'll need to make sure that your
+``<form>`` element correctly defines the ``enctype`` as
+``"multipart/form-data"``::
+
+  <form enctype="multipart/form-data" method="post" action="/foo/">
+
+Secondly, when you use the form, you need to bind the file data. File
+data is handled separately to normal form data, so when your form
+contains a ``FileField`` and ``ImageField``, you will need to specify
+a second argument when you bind your form. So if we extend our
+ContactForm to include an ``ImageField`` called ``mugshot``, we
+need to bind the file data containing the mugshot image::
+
+    # Bound form with an image field
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> file_data = {'mugshot': {'filename':'face.jpg'
+    ...                          'content': <file data>}}
+    >>> f = ContactFormWithMugshot(data, file_data)
+
+In practice, you will usually specify ``request.FILES`` as the source
+of file data (just like you use ``request.POST`` as the source of
+form data)::
+
+    # Bound form with an image field, data from the request
+    >>> f = ContactFormWithMugshot(request.POST, request.FILES)
+
+Constructing an unbound form is the same as always -- just omit both
+form data *and* file data:
+
+    # Unbound form with a image field
+    >>> f = ContactFormWithMugshot()
+
 Subclassing forms
 -----------------
 
@@ -1099,6 +1142,54 @@ Has two optional arguments for validation, ``max_length`` and ``min_length``.
 If provided, these arguments ensure that the string is at most or at least the
 given length.
 
+``FileField``
+~~~~~~~~~~~~~
+
+**New in Django development version**
+
+    * Default widget: ``FileInput``
+    * Empty value: ``None``
+    * Normalizes to: An ``UploadedFile`` object that wraps the file content
+      and file name into a single object.
+    * Validates that non-empty file data has been bound to the form.
+
+An ``UploadedFile`` object has two attributes:
+
+    ======================  =====================================================
+    Argument                Description
+    ======================  =====================================================
+    ``filename``            The name of the file, provided by the uploading
+                            client.
+    ``content``             The array of bytes comprising the file content.
+    ======================  =====================================================
+
+The string representation of an ``UploadedFile`` is the same as the filename
+attribute.
+
+When you use a ``FileField`` on a form, you must also remember to
+`bind the file data to the form`_.
+
+.. _`bind the file data to the form`: `Binding uploaded files to a form`_
+
+``ImageField``
+~~~~~~~~~~~~~~
+
+**New in Django development version**
+
+    * Default widget: ``FileInput``
+    * Empty value: ``None``
+    * Normalizes to: An ``UploadedFile`` object that wraps the file content
+      and file name into a single object.
+    * Validates that file data has been bound to the form, and that the
+      file is of an image format understood by PIL.
+
+Using an ImageField requires that the `Python Imaging Library`_ is installed.
+
+When you use a ``FileField`` on a form, you must also remember to
+`bind the file data to the form`_.
+
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
 ``IntegerField``
 ~~~~~~~~~~~~~~~~
 
@@ -1222,7 +1313,7 @@ Custom form and field validation
 
 Form validation happens when the data is cleaned. If you want to customise
 this process, there are various places you can change, each one serving a
-different purpose. Thee types of cleaning methods are run during form
+different purpose. Three types of cleaning methods are run during form
 processing. These are normally executed when you call the ``is_valid()``
 method on a form. There are other things that can trigger cleaning and
 validation (accessing the ``errors`` attribute or calling ``full_clean()``
@@ -1372,17 +1463,17 @@ the full list of conversions:
     ``AutoField``                    Not represented in the form
     ``BooleanField``                 ``BooleanField``
     ``CharField``                    ``CharField`` with ``max_length`` set to
-                                     the model field's ``maxlength``
+                                     the model field's ``max_length``
     ``CommaSeparatedIntegerField``   ``CharField``
     ``DateField``                    ``DateField``
     ``DateTimeField``                ``DateTimeField``
     ``DecimalField``                 ``DecimalField``
     ``EmailField``                   ``EmailField``
-    ``FileField``                    ``CharField``
+    ``FileField``                    ``FileField``
     ``FilePathField``                ``CharField``
     ``FloatField``                   ``FloatField``
     ``ForeignKey``                   ``ModelChoiceField`` (see below)
-    ``ImageField``                   ``CharField``
+    ``ImageField``                   ``ImageField``
     ``IntegerField``                 ``IntegerField``
     ``IPAddressField``               ``CharField``
     ``ManyToManyField``              ``ModelMultipleChoiceField`` (see
@@ -1452,15 +1543,15 @@ Consider this set of models::
     )
 
     class Author(models.Model):
-        name = models.CharField(maxlength=100)
-        title = models.CharField(maxlength=3, choices=TITLE_CHOICES)
+        name = models.CharField(max_length=100)
+        title = models.CharField(max_length=3, choices=TITLE_CHOICES)
         birth_date = models.DateField(blank=True, null=True)
 
         def __unicode__(self):
             return self.name
 
     class Book(models.Model):
-        name = models.CharField(maxlength=100)
+        name = models.CharField(max_length=100)
         authors = models.ManyToManyField(Author)
 
 With these models, a call to ``form_for_model(Author)`` would return a ``Form``
@@ -1502,6 +1593,44 @@ the database. In this case, it's up to you to call ``save()`` on the resulting
 model instance. This is useful if you want to do custom processing on the
 object before saving it. ``commit`` is ``True`` by default.
 
+Another side effect of using ``commit=False`` is seen when your model has
+a many-to-many relation with another model. If your model has a many-to-many
+relation and you specify ``commit=False`` when you save a form, Django cannot
+immediately save the form data for the many-to-many relation. This is because
+it isn't possible to save many-to-many data for an instance until the instance
+exists in the database.
+
+To work around this problem, every time you save a form using ``commit=False``,
+Django adds a ``save_m2m()`` method to the form created by ``form_for_model``.
+After you've manually saved the instance produced by the form, you can invoke
+``save_m2m()`` to save the many-to-many form data. For example::
+
+    # Create a form instance with POST data.
+    >>> f = AuthorForm(request.POST)
+
+    # Create, but don't save the new author instance.
+    >>> new_author = f.save(commit=False)
+
+    # Modify the author in some way.
+    >>> new_author.some_field = 'some_value'
+
+    # Save the new instance.
+    >>> new_author.save()
+
+    # Now, save the many-to-many data for the form.
+    >>> f.save_m2m()
+
+Calling ``save_m2m()`` is only required if you use ``save(commit=False)``.
+When you use a simple ``save()`` on a form, all data -- including
+many-to-many data -- is saved without the need for any additional method calls.
+For example::
+
+	# Create a form instance with POST data.
+	>>> f = AuthorForm(request.POST)
+
+    # Create and save the new author instance. There's no need to do anything else.
+    >>> new_author = f.save()
+
 Using an alternate base class
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/overview.txt b/docs/overview.txt
index 46211432cb..b0311cee96 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -25,14 +25,14 @@ far, it's been solving two years' worth of database-schema problems. Here's a
 quick example::
 
     class Reporter(models.Model):
-        full_name = models.CharField(maxlength=70)
+        full_name = models.CharField(max_length=70)
 
         def __unicode__(self):
             return self.full_name
 
     class Article(models.Model):
         pub_date = models.DateTimeField()
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         article = models.TextField()
         reporter = models.ForeignKey(Reporter)
 
@@ -134,7 +134,7 @@ your model classes::
 
     class Article(models.Model):
         pub_date = models.DateTimeField()
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         article = models.TextField()
         reporter = models.ForeignKey(Reporter)
         class Admin: pass
@@ -288,14 +288,16 @@ This has been only a quick overview of Django's functionality. Some more useful
 features:
 
     * A caching framework that integrates with memcached or other backends.
-    * A syndication framework that makes creating RSS and Atom feeds as easy as
+    * A `syndication framework`_ that makes creating RSS and Atom feeds as easy as
       writing a small Python class.
     * More sexy automatically-generated admin features -- this overview barely
       scratched the surface.
 
+.. _syndication framework: ../syndication_feeds/
+
 The next obvious steps are for you to `download Django`_, read `the tutorial`_
 and join `the community`_. Thanks for your interest!
 
 .. _download Django: http://www.djangoproject.com/download/
-.. _the tutorial: http://www.djangoproject.com/documentation/tutorial01/
+.. _the tutorial: ../tutorial01/
 .. _the community: http://www.djangoproject.com/community/
diff --git a/docs/release_notes_0.95.txt b/docs/release_notes_0.95.txt
index 3709cacf5a..f2ecbb66e6 100644
--- a/docs/release_notes_0.95.txt
+++ b/docs/release_notes_0.95.txt
@@ -114,7 +114,7 @@ there's a #django channel on irc.freenode.net that is regularly populated by
 Django users and developers from around the world. Friendly people are usually
 available at any hour of the day -- to help, or just to chat.
 
-.. _online: http://www.djangoproject.com/documentation/
+.. _online: http://www.djangoproject.com/documentation/0.95/
 .. _Django website: http://www.djangoproject.com/
 .. _FAQ: http://www.djangoproject.com/documentation/faq/
 .. _django-users: http://groups.google.com/group/django-users
diff --git a/docs/request_response.txt b/docs/request_response.txt
index 0b985d563b..a17a60ff17 100644
--- a/docs/request_response.txt
+++ b/docs/request_response.txt
@@ -297,7 +297,7 @@ In contrast to ``HttpRequest`` objects, which are created automatically by
 Django, ``HttpResponse`` objects are your responsibility. Each view you write
 is responsible for instantiating, populating and returning an ``HttpResponse``.
 
-The ``HttpResponse`` class lives at ``django.http.HttpResponse``.
+The ``HttpResponse`` class lives in the ``django.http`` module.
 
 Usage
 -----
diff --git a/docs/sitemaps.txt b/docs/sitemaps.txt
index 550f448de1..1d4fba2626 100644
--- a/docs/sitemaps.txt
+++ b/docs/sitemaps.txt
@@ -21,7 +21,7 @@ you express this information in Python code.
 It works much like Django's `syndication framework`_. To create a sitemap, just
 write a ``Sitemap`` class and point to it in your URLconf_.
 
-.. _syndication framework: ../syndication/
+.. _syndication framework: ../syndication_feeds/
 .. _URLconf: ../url_dispatch/
 
 Installation
diff --git a/docs/sites.txt b/docs/sites.txt
index e9982f745a..90a9d0f90f 100644
--- a/docs/sites.txt
+++ b/docs/sites.txt
@@ -46,7 +46,7 @@ that's represented by a ``ManyToManyField`` in the ``Article`` model::
     from django.contrib.sites.models import Site
 
     class Article(models.Model):
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         # ...
         sites = models.ManyToManyField(Site)
 
@@ -87,7 +87,7 @@ like this::
     from django.contrib.sites.models import Site
 
     class Article(models.Model):
-        headline = models.CharField(maxlength=200)
+        headline = models.CharField(max_length=200)
         # ...
         site = models.ForeignKey(Site)
 
@@ -229,7 +229,7 @@ Use ``CurrentSiteManager`` by adding it to your model explicitly. For example::
 
     class Photo(models.Model):
         photo = models.FileField(upload_to='/home/photos')
-        photographer_name = models.CharField(maxlength=100)
+        photographer_name = models.CharField(max_length=100)
         pub_date = models.DateField()
         site = models.ForeignKey(Site)
         objects = models.Manager()
@@ -257,7 +257,7 @@ this::
 
     class Photo(models.Model):
         photo = models.FileField(upload_to='/home/photos')
-        photographer_name = models.CharField(maxlength=100)
+        photographer_name = models.CharField(max_length=100)
         pub_date = models.DateField()
         publish_on = models.ForeignKey(Site)
         objects = models.Manager()
@@ -318,7 +318,7 @@ Here's how Django uses the sites framework:
 
 .. _redirects framework: ../redirects/
 .. _flatpages framework: ../flatpages/
-.. _syndication framework: ../syndication/
+.. _syndication framework: ../syndication_feeds/
 .. _authentication framework: ../authentication/
 
 ``RequestSite`` objects
diff --git a/docs/testing.txt b/docs/testing.txt
index f4b78273ce..52285f5e8e 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -79,8 +79,8 @@ For example::
         'The cat says "meow"'
         """
 
-        name = models.CharField(maxlength=20)
-        sound = models.CharField(maxlength=20)
+        name = models.CharField(max_length=20)
+        sound = models.CharField(max_length=20)
 
         def speak(self):
             return 'The %s says "%s"' % (self.name, self.sound)
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 180e30292d..32480ca487 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -251,12 +251,12 @@ These concepts are represented by simple Python classes. Edit the
     from django.db import models
 
     class Poll(models.Model):
-        question = models.CharField(maxlength=200)
+        question = models.CharField(max_length=200)
         pub_date = models.DateTimeField('date published')
 
     class Choice(models.Model):
         poll = models.ForeignKey(Poll)
-        choice = models.CharField(maxlength=200)
+        choice = models.CharField(max_length=200)
         votes = models.IntegerField()
 
 The code is straightforward. Each model is represented by a class that
@@ -279,7 +279,7 @@ name for ``Poll.pub_date``. For all other fields in this model, the field's
 machine-readable name will suffice as its human-readable name.
 
 Some ``Field`` classes have required elements. ``CharField``, for example,
-requires that you give it a ``maxlength``. That's used not only in the database
+requires that you give it a ``max_length``. That's used not only in the database
 schema, but in validation, as we'll soon see.
 
 Finally, note a relationship is defined, using ``models.ForeignKey``. That tells
diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt
index 99f586b4a1..b820701d11 100644
--- a/docs/tutorial02.txt
+++ b/docs/tutorial02.txt
@@ -240,7 +240,7 @@ default, provide enough fields for 3 Choices."
 
 Then change the other fields in ``Choice`` to give them ``core=True``::
 
-    choice = models.CharField(maxlength=200, core=True)
+    choice = models.CharField(max_length=200, core=True)
     votes = models.IntegerField(core=True)
 
 This tells Django: "When you edit a Choice on the Poll admin page, the 'choice'
diff --git a/docs/tutorial03.txt b/docs/tutorial03.txt
index bf85c27231..d49a417dcf 100644
--- a/docs/tutorial03.txt
+++ b/docs/tutorial03.txt
@@ -356,7 +356,8 @@ Use the template system
 =======================
 
 Back to the ``detail()`` view for our poll application. Given the context 
-variable ``poll``, here's what the template might look like::
+variable ``poll``, here's what the "polls/detail.html" template might look
+like::
 
     <h1>{{ poll.question }}</h1>
     <ul>
diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt
index cfd9a45a4b..553a76e9b1 100644
--- a/docs/tutorial04.txt
+++ b/docs/tutorial04.txt
@@ -8,8 +8,8 @@ application and will focus on simple form processing and cutting down our code.
 Write a simple form
 ===================
 
-Let's update our poll detail template from the last tutorial, so that the
-template contains an HTML ``<form>`` element::
+Let's update our poll detail template ("polls/detail.html") from the last
+tutorial, so that the template contains an HTML ``<form>`` element::
 
     <h1>{{ poll.question }}</h1>
 
@@ -213,7 +213,7 @@ objects" and "display a detail page for a particular type of object."
       a way to refer to its URL later on (see `naming URL patterns`_ for more on
       named patterns).
       
-.. _naming URL patterns: http://www.djangoproject.com/documentation/url_dispatch/#naming-url-patterns
+.. _naming URL patterns: ../url_dispatch/#naming-url-patterns
 
 By default, the ``object_detail`` generic view uses a template called
 ``<app name>/<model name>_detail.html``. In our case, it'll use the template
diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 716686ff50..f9723a6a89 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -404,7 +404,7 @@ This technique is used in `generic views`_ and in the `syndication framework`_
 to pass metadata and options to views.
 
 .. _generic views: ../generic_views/
-.. _syndication framework: ../syndication/
+.. _syndication framework: ../syndication_feeds/
 
 .. admonition:: Dealing with conflicts