Overhaul the semantics of Request.handlerPath and Request.url.

README.md

 ## Web Server Middleware for Dart
 
 [![Build Status](https://travis-ci.org/dart-lang/shelf.svg?branch=master)](https://travis-ci.org/dart-lang/shelf)
 [![Coverage Status](https://coveralls.io/repos/dart-lang/shelf/badge.svg?branch=master)](https://coveralls.io/r/dart-lang/shelf?branch=travis_coveralls)
 
 ## Introduction
 
 **Shelf** makes it easy to create and compose **web servers** and **parts of web
 servers**. How?
 
@@ skipping 48 matching lines @@
 
 [middleware]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf@id_Middleware
 
 [shelf.Pipeline]:  http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf.Pipeline
 
 Some middleware can also take multiple handlers and call one or more of them for
 each request. For example, a routing middleware might choose which handler to
 call based on the request's URI or HTTP method, while a cascading middleware
 might call each one in sequence until one returns a successful response.
 
+Middleware that routes requests between handlers should be sure to update each
+request's [`handlerPath`][handlerPath] and [`url`][url]. This allows inner
+handlers to know where they are in the application so they can do their own
+routing correctly. This can be easily accomplished using
+[`Request.change()`][change]:
+
+[handlerPath]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf.Request@id_handlerPath
+[url]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf.Request@id_url
+[change]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf.Request@id_change
+
+```dart
+// In an imaginary routing middleware...
+var component = request.url.pathComponents.first;
+var handler = _handlers[component];
+if (handler == null) return new Response.notFound(null);
+
+// Create a new request just like this one but with whatever URL comes after
+// [component] instead.
+return handler(request.change(script: component));
+```
+
 ## Adapters
 
 An adapter is any code that creates [shelf.Request][] objects, passes them to a
 handler, and deals with the resulting [shelf.Response][]. For the most part,
 adapters forward requests from and responses to an underlying HTTP server;
 [shelf_io.serve][] is this sort of adapter. An adapter might also synthesize
 HTTP requests within the browser using `window.location` and `window.history`,
 or it might pipe requests directly from an HTTP client to a Shelf handler.
 
 [shelf_io.serve]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf-io@id_serve
 
 When implementing an adapter, some rules must be followed. The adapter must not
-pass the `url` or `scriptName` parameters to [new shelf.Request][]; it should
+pass the `url` or `handlerPath` parameters to [new shelf.Request][]; it should
 only pass `requestedUri`. If it passes the `context` parameter, all keys must
 begin with the adapter's package name followed by a period. If multiple headers
 with the same name are received, the adapter must collapse them into a single
 header separated by commas as per [RFC 2616 section 4.2][].
 
 [new shelf.Request]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf.Request@id_Request-
 
 [RFC 2616 section 4.2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html
 
 An adapter must handle all errors from the handler, including the handler
@@ skipping 35 matching lines @@
 }
 ```
 
 ## Inspiration
 
 * [Connect](http://www.senchalabs.org/connect/) for NodeJS.
     * Read [this great write-up](http://howtonode.org/connect-it) to understand
       the overall philosophy of all of these models.
 * [Rack](http://rack.github.io/) for Ruby.
 * [WSGI](http://legacy.python.org/dev/peps/pep-3333/) for Python.