Ticket #2568: permalink-second-go.diff

docs/model-api.txt

@@ -1680 +1680 @@
 
     <a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
 
-(Yes, we know ``get_absolute_url()`` couples URLs to models, which violates the
-DRY principle, because URLs are defined both in a URLconf and in the model.
-This is a rare case in which we've intentionally violated that principle for
-the sake of convenience. With that said, we're working on an even cleaner way
-of specifying URLs in a more DRY fashion.)
 
+The ``permalink()`` decorator
+-----------------------------
+
+The trouble with the use of ``get_absolute_url()`` above is that hard coding
+parts of your urls couples URLs to models, which violates the DRY principle,
+because URLs are defined both in a URLconf and in the model.
+
+In the development version, you can further decouple your apps using the
+``permalink`` decorator. for example::
+
+    from django.db.models import permalink
+
+    def get_absolute_url(self):
+        return ('people.views.detail', str(self.id))
+    get_absolute_url=permalink(get_absolute_url)
+
+The decorated function does a reverse lookup to calculate the url for the
+object based on the view and parameters returned by the undecorated function,
+and your project / apps' urlconfs.
+
+
 Executing custom SQL
 --------------------