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

@@ -1721,8 +1721,8 @@ But this template code is good::
 
     <a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
 
-``permalink``
+The ``permalink`` decorator
--------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 **New in Django development version.**
 
@@ -1730,11 +1730,10 @@ 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
 --------------------