Add route matching docs

Author: mjackson

docs/Glossary.md

@@ -132,7 +132,7 @@ A *route pattern* (or "path") is a string that describes a portion of a URL. Pat
 
   - `:paramName` – matches a URL segment up to the next `/`, `?`, or `#`. The matched string is called a [param](#params)
   - `()` – Wraps a portion of the URL that is optional
-  - `*` – Matches all characters (non-greedy) up to the next character in the pattern, or to the end of the URL if there is none, and creates a `splat` param
+  - `*` – Matches all characters (non-greedy) up to the next character in the pattern, or to the end of the URL if there is none, and creates a `splat` [param](#params)
 
 Route patterns are relative to the pattern of the parent route unless they begin with a `/`, in which case they begin matching at the beginning of the URL.
 

docs/README.md

@@ -2,6 +2,7 @@
 
 - [Introduction](Introduction.md)
 - [Route Configuration](RouteConfiguration.md)
+- [Route Matching](RouteMatching.md)
 - [Dynamic Routing](DynamicRouting.md)
 - [Advanced Usage](AdvancedUsage.md)
 - [Server Rendering](ServerRendering.md)

docs/RouteConfiguration.md

@@ -1,6 +1,6 @@
 ## Route Configuration
 
-Let's start with the simple app from [the introduction](Introduction.md).
+A [route configuration](Glossary.md#routeconfig) is basically a set of instructions that tell a router how to try and [match the URL](RouteMatching.md) and what code to run when it does. To illustrate some of the features available in your route config, let's expand on the simple app from [the introduction](Introduction.md).
 
 ```js
 import React from 'react';
@@ -67,7 +67,7 @@ URL                     | Components
 
 ### Adding an Index
 
-Imagine we'd like to render another component inside of `App` when the URL is `/`. Currently, `this.props.children` is `undefined` in this case. We can use an `<IndexRoute>` for that.
+Imagine we'd like to render another component inside of `App` when the URL is `/`. Currently, `this.props.children` is `undefined` in this case. We can use an `<IndexRoute>` to specify a "default" page.
 
 ```js
 import { IndexRoute } from 'react-router';
@@ -133,6 +133,8 @@ URL                     | Components
 
 The ability to use absolute paths in deeply nested routes gives us complete control over what the URL looks like! We don't have to add more segments to the URL just to get nested UI.
 
+**Note**: Absolute paths may not be used in route config that is [dynamically loaded](DynamicLoading.md).
+
 ### Preserving URLs
 
 But wait just a minute ... we just changed a URL! [That's not cool](http://www.w3.org/Provider/Style/URI.html). Now everyone who had a link to `/inbox/messages/5` has a **broken link**. :(
@@ -159,3 +161,34 @@ React.render((
 ```
 
 Now when someone clicks on that link to `/inbox/messages/5` they'll automatically be redirected to `/messages/5`. We don't hate our users anymore! :highfive:
+
+### Alternate Configuration
+
+Since [route](Glossary.md#route)s are usually nested, it's useful to use a concise nested syntax like [JSX](https://facebook.github.io/jsx/) to describe their relationship to one another. However, you may use an array of [route](Glossary.md#route) objects if you prefer to avoid using JSX.
+
+The route config we've discussed up to this point could also be specified like this:
+
+```js
+var routeConfig = [
+  { path: '/',
+    component: App,
+    indexRoute: { component: Dashboard },
+    childRoutes: [
+      { path: 'about', component: About },
+      { path: 'inbox',
+        component: Inbox,
+        childRoutes: [
+          { path: '/messages/:id', component: Message },
+          { path: 'messages/:id',
+            onEnter: function (nextState, redirectTo) {
+              redirectTo('/messages/' + nextState.params.id);
+            }
+          }
+        ]
+      }
+    ]
+  }
+];
+
+React.render(<Router routes={routeConfig} />, document.body);
+```

docs/RouteMatching.md

@@ -0,0 +1,23 @@
+## Route Matching
+
+A [route](Glossary.md#route) has two attributes that determine whether or not it "matches" the URL: 1) [nesting](#nesting) and 2) its [`path`](#pathsyntax).
+
+### Nesting
+
+React Router uses the concept of nested routes to let you declare nested sets of views that should be rendered when a given URL is invoked. Nested routes are arranged in a tree-like structure. To find a match, React Router traverses the [route config](Glossary.md#routeconfig) depth-first searching for a route that matches the URL. 
+
+### Path Syntax
+
+A route path is [a string pattern](Glossary.md#routepattern) that is used to match a URL (or a portion of one). Route paths are interpreted literally, except for the following special symbols:
+
+  - `:paramName` – matches a URL segment up to the next `/`, `?`, or `#`. The matched string is called a [param](Glossary.md#params)
+  - `()` – Wraps a portion of the URL that is optional
+  - `*` – Matches all characters (non-greedy) up to the next character in the pattern, or to the end of the URL if there is none, and creates a `splat` [param](Glossary.md#params)
+
+```
+<Route path="/hello/:name">         // matches /hello/michael and /hello/ryan
+<Route path="/hello(/:name)">       // matches /hello, /hello/michael, and /hello/ryan
+<Route path="/files/*.*">           // matches /files/hello.jpg and /files/path/to/hello.jpg
+```
+
+If a route uses a relative `path`, it builds upon the accumulated `path` of its ancestors. Nested routes may opt-out of this behavior by [using an absolute `path`](RouteConfiguration.md#decoupling-the-ui-from-the-url).