anchor.diff:  
   A typical web service will expose some number of resources; under Rook this means mapping a number of namespaces.
   
  -The {api}/io.aviso.rook.html#var-namespace-handler[+namespace-handler+] function is the easy way to do this mapping. It combines +compojure.core/context+ with Rook's
  -+wrap-namespace+ (which identifies the function to be invoked within the namespace) and +default-rook-pipeline+.
  -
  -----
  -(routes
  -  (namespace-handler "/users" 'org.example.resources.users)
  -  (namespace-handler "/orders" 'org.example.resources.orders))
  +The {api}/io.aviso.rook.html#var-namespace-handler[+namespace-handler+] function is the easy way to do this mapping.
  +
  +----
  +(namespace-handler
  +  [["users"] 'org.example.resources.users]
  +  [["orders"] 'org.example.resources.orders])
   ----
   
   IMPORTANT: Rook will +require+ the namespace if it has not already been previously loaded into Clojure.
   
  -Remember that the way +context+ works is to match and strip off the prefix, so an incoming GET request for +/users/232+
  -will be matched as context +/users+; Rook will then identify function +org.example.resources.users/show+ with path +/:id+;
  -ultimately invoking the function with the _string_ value +232+ for the +id+ parameter.
  -
  -In more complicated circumstances, you may have resources in a parent-child relationship. For example, if you were modeling
  -_hotels_ which contain _rooms_, you might want to access the list of rooms for a particular
  -hotel with the URL +/hotels/123/rooms/237+:
  -
  -----
  -(routes
  -  (namespace-handler "/hotels 'org.example.resources.hotels
  -    (routes
  -       (namespace-handler "/:hotel-id/rooms" 'org.example.resources.rooms)
  -       default-rook-pipeline)))
  -----
  -
  -In this example, the first +namespace-handler+ call will match any URL that starts with +/hotels+. Since that
  -may be a match for the hotels resource itself, or rooms within a specific hotel, the handler for the namespace
  -can't simply be +default-rook-pipeline+; instead it is a new route containing a namespace handler, and the
  -+default-rook-pipeline+ for the +org.example.resources.hotels+ namespace.
  -
  -The nested route matches the +:hotel-id+ symbol from the path; this will be resolved to argument +hotel-id+ in any
  -resource handler function that is invoked in the +rooms+ namespace.
  -
  -It is important that the +default-rook-pipeline+ both be present, and come _last_.
  -
  -If it is missing, then requests for the +/hotels+ URL will be identified by the middleware, but will never be invoked.
  -
  -If it is present, but comes before the nested namespaces, then a conflict will occur: URLs that should match against
  -the +rooms+ resource will also match against the +hotels+ resource, and since the +default-rook-pipeline+ for the
  -+hotels+ resource is executed first (incorrectly), it will invoke a resource handler function from the +hotels+ namespace.
  -
  -The namespace middleware always invokes its delegate handler (the request handling function it wraps around), _even when no function has been identified_.
  -This seems counter-intuitive, but makes sense in the context of the nested resources: for a particular request
  -the +hotels+ namespace may not have a corresponding function to invoke, but the nested +rooms+ namespace may have
  -a matching function.
  -
  -Also, in the nested resource scenario, the function to invoke may be identified in an outer context, then re-identified,
  -in an inner context, before being invoked.
  -
   == Writing Rook Middleware
   
  -Rook uses the +:rook+ key of the request to store information needed to process requests.
  -With the exception of +:arg-resolvers+, the values are supplied by the the +wrap-namespace+ function.
  +Rook uses the +:rook+ key of the request to store information needed
  +to process requests. Middleware specified in calls to
  ++namespace-handler+ can make use of this information.
   
   +:arg-resolvers+::
   List of argument resolvers that apply to any invoked resource handler functions.
  -+:namespace+::
  -The symbol identifying the namespace containing the matched function.
  -+:function+::
  -The matched function, which will be invoked by +default-rook-pipeline+.
   +:metadata+::
  -The metadata for the matched function. This is the merged metadata of the function and the namespace (if there
  -are collisions, the function takes precedence).
  -
  -Rook middleware that fits between +wrap-namespace+ and +rook-dispatcher+ should check for nested request key +[:rook :function]+ to
  -see if a function has been identified.
  +The metadata for the matched function minus the
  ++:arg-resolvers+ key (as argument resolvers are treated specially by
  +the dispatch machinery). This is the merged metadata of the function
  +and the namespace (if there are collisions, the function takes
  +precedence). This is, notably, where the request schema is found
  +during request processing (see below).
   
   == Validation
   
  
positive.code: The +:path-spec+ contains two values: the keyword for the verb (this may also be the value +:all+) and the path to match.
  
  == Ring Handlers and Middleware
  
  image:rook-sync.png[Rook Processing Diagram]
  
  Rook works within the Ring framework by providing middleware and request handlers, forming a processing pipeline.
  The section marked *namespace-handler*  in the diagram represents a portion of the overall pipeline constructed by
  
negative.code: == Resource Handler Functions
  
  Rook analyzes the public functions of a namespace to determine which functions are invoked and under which circumstances.
  
  The circumstances are a combination of an HTTP verb (GET, POST, etc.)
  and the request path. The Rook representation is your choice of
  ----
  [:get "/foo/:id"]   ; :path-spec key in a handler function's metadata
  ----
  or
  ----
  [:get ["foo" :id]]  ; :route-spec key in a handler function's metadata
  ----
  -- these both catch +GET /foo/123+ with +123+ bound to the path parameter +id+.
  
  Rook applies a naming convention to functions, so simply naming a function with a particular name implies a certain
  path specification.
  