Refactored URL mapping documentation.

Reorganized topic document so it introduces concepts form simple to more
complex. Moved reference parts to their own documents.

docs/ref/urls.txt

@@ -0,0 +1,139 @@
+======================================
+``django.conf.urls`` utility functions
+======================================
+
+.. module:: django.conf.urls
+
+.. versionchanged:: 1.4
+    Starting with Django 1.4 functions ``patterns``, ``url``, ``include`` plus
+    the ``handler*`` symbols described below live in the ``django.conf.urls``
+    module.
+
+    Until Django 1.3 they were located in ``django.conf.urls.defaults``. You
+    still can import them from there but it will be removed in Django 1.6.
+
+patterns()
+----------
+
+.. function:: patterns(prefix, pattern_description, ...)
+
+A function that takes a prefix, and an arbitrary number of URL patterns, and
+returns a list of URL patterns in the format Django needs.
+
+The first argument to ``patterns()`` is a string ``prefix``. See
+:ref:`The view prefix <urlpatterns-view-prefix>`.
+
+The remaining arguments should be tuples in this format::
+
+    (regular expression, Python callback function [, optional_dictionary [, optional_name]])
+
+The ``optional_dictionary`` and ``optional_name`` parameters are described in
+:ref:`Passing extra options to view functions <views-extra-options>`.
+
+.. note::
+    Because `patterns()` is a function call, it accepts a maximum of 255
+    arguments (URL patterns, in this case). This is a limit for all Python
+    function calls. This is rarely a problem in practice, because you'll
+    typically structure your URL patterns modularly by using `include()`
+    sections. However, on the off-chance you do hit the 255-argument limit,
+    realize that `patterns()` returns a Python list, so you can split up the
+    construction of the list.
+
+    ::
+
+        urlpatterns = patterns('',
+            ...
+            )
+        urlpatterns += patterns('',
+            ...
+            )
+
+    Python lists have unlimited size, so there's no limit to how many URL
+    patterns you can construct. The only limit is that you can only create 254
+    at a time (the 255th argument is the initial prefix argument).
+
+url()
+-----
+
+.. function:: url(regex, view, kwargs=None, name=None, prefix='')
+
+You can use the ``url()`` function, instead of a tuple, as an argument to
+``patterns()``. This is convenient if you want to specify a name without the
+optional extra arguments dictionary. For example::
+
+    urlpatterns = patterns('',
+        url(r'^index/$', index_view, name="main-view"),
+        ...
+    )
+
+This function takes five arguments, most of which are optional::
+
+    url(regex, view, kwargs=None, name=None, prefix='')
+
+See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name``
+parameter is useful.
+
+The ``prefix`` parameter has the same meaning as the first argument to
+``patterns()`` and is only relevant when you're passing a string as the
+``view`` parameter.
+
+include()
+---------
+
+.. function:: include(<module or pattern_list>)
+
+A function that takes a full Python import path to another URLconf module that
+should be "included" in this place.
+
+:func:`include` also accepts as an argument an iterable that returns URL
+patterns.
+
+See :ref:`Including other URLconfs <including-other-urlconfs>`.
+
+handler403
+----------
+
+.. data:: handler403
+
+A callable, or a string representing the full Python import path to the view
+that should be called if the user doesn't have the permissions required to
+access a resource.
+
+By default, this is ``'django.views.defaults.permission_denied'``. That default
+value should suffice.
+
+See the documentation about :ref:`the 403 (HTTP Forbidden) view
+<http_forbidden_view>` for more information.
+
+.. versionadded:: 1.4
+    ``handler403`` is new in Django 1.4.
+
+handler404
+----------
+
+.. data:: handler404
+
+A callable, or a string representing the full Python import path to the view
+that should be called if none of the URL patterns match.
+
+By default, this is ``'django.views.defaults.page_not_found'``. That default
+value should suffice.
+
+See the documentation about :ref:`the 404 (HTTP Not Found) view
+<http_not_found_view>` for more information.
+
+handler500
+----------
+
+.. data:: handler500
+
+A callable, or a string representing the full Python import path to the view
+that should be called in case of server errors. Server errors happen when you
+have runtime errors in view code.
+
+By default, this is ``'django.views.defaults.server_error'``. That default
+value should suffice.
+
+See the documentation about :ref:`the 500 (HTTP Internal Server Error) view
+<http_internal_server_error_view>` for more information.
+