Ollie Rutherfurd committed 893f215

more doc tweaks

Comments (0)

Files changed (1)

-Makes Django URL patterns easier to read and write.
+Making it easier to read and write Django URL patterns.
+By making assumptions, like ``year`` is usually a 4-digit number and
+``id`` 1 or more digits, `django-easyurls` takes much of the repetition
+out of defining URLs, using a syntax that's shorter and easier to read.
 Compare the following:
         url(r'^(?P<year>\d{4})/$', 'archive_year',  info_dict),
-    # using easyurls
+    # use easyurls, and let it generate the regex for you
     from easyurls import regex as p
     urlpatterns += patterns('django.views.generic.date_based',
         url(p('<year>/<month:mon>/<day>/<slug>'), 'object_detail', info_dict),
         url(p('<year>'),                          'archive_year',  info_dict),
-The second is shorter, easier to read and write, and functionally equivalent to
-the first.  Also, note that urls are automatically prefixed with '^', and '/$'
-are automatically appended, if missing (this can be disabled).
+These two sets of URL patterns are functionally equivalent -- the same
+regex is passed to ``url()`` in both cases, but the second is shorter
+and clearer.  Why keep repeating that year is a 4-digit number, month is
+3 letters, and day a 1 or 2 digit number?  Also, since 99% of the
+time one wants the pattern to start with '^', and end with '/$', why
+keep repeating it?  If you don't want them, you can say so.
-easyurls works by defining names for patterns.  By default, the name of
-the captured variable is the name of the pattern.  This can be
-overriden, as is done above where the "mon" pattern is used for "month".
+django-easyurls works by defining names for patterns and generating
+regular expressions for you.  By default, the name of the captured
+variable is the name of the pattern.  This can be overriden, as is done
+above where the "mon" pattern is used for "month", instead of the
+default ``\d{1,2}``.
 Here's a list of the default patterns: