--- a/docs/docs/04_content-model/02_routes.md	Wed Sep 07 08:58:41 2016 -0700
+++ b/docs/docs/04_content-model/02_routes.md	Wed Sep 07 22:34:28 2016 -0700
@@ -16,23 +16,42 @@
 
 Each route must define the following settings:
 
-* `url`: That's the pattern to use to figure out where the baked page will go.
-  You obviously need to use _placeholders_ here (things of the form `%blah%`)
-  otherwise all your pages would be overwriting each other -- although PieCrust
-  would warn you about that. The available placeholders depend on the source
-  tied to this route. See the [list of available sources][refsrc] to see what
-  kind of routing information they expose.
+  * `url`: That's the pattern to use to figure out where the baked page will go.
+    You need to use _placeholders_ here (things of the form `%blah%`) otherwise
+    all your pages would have the same URL and would be overwriting each other.
+  
+    The available placeholders depend on the source or generator tied to this
+    route (see below). Refer to the [list of available sources][refsrc] and
+    [generators][refgen] to see what kind of routing information they expose.
 
-* `source` or `generator`: This defines the source or generator that this route
-  is defined for. Only pages originating from the source or generator of that
-  name will have their bake output generated from this route. You can't define
-  both `source` and `generator` -- it needs to be one or the other.
+    You'll notice that some routing parameters are *required*, while others are
+    *optional*. The *required* parameters *must* be used in the URL pattern. The
+    *optional* ones are, well, optional.
+
+  * `source` or `generator`: This defines the source or generator that this
+    route is defined for. Only pages originating from the source or generator of
+    that name will have their bake output generated with this route. You can't
+    define both `source` and `generator` -- it needs to be one or the other.
 
 Optional settings include:
 
-* `page_suffix`: Pages that create _sub-pages_ (_e.g._ when using pagination)
-  will append this suffix to the route. By default, this is `/%num%`. You _must_
-  use the `%num%` placeholder somewhere in this setting.
+  * `page_suffix`: Pages that create _sub-pages_ (_e.g._ when using pagination)
+    will append this suffix to the route. By default, this is `/%num%`. You _must_
+    use the `%num%` placeholder somewhere in this setting.
+
+  * `func`: The name for a *route function* that you can use through the
+    [template engine][tpl]. This is what lets you get a URL when you write
+    {%raw%}`{{pcurl('foo/bar')}}`{%endraw%} (the function name being `pcurl`
+    here) to generate an URL to the `foo/bar.html` page (or something similar).
+    The name is up to you, but when you use it, you'll have to pass parameters
+    in the same order as they appear in the URL pattern.
+    
+    So for instance, if you define a route as `/blog/%year%/%slug%`, and that
+    route has a `func` name of `post_url`, then you would use it as such:
+    `post_url(2016, "some-blog-post")`.
+
+    To know what routing parameters a given source or generator supports, see 
+    the reference documentation for [sources][refsrc] and [generators][refgen].
 
 
 ## Route ordering
@@ -48,5 +67,7 @@
 
 
 
+[tpl]: {{docurl('content/templating')}}
 [refsrc]: {{docurl('reference/sources')}}
+[refgen]: {{docurl('reference/generators')}}
 

--- a/docs/docs/99_reference/03_sources.md	Wed Sep 07 08:58:41 2016 -0700
+++ b/docs/docs/99_reference/03_sources.md	Wed Sep 07 22:34:28 2016 -0700
@@ -23,6 +23,9 @@
       on of the `site/auto_formats` (`.md`, `.textile`), the extension is
       stripped from the slug.
 
+* Required routing parameter:
+    * `slug`
+
 
 ## Auto-configuring source
 
@@ -54,6 +57,9 @@
     * `config`: A page configuration fragment containing the `setting_name` and
       its value extracted from the page's relative path.
 
+* Required routing parameter:
+    * `slug`
+
 
 ## Ordered source
 
@@ -78,6 +84,9 @@
     * `config`: A page configuration fragment containing the `setting_name` and
       its value extracted from the page file's name prefix.
 
+* Required routing parameter:
+    * `slug`
+
 * Notes:
     * A setting called `<setting_name>_trail` will also be created in each
       page's metadata, which contains a list of all the order values starting
@@ -121,6 +130,14 @@
     * `slug`: Just like for the `default` source. This here is the part that
       comes after the date prefix.
 
+* Required routing parameters:
+    * `slug`
+
+* Optional routing parameters:
+    * `year`, `month`, `day`. Works best when those parameters are declared as
+      integers (`%int:year%`) or more precisely `int4` (for `year`) and `int2`
+      (for `month` and `day`) so you get proper `0` padding.
+
 * Notes:
     * To specify the time of day of a blog post, set the `time` setting in the
       page's configuration header.
@@ -148,8 +165,10 @@
       from the first non-blank line in the page file.
 
 * Metadata provided:
-    * Same as for the `default` source.
+    * `slug`: Same as for the `default` source.
     * `config`: The page configuration recipe set in the source configuration,
       with any dynamic settings resolved.
 
+* Required routing parameter:
+    * `slug`