Copy edited new docs in docs/model-api.txt from [4535]

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

docs/model-api.txt

@@ -874,8 +874,8 @@ the relationship should work. All are optional:
                              force Django to add the descriptor for the reverse
                              relationship, allowing ``ManyToMany`` relationships to be
                              non-symmetrical.
-			     
+
-    ``db_table``             The name of the table to create for storing the many-to-many 
+    ``db_table``             The name of the table to create for storing the many-to-many
                              data. If this is not provided, Django will assume a default
                              name based upon the names of the two tables being joined.
 
@@ -1272,8 +1272,8 @@ A few special cases to note about ``list_display``:
                   return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
               colored_name.allow_tags = True
 
-    * If the string given is a method of the model that returns True or False 
+    * If the string given is a method of the model that returns True or False
-      Django will display a pretty "on" or "off" icon if you give the method a 
+      Django will display a pretty "on" or "off" icon if you give the method a
       ``boolean`` attribute whose value is ``True``.
 
       Here's a full example model::
@@ -1412,7 +1412,7 @@ This should be set to a list of field names that will be searched whenever
 somebody submits a search query in that text box.
 
 These fields should be some kind of text field, such as ``CharField`` or
-``TextField``. You can also perform a related lookup on a ``ForeignKey`` with 
+``TextField``. You can also perform a related lookup on a ``ForeignKey`` with
 the lookup API "follow" notation::
 
     search_fields = ['foreign_key__related_fieldname']
@@ -1721,20 +1721,19 @@ But this template code is good::
 
     <a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
 
-``permalink``
+The ``permalink`` decorator
--------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-** New in Django development version. **
+**New in Django development version.**
 
 The problem with the way we wrote ``get_absolute_url()`` above is that it
 slightly violates the DRY principle: the URL for this object is defined both
 in the URLConf file and in the model.
 
-You can further decouple your models from the URL configuration using the
+You can further decouple your models from the URLconf using the ``permalink``
-``permalink`` function. This function acts as a decorator and is passed the
+decorator. This decorator is passed the view function and any parameters you
-view function and any parameters you would use for accessing this instance
+would use for accessing this instance directly. Django then works out the
-directly. Django then works out the correct full URL path using the URL
+correct full URL path using the URLconf. For example::
-configuration file. For example::
 
     from django.db.models import permalink
 
@@ -1742,9 +1741,9 @@ configuration file. For example::
         return ('people.views.details', str(self.id))
     get_absolute_url = permalink(get_absolute_url)
 
-In this way, you are tying the model's absolute URL to the view that is used
+In this way, you're tying the model's absolute URL to the view that is used
-to display it, without repeating the URL information anywhere. You still use
+to display it, without repeating the URL information anywhere. You can still
-the ``get_absolute_url`` method in templates, as before.
+use the ``get_absolute_url`` method in templates, as before.
 
 Executing custom SQL
 --------------------