Made a bunch of edits and typo corrections to 1.0-porting-guide.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8966 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/releases/1.0-porting-guide.txt

@@ -4,7 +4,7 @@ Porting your apps from Django 0.96 to 1.0
 
 .. highlight:: python
 
-Django 1.0 breaks compatibility with 0.96 in some areas. 
+Django 1.0 breaks compatibility with 0.96 in some areas.
 
 This guide will help you port 0.96 projects and apps to 1.0. The first part of
 this document includes the common changes needed to run with 1.0. If after going
@@ -97,7 +97,7 @@ New (1.0) ``admin.py``::
 
     from django.contrib import admin
     from models import Author
-    
+
     class AuthorAdmin(admin.ModelAdmin):
         list_display = ['first_name', 'last_name']
         prepopulated_fields = {
@@ -139,7 +139,7 @@ Old (0.96)::
 
     class Parent(models.Model):
         ...
-        
+
     class Child(models.Model):
         parent = models.ForeignKey(Parent, edit_inline=models.STACKED, num_in_admin=3)
 
@@ -149,13 +149,13 @@ New (1.0)::
     class ChildInline(admin.StackedInline):
         model = Child
         extra = 3
-        
+
     class ParentAdmin(models.ModelAdmin):
         model = Parent
         inlines = [ChildInline]
-        
+
     admin.site.register(Parent, ParentAdmin)
-    
+
 See :ref:`admin-inlines` for more details.
 
 Simplify ``fields``, or use ``fieldsets``
@@ -164,37 +164,37 @@ Simplify ``fields``, or use ``fieldsets``
 The old ``fields`` syntax was quite confusing, and has been simplified. The old
 syntax still works, but you'll need to use ``fieldsets`` instead.
 
-Old (0.96)::    
+Old (0.96)::
 
     class ModelOne(models.Model):
         ...
-        
+
         class Admin:
             fields = (
                 (None, {'fields': ('foo','bar')}),
             )
-    
+
     class ModelTwo(models.Model):
         ...
-        
+
         class Admin:
             fields = (
                 ('group1', {'fields': ('foo','bar'),   'classes': 'collapse'}),
                 ('group2', {'fields': ('spam','eggs'), 'classes': 'collapse wide'}),
             )
-            
+
 
 New (1.0)::
 
     class ModelOneAdmin(admin.ModelAdmin):
         fields = ('foo', 'bar')
-        
+
     class ModelTwoAdmin(admin.ModelAdmin):
         fieldsets = (
             ('group1', {'fields': ('foo','bar'),   'classes': 'collapse'}),
             ('group2', {'fields': ('spam','eggs'), 'classes': 'collapse wide'}),
         )
-        
+
 
 .. seealso::
 
@@ -212,7 +212,7 @@ URLs
 Update your root ``urls.py``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are using the admin site you need to update your root ``urls.py``.
+If you're using the admin site, you need to update your root ``urls.py``.
 
 Old (0.96) ``urls.py``::
 
@@ -246,14 +246,23 @@ Use ``django.forms`` instead of ``newforms``
 
 Replace ``django.newforms`` with ``django.forms`` -- Django 1.0 renamed the
 ``newforms`` module (introduced in 0.96) to plain old ``forms``. The
-``oldforms`` module was also removed removed.
+``oldforms`` module was also removed.
 
-If you are already using new forms all you have to do is change your import
-statement. Instead of ``from django import newforms as forms``, use ``from
-django import forms``.
+If you're already using the ``newforms`` library, and you used our recommended
+``import`` statement syntax, all you have to do is change your import
+statements.
 
-If you are using the old forms system, you will have to rewrite your forms. A
-good place to start is the :ref:`forms documentation <topics-forms-index>`
+Old::
+
+    from django import newforms as forms
+
+New::
+
+    from django import forms
+
+If you're using the old forms system (formerly known as ``django.forms`` and
+``django.oldforms``), you'll have to rewrite your forms. A good place to start
+is the :ref:`forms documentation <topics-forms-index>`
 
 Handle uploaded files using the new API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -268,7 +277,7 @@ Thus, in a view like::
           f = request.FILES['file_field_name']
           ...
 
-You'd need to make the following changes:
+...you'd need to make the following changes:
 
 ===================== =====================
 Old (0.96)            New (1.0)
@@ -284,7 +293,7 @@ Templates
 Learn to love autoescaping
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By default, the templating system now automatically HTML-escapes the output of
+By default, the template system now automatically HTML-escapes the output of
 every variable. To learn more, see :ref:`automatic-html-escaping`.
 
 To disable auto-escaping for an individual variable, use the :tfilter:`safe`
@@ -352,18 +361,19 @@ Template tags
 :ttag:`spaceless` tag
 ~~~~~~~~~~~~~~~~~~~~~
 
-The spaceless template tag removes *all* spaces between HTML tags instead of
-preserving a single space.
+The spaceless template tag now removes *all* spaces between HTML tags, instead
+of preserving a single space.
 
-Localflavor
------------
+Local flavors
+-------------
 
-US localflavor
-~~~~~~~~~~~~~~
+U.S. local flavor
+~~~~~~~~~~~~~~~~~
 
-``django.contrib.localflavor.usa`` has been renamed
-:mod:`django.contribg.localflavor.us`. This change was made to match the naming
-scheme of other local flavors.
+``django.contrib.localflavor.usa`` has been renamed to
+:mod:`django.contrib.localflavor.us`. This change was made to match the naming
+scheme of other local flavors. To migrate your code, all you need to do is
+change the imports.
 
 Sessions
 --------
@@ -372,7 +382,7 @@ Getting a new session key
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``SeesionBase.get_new_session_key()`` has been renamed to
-``_get_new_session_key()``; ``get_new_session_object()`` no longer exists.
+``_get_new_session_key()``. ``get_new_session_object()`` no longer exists.
 
 Fixtures
 --------
@@ -390,7 +400,7 @@ Settings
 Better exceptions
 ~~~~~~~~~~~~~~~~~
 
-The old :exc:`EnvironmentError` was split into an :exc:`ImportError` raised when
+The old :exc:`EnvironmentError` has split into an :exc:`ImportError` when
 Django fails to find the settings module and a :exc:`RuntimeError` when you try
 to reconfigure settings after having already used them
 
@@ -401,15 +411,15 @@ The ``LOGIN_URL`` constant moved from ``django.contrib.auth`` into the
 ``settings`` module. Instead of using ``from django.contrib.auth import
 LOGIN_URL`` refer to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
 
-:setting:`APPEND_SLASH` behaviour has been updated
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:setting:`APPEND_SLASH` behavior has been updated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In 0.96, if a URL didn't end in a slash or have a period in the final
-component of it's path, and ``APPEND_SLASH`` was True, Django would redirect
+component of its path, and ``APPEND_SLASH`` was True, Django would redirect
 to the same URL, but with a slash appended to the end. Now, Django checks to
-see if the pattern without the trailing slash would be matched by something in
-your URL patterns. If so, no redirection takes place, because it is assumed
-you deliberately wanted to catch that pattern.
+see whether the pattern without the trailing slash would be matched by
+something in your URL patterns. If so, no redirection takes place, because it
+is assumed you deliberately wanted to catch that pattern.
 
 For most people, this won't require any changes. Some people, though, have URL
 patterns that look like this::
@@ -421,13 +431,13 @@ slash. If you always want a slash on such URLs, rewrite the pattern as::
 
     r'/some_prefix/(.*/)$'
 
-Samller model changes
+Smaller model changes
 ---------------------
 
 Different exception from ``get()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The models manager now returns a :exc:`MultipleObjectsReturned` exception
+Managers now return a :exc:`MultipleObjectsReturned` exception
 instead of :exc:`AssertionError`:
 
 Old (0.96)::
@@ -443,7 +453,7 @@ New (1.0)::
       Model.objects.get(...)
   except Model.MultipleObjectsReturned:
       handle_the_error()
-      
+
 ``LazyDate`` has been fired
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -482,28 +492,28 @@ New (1.0)::
         ...
 
 If you forget to make this change, you will see errors about ``FloatField``
-not taking a ``max_digits`` attribute in ``__init__``, since the new
+not taking a ``max_digits`` attribute in ``__init__``, because the new
 ``FloatField`` takes no precision-related arguments.
 
-If you are using MySQL or PostgreSQL, there are no further changes needed. The
+If you're using MySQL or PostgreSQL, no further changes are needed. The
 database column types for ``DecimalField`` are the same as for the old
 ``FloatField``.
 
-If you are using SQLite, you need to force the database to view the
+If you're using SQLite, you need to force the database to view the
 appropriate columns as decimal types, rather than floats. To do this, you'll
 need to reload your data. Do this after you have made the change to using
 ``DecimalField`` in your code and updated the Django code.
 
 .. warning::
 
-  **Back up your database first!** 
-  
+  **Back up your database first!**
+
   For SQLite, this means making a copy of the single file that stores the
   database (the name of that file is the ``DATABASE_NAME`` in your settings.py
   file).
 
-To upgrade each application to use a ``DecimalField``, do the following,
-replacing ``<app>`` in the code below with each app's name:
+To upgrade each application to use a ``DecimalField``, you can do the
+following, replacing ``<app>`` in the code below with each app's name:
 
 .. code-block:: bash
 
@@ -513,15 +523,15 @@ replacing ``<app>`` in the code below with each app's name:
 
 Notes:
 
-  1. It is important that you remember to use XML format in the first step of
+  1. It's important that you remember to use XML format in the first step of
      this process. We are exploiting a feature of the XML data dumps that makes
      porting floats to decimals with SQLite possible.
-  
+
   2. In the second step you will be asked to confirm that you are prepared to
      lose the data for the application(s) in question. Say yes; we'll restore
      this data in the third step, of course.
-  
-  3. ``DecimalField`` is not used in any of the apps shipped with Django prior 
+
+  3. ``DecimalField`` is not used in any of the apps shipped with Django prior
      to this change being made, so you do not need to worry about performing
      this procedure for any of the standard Django models.
 
@@ -544,10 +554,13 @@ some kind (e.g. a button).
 ``_()`` is no longer in builtins
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``_()`` is no longer monkeypatched into builtins. If you were previously
-relying on ``_()`` always being present, you should now explicitly import
-``ugettext`` or ``ugettext_lazy``, if appropriate, and alias it to ``_``
-yourself::
+``_()`` (the callable object whose name is a single underscore) is no longer
+monkeypatched into builtins -- that is, it's no longer available magically in
+every module.
+
+If you were previously relying on ``_()`` always being present, you should now
+explicitly import ``ugettext`` or ``ugettext_lazy``, if appropriate, and alias
+it to ``_`` yourself::
 
     from django.utils.translation import ugettext as _
 
@@ -593,17 +606,17 @@ Management commands
 Running management commands from your code
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:mod:`django.core.management`` has been greately refactored.
+:mod:`django.core.management`` has been greatly refactored.
 
-Calls to management services in your code will now need to use
+Calls to management services in your code now need to use
 ``call_command``. For example, if you have some test code that calls flush and
 load_data::
 
       from django.core import management
       management.flush(verbosity=0, interactive=False)
       management.load_data(['test_data'], verbosity=0)
 
-You will need to change this code to read::
+...you'll need to change this code to read::
 
       from django.core import management
       management.call_command('flush', verbosity=0, interactive=False)
@@ -619,7 +632,7 @@ options. So:
 
       $ django-admin.py --settings=foo.bar runserver
 
-no longer works, and must be changed to:
+...no longer works and should be changed to:
 
 .. code-block:: bash
 
@@ -631,7 +644,7 @@ Syndication
 ``Feed.__init__`` has changed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``__init__()`` parameters in in syndication framework's ``Feed`` class now
+The ``__init__()`` parameters in the syndication framework's ``Feed`` class now
 take an ``HttpRequest`` object as its second parameter, instead of the feed's
 URL. This allows the syndication framework to work without requiring the sites
 framework. This only affects code that subclass ``Feed`` and overrides the
@@ -652,7 +665,7 @@ To update your code:
      1. Use :class:`django.utils.datastructures.SortedDict` wherever you were
         using ``django.newforms.forms.SortedDictFromList``.
 
-     2. Since :meth:`django.utils.datastructures.SortedDict.copy` return a
+     2. Because :meth:`django.utils.datastructures.SortedDict.copy` returns a
         deepcopy as ``SortedDictFromList`` method did, you will need to update
         your code if you were relying on a deepcopy. Do this by using
         ``copy.deepcopy`` directly.