Update the routing guide for style and to add information on new routing features

2 files changed, 391 insertions, 435 deletions

diff --git a/railties/guides/assets/stylesheets/main.css b/railties/guides/assets/stylesheets/main.css
index 7ccae2c87e..bab0b7a9d9 100644
--- a/railties/guides/assets/stylesheets/main.css
+++ b/railties/guides/assets/stylesheets/main.css
@@ -437,7 +437,7 @@ div.code_container, div.important, div.caution, div.warning, div.note, div.info
 /* Remove bottom margin of paragraphs in special boxes, otherwise they get a
 spurious blank area below with the box background. */
 div.important p, div.caution p, div.warning p, div.note p, div.info p {
-    margin-bottom: 0px;
+    margin-bottom: 1em;
 }
 
 /* Edge Badge
diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile
index cf71e700dc..92d38c4aa7 100644
--- a/railties/guides/source/routing.textile
+++ b/railties/guides/source/routing.textile
@@ -2,180 +2,111 @@ h2. Rails Routing from the Outside In
 
 This guide covers the user-facing features of Rails routing. By referring to this guide, you will be able to:
 
-* Understand the purpose of routing
-* Decipher the code in +routes.rb+
-* Construct your own routes, using either the @match@ method or the preferred RESTful style
-* Identify how a route will map to a controller and action
+* Understand the code in +routes.rb+
+* Construct your own routes, using either the preferred resourceful style or with the @match@ method
+* Identify what parameters to expect an action to receive
+* Automatically create URLs using route helpers
+* Use advanced techniques such as constraints and Rack endpoints
 
 endprologue.
 
-h3. The Dual Purpose of Routing
+h3. The Purpose of the Rails Router
 
-Rails routing is a two-way piece of machinery - rather as if you could turn trees into paper, and then turn paper back into trees. Specifically, it both connects incoming HTTP requests to the code in your application's controllers, and helps you generate URLs without having to hard-code them as strings.
+The Rails router recognizes URLs and dispatches them to a controller's action. It can also generate URLs, avoiding the need to hardcode URL strings in your views.
 
 h4. Connecting URLs to Code
 
-When your Rails application receives an incoming HTTP request, say
+When your Rails application receives an incoming request
 
-<pre>
+<plain>
 GET /patients/17
-</pre>
-
-the routing engine within Rails is the piece of code that dispatches the request to the appropriate spot in your application. In this case, the application would most likely end up running the +show+ action within the +patients+ controller, displaying the details of the patient whose ID is 17.
-
-h4. Generating URLs from Code
+</plain>
 
-Routing also works in reverse. If your application contains this code:
+it asks the router to match it to a controller action. If the first matching route is
 
 <ruby>
-@patient = Patient.find(17)
+match "/patients/:id" => "patients#show"
 </ruby>
 
-<erb>
-<%= link_to "Patient Record", patient_path(@patient) %>
-</erb>
-
-Then the routing engine is the piece that translates that to a link to a URL such as +http://example.com/patients/17+. By using routing in this way, you can reduce the brittleness of your application as compared to one with hard-coded URLs, and make your code easier to read and understand.
-
-NOTE: Patient needs to be declared as a Restful resource for this style of translation to be available.
+the request is dispatched to the +patients+ controller's +show+ action with <tt>{ :id => "17" }</tt> in +params+.
 
-h3. Quick Tour of +routes.rb+
-
-There are two components to routing in Rails: the routing engine itself, which is supplied as part of Rails, and the file +config/routes.rb+, which contains the actual routes that will be used by your application. Learning exactly what you can put in +routes.rb+ is the main topic of this guide, but before we dig in let's get a quick overview.
-
-h4. Processing the File
-
-In format, +routes.rb+ is nothing more than one big block sent to +ApplicationName::Application.routes.draw+. Within this block, you can have comments, but it's likely that most of your content will be individual lines of code - each line being a route in your application. You'll find five main types of content in this file:
-
-* RESTful Routes
-* Named Routes
-* Nested Routes
-* Regular Routes
-* Default Routes
-
-Each of these types of route is covered in more detail later in this guide.
-
-The +routes.rb+ file is processed from top to bottom when a request comes in. The request will be dispatched to the first matching route, and then proceeds to the next. If there is no matching route, then Rails returns HTTP status 404 to the caller.
-
-h4. RESTful Routes
-
-RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information with a single declaration. A RESTful route looks like this:
-
-<ruby>
-resources :books
-</ruby>
-
-h4(#quick-tour-named-routes). Named Routes
-
-Named routes give you very readable links in your code, as well as handling incoming requests. Here's a typical named route:
-
-<ruby>
-match 'login' => 'sessions#new', :as => 'login'
-</ruby>
+h4. Generating URLs from Code
 
-If you're coming from Rails 2, this route will be equivalent to:
+You can also generate routes. If your application contains this code:
 
 <ruby>
-map.login '/login', :controller => 'sessions', :action => 'new'
+@patient = Patient.find(17)
 </ruby>
 
-You will also notice that +sessions#new+ is a shorthand for +:controller => 'sessions', :action => 'new'+. By declaring a named route such as this, you can use +login_path+ or +login_url+ in your controllers and views to generate the URLs for this route. A RESTful generates named routes without the need to explicitly generate a named route via +as+ key.
+<erb>
+<%= link_to "Patient Record", patients_path(@patient.id) %>
+</erb>
 
-h4. Nested Routes
+The router will generate the path +/patients/17+. This reduces the brittleness of your view and makes your code easier to understand.
 
-Nested routes let you declare that one resource is contained within another resource. You'll see later on how this translates to URLs and paths in your code. For example, if your application includes parts, each of which belongs to an assembly, you might have this nested route declaration:
+h3. Resource Routing: the Rails Default
 
-<ruby>
-resources :assemblies do
-  resources :parts
-end
-</ruby>
+Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your +index+, +show+, +new+, +edit+, +create+, +update+ and +destroy+ actions, a resourceful route declares them in a single line of code.
 
-h4(#quick-tour-regular-routes). Regular Routes
+h4. Resources on the Web
 
-In many applications, you'll also see non-RESTful routing, which explicitly connects the parts of a URL to a particular action. For example,
+Browsers request pages from Rails by making a request for a URL using a specific HTTP method, such as +GET+, +POST+, +PUT+ and +DELETE+. Each method is a request to perform an operation on the resource. A resource route maps a number of related request to the actions in a single controller.
 
-<ruby>
-match 'parts/:number' => 'inventory#show'
-</ruby>
+When your Rails application receives an incoming request for
 
-h4. Default Routes
+<plain>
+DELETE /photos/17
+</plain>
 
-The default route is a safety net that catches otherwise-unrouted requests. Many Rails applications will contain this default route:
+it asks the router to map it to a controller action. If the first matching route is
 
 <ruby>
-match ':controller(/:action(/:id(.:format)))'
+resources :photos
 </ruby>
 
-In Rails 3, this route is commented out advising to use RESTful routes as much as possible. So if you're using RESTful routing for everything in your application, you will probably want to leave it like that.
-
-h3. RESTful Routing: the Rails Default
-
-RESTful routing is the current standard for routing in Rails, and it's the one that you should prefer for new applications. It can take a little while to understand how RESTful routing works, but it's worth the effort; your code will be easier to read and you'll be working with Rails, rather than fighting against it, when you use this style of routing.
-
-h4. What is REST?
-
-The foundation of RESTful routing is generally considered to be Roy Fielding's doctoral thesis, "Architectural Styles and the Design of Network-based Software Architectures":http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. Fortunately, you need not read this entire document to understand how REST works in Rails. REST, an acronym for Representational State Transfer, boils down to two main principles for our purposes:
-
-* Using resource identifiers (which, for the purposes of discussion, you can think of as URLs) to represent resources
-* Transferring representations of the state of that resource between system components.
-
-For example, to a Rails application a request such as this:
-
-<pre>
-DELETE /photos/17
-</pre>
-
-would be understood to refer to a photo resource with the ID of 17, and to indicate a desired action - deleting that resource. REST is a natural style for the architecture of web applications, and Rails makes it even more natural by using conventions to shield you from some of the RESTful complexities.
+Rails would dispatch that request to the +destroy+ method on the +photos+ controller with <tt>{ :id => "17" }</tt> in +params+.
 
 h4. CRUD, Verbs, and Actions
 
-In Rails, a RESTful route provides a mapping between HTTP verbs, controller actions, and (implicitly) CRUD operations in a database. A single entry in the routing file, such as
+In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions. By convention, each action also maps to particular CRUD operations in a database. A single entry in the routing file, such as
 
 <ruby>
 resources :photos
 </ruby>
 
-creates seven different routes in your application:
+creates seven different routes in your application, all mapping to the +Photos+ controller:
 
-|_.HTTP verb|_.URL           |_.controller|_.action |_.used for|
-|GET        |/photos         |Photos      |index    |display a list of all photos|
-|GET        |/photos/new     |Photos      |new      |return an HTML form for creating a new photo|
-|POST       |/photos         |Photos      |create   |create a new photo|
-|GET        |/photos/1       |Photos      |show     |display a specific photo|
-|GET        |/photos/1/edit  |Photos      |edit     |return an HTML form for editing a photo|
-|PUT        |/photos/1       |Photos      |update   |update a specific photo|
-|DELETE     |/photos/1       |Photos      |destroy  |delete a specific photo|
-
-For the specific routes (those that reference just a single resource), the identifier for the resource will be available within the corresponding controller action as +params[:id]+.
+|_. Verb |_.URL             |_.action |_.used for|
+|GET     |/photos           |index    |display a list of all photos|
+|GET     |/photos/new       |new      |return an HTML form for creating a new photo|
+|POST    |/photos           |create   |create a new photo|
+|GET     |/photos/:id       |show     |display a specific photo|
+|GET     |/photos/:id/edit  |edit     |return an HTML form for editing a photo|
+|PUT     |/photos/:id       |update   |update a specific photo|
+|DELETE  |/photos/:id       |destroy  |delete a specific photo|
 
 h4. URLs and Paths
 
-Creating a RESTful route will also make available a pile of helpers within your application, something that requires explicit mention otherwise:
+Creating a resourceful route will also expose a number of helpers to the controllers in your application. In the case of +resources :photos+:
 
-* +photos_url+ and +photos_path+ map to the path for the index and create actions
-* +new_photo_url+ and +new_photo_path+ map to the path for the new action
-* +edit_photo_url+ and +edit_photo_path+ map to the path for the edit action
-* +photo_url+ and +photo_path+ map to the path for the show, update, and destroy actions
+* +photos_path+ returns +/photos+
+* +new_photo_path+ returns +/photos/new+
+* +edit_photo_path+ returns +/photos/edit+
+* +photo_path(id)+ returns +/photos/:id+ (for instance, +photo_path(10)+ returns +/photos/10+)
 
-NOTE: Because routing makes use of the HTTP verb as well as the path in the request to dispatch requests, the seven routes generated by a RESTful routing entry only give rise to four pairs of helpers.
+Each of these helpers has a corresponding +_url+ helper (such as +photos_url+) which returns the same path prefixed with the current host, port and path prefix.
 
-In each case, the +_url+ helper generates a string containing the entire URL that the application will understand, while the +_path+ helper generates a string containing the relative path from the root of the application. For example:
-
-<ruby>
-photos_url  # => "http://www.example.com/photos"
-photos_path # => "/photos"
-</ruby>
+NOTE: Because the router uses the HTTP verb and URL to match inbound requests, four URLs map to seven different actions.
 
 h4. Defining Multiple Resources at the Same Time
 
-If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to +resources+:
+If you need to create routes for more than one resource, you can save a bit of typing by defining them all with a single call to +resources+:
 
 <ruby>
 resources :photos, :books, :videos
 </ruby>
 
-This has exactly the same effect as
+This works exactly the same as
 
 <ruby>
 resources :photos
@@ -185,205 +116,91 @@ resources :videos
 
 h4. Singular Resources
 
-You can also apply RESTful routing to singleton resources within your application. In this case, you use +resource+ instead of +resources+ and the route generation is slightly different. For example, a routing entry of
+Sometimes, you have a resource that clients always look up without referencing an ID. A common example, +/profile+ always shows the profile of the currently logged in user. In this case, you can use a singular resource to map +/profile+ (rather than +/profile/:id+) to the +show+ action.
 
 <ruby>
 resource :geocoder
 </ruby>
 
-creates six different routes in your application:
-
-|_.HTTP verb|_.URL           |_.controller|_.action |_.used for|
-|GET        |/geocoder/new   |Geocoders   |new      |return an HTML form for creating the new geocoder|
-|POST       |/geocoder       |Geocoders   |create   |create the new geocoder|
-|GET        |/geocoder       |Geocoders   |show     |display the one and only geocoder resource|
-|GET        |/geocoder/edit  |Geocoders   |edit     |return an HTML form for editing the geocoder|
-|PUT        |/geocoder       |Geocoders   |update   |update the one and only geocoder resource|
-|DELETE     |/geocoder       |Geocoders   |destroy  |delete the geocoder resource|
-
-NOTE: Even though the name of the resource is singular in +routes.rb+, the matching controller is still plural.
-
-A singular RESTful route generates an abbreviated set of helpers:
-
-* +new_geocoder_url+ and +new_geocoder_path+ map to the path for the new action
-* +edit_geocoder_url+ and +edit_geocoder_path+ map to the path for the edit action
-* +geocoder_url+ and +geocoder_path+ map to the path for the create, show, update, and destroy actions
-
-h4. Customizing Resources
+creates six different routes in your application, all mapping to the +Geocoders+ controller:
 
-Although the conventions of RESTful routing are likely to be sufficient for many applications, there are a number of ways to customize the way that RESTful routes work. These options include:
+|_. Verb    |_.URL          |_.action |_.used for|
+|GET        |/geocoder/new  |new      |return an HTML form for creating the geocoder|
+|POST       |/geocoder      |create   |create the new geocoder|
+|GET        |/geocoder      |show     |display the one and only geocoder resource|
+|GET        |/geocoder/edit |edit     |return an HTML form for editing the geocoder|
+|PUT        |/geocoder      |update   |update the one and only geocoder resource|
+|DELETE     |/geocoder      |destroy  |delete the geocoder resource|
 
-* +:controller+
-* +:singular+
-* +:constraints+
-* +:as+
-* +:path_names+
-* +:only+
-* +:except+
+NOTE: Because you might want to use the same controller for a singular route (+/account+) and a plural route (+/accounts/45+), singular resources map to plural controllers.
 
-You can also add additional routes via the +member+ and +collection+ blocks, which are discussed later in this guide.
+A singular resourceful route generates these helpers:
 
-h5. Using +:controller+
+* +new_geocoder_path+ returns +/geocoder/new+
+* +edit_geocoder_path+ returns +/geocoder/edit+
+* +geocoder_path+ returns +/geocoder+
 
-The +:controller+ option lets you use a controller name that is different from the public-facing resource name. For example, this routing entry:
-
-<ruby>
-resources :photos, :controller => "images"
-</ruby>
-
-will recognize incoming URLs containing +photo+ but route the requests to the Images controller:
-
-|_.HTTP verb|_.URL           |_.controller|_.action |_.used for|
-|GET        |/photos         |Images      |index    |display a list of all images|
-|GET        |/photos/new     |Images      |new      |return an HTML form for creating a new image|
-|POST       |/photos         |Images      |create   |create a new image|
-|GET        |/photos/1       |Images      |show     |display a specific image|
-|GET        |/photos/1/edit  |Images      |edit     |return an HTML form for editing an image|
-|PUT        |/photos/1       |Images      |update   |update a specific image|
-|DELETE     |/photos/1       |Images      |destroy  |delete a specific image|
-
-NOTE: The helpers will be generated with the name of the resource, not the name of the controller. So in this case, you'd still get +photos_path+, +new_photo_path+, and so on.
+As with plural resources, the same helpers ending in +_url+ will also include the host, port and path prefix.
 
 h4. Controller Namespaces and Routing
 
-Rails allows you to group your controllers into namespaces by saving them in folders underneath +app/controllers+. The +:controller+ option provides a convenient way to use these routes. For example, you might have a resource whose controller is purely for admin users in the +admin+ folder:
+You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an +Admin::+ namespace. You would place these controllers under the +app/controllers/admin+ directory, and you can group them together in your router:
 
 <ruby>
-resources :photos, :controller => "admin/photos"
-</ruby>
-
-If you use controller namespaces, you need to be aware of a subtlety in the Rails routing code: it always tries to preserve as much of the namespace from the previous request as possible. For example, if you are on a view generated from the +photo_path+ helper, and you follow a link generated with +&lt;%= link_to "show", photo_path(1) %&gt;+ you will end up on the view generated by +admin/photos/show+, but you will also end up in the same place if you have +&lt;%= link_to "show", {:controller => "photos", :action => "show"} %&gt;+ because Rails will generate the show URL relative to the current URL.
-
-TIP: If you want to guarantee that a link goes to a top-level controller, use a preceding slash to anchor the controller name: +&lt;%= link_to "show", {:controller => "/photos", :action => "show"} %&gt;+
-
-You can also specify a controller namespace with the +namespace+ method instead of a path. This can be especially useful when mapping multiple namespaced routes together:
-
-<ruby>
-namespace :admin do
-  resources :photos, :videos
+namespace "admin" do
+  resources :posts, :comments
 end
 </ruby>
 
-That would give you routing for +admin/photos+ and +admin/videos+ controllers. 
-
-The difference between generating routes through +namespace+ and the +:controller+ key is that the +namespace+ will add +admin+ to the generated helpers as well, so the above route generates +admin_photos_path+.
-
-h5. Using +:singular+
-
-If for some reason Rails isn't doing what you want in converting the plural resource name to a singular name in member routes, you can override its judgment with the +:singular+ option:
-
-<ruby>
-resources :teeth, :singular => "tooth"
-</ruby>
-
-TIP: Depending on the other code in your application, you may prefer to add additional rules to the +Inflector+ class instead.
-
-h5. Using +:constraints+
-
-You can use the +:constraints+ option in a RESTful route to impose a format on the implied parameter in routes. For example:
-
-<ruby>
-resources :photos, :constraints => {:id => /[A-Z][A-Z][0-9]+/}
-</ruby>
-
-This declaration constrains the +:id+ parameter to match the supplied regular expression. So, in this case, +/photos/1+ would no longer be recognized by this route, but +/photos/RR27+ would.
-
-h5. Using +:as+
-
-The +:as+ option lets you override the normal naming for the actual generated paths. For example:
-
-<ruby>
-resources :photos, :as => "images"
-</ruby>
-
-will recognize incoming URLs containing +image+ but route the requests to the Photos controller:
-
-|_.HTTP verb|_.URL           |_.controller|_.action |_:used for|
-|GET        |/images         |Photos      |index    |display a list of all photos|
-|GET        |/images/new     |Photos      |new      |return an HTML form for creating a new photo|
-|POST       |/images         |Photos      |create   |create a new photo|
-|GET        |/images/1       |Photos      |show     |display a specific photo|
-|GET        |/images/1/edit  |Photos      |edit     |return an HTML form for editing a photo|
-|PUT        |/images/1       |Photos      |update   |update a specific photo|
-|DELETE     |/images/1       |Photos      |destroy  |delete a specific photo|
+This will create a number of routes for each of the +posts+ and +comments+ controller. For +Admin::PostsController+, Rails will create:
 
-NOTE: The helpers will be generated with the name of the resource, not the path name. So in this case, you'd still get +photos_path+, +new_photo_path+, and so on.
+|_. Verb |_.URL                |_.action |_. helper                  |
+|GET     |/admin/photos        |index    | admin_photos_path         |
+|GET     |/admin/photos/new    |new      | new_admin_photos_path     |
+|POST    |/admin/photos        |create   | admin_photos_path         |
+|GET     |/admin/photos/1      |show     | admin_photo_path(id)      |
+|GET     |/admin/photos/1/edit |edit     | edit_admin_photo_path(id) |
+|PUT     |/admin/photos/1      |update   | admin_photo_path(id)      |
+|DELETE  |/admin/photos/1      |destroy  | admin_photo_path(id)      |
 
-h5. Using +:path_names+
-
-The +:path_names+ option lets you override the automatically-generated "new" and "edit" segments in URLs:
+If you want to route +/photos+ (without the prefix +/admin+) to +Admin::PostsController+, you could use
 
 <ruby>
-resources :photos, :path_names => { :new => 'make', :edit => 'change' }
-</ruby>
-
-This would cause the routing to recognize URLs such as
-
-<pre>
-/photos/make
-/photos/1/change
-</pre>
-
-NOTE: The actual action names aren't changed by this option; the two URLs shown would still route to the new and edit actions.
-
-TIP: If you find yourself wanting to change this option uniformly for all of your routes, you can set a default in your environment:
-
-<ruby>
-config.action_controller.resources_path_names = { :new => 'make', :edit => 'change' }
+scope :module => "admin" do
+  resources :posts, :comments
+end
 </ruby>
 
-h5. Using +:name_prefix+
-
-You can use the :name_prefix option to avoid collisions between routes. This is most useful when you have two resources with the same name that use +:path_prefix+ to map differently. For example:
+or, for a single case
 
 <ruby>
-resources :photos :name_prefix => 'photographer'
+resources :posts, :module => "admin"
 </ruby>
 
-This combination will give you route helpers such as +photographer_photos_path+ to use in your code.
-
-NOTE: You can also use +:name_prefix+ with non-RESTful routes.
-
-h5. Using +:only+ and +:except+
-
-By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option specifies that only certain routes should be generated:
+If you want to route +/admin/photos+ to +PostsController+ (without the +Admin::+ module prefix), you could use
 
 <ruby>
-resources :photos, :only => [:index, :show]
-</ruby>
-
-With this declaration, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the create action) will fail.
-
-The +:except+ option specifies a route or list of routes that should _not_ be generated:
-
-<ruby>
-resources :photos, :except => :destroy
+scope "/admin" do
+  resources :posts, :comments
+end
 </ruby>
 
-In this case, all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/<em>id</em>+) will be generated.
-
-TIP: If your application has many RESTful routes, using +:only+ and +:except+ to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
-
-h5. Changing Path Names for Resources
-
-Using +scope+, we can alter path names generated by resources:
+or, for a single case
 
 <ruby>
-scope(:resources_path_names => { :new => "neu", :edit => "bearbeiten" }) do
-  resources :categories, :path => "kategorien"
-end
+resources :posts, :path => "/admin"
 </ruby>
 
-With +scope+ defined, it now generates routes with customized path names.
+In each of these cases, the named routes remain the same as if you did not use +scope+. In the last case, the following URLs map to +PostsController+:
 
-|_.HTTP verb|_.URL                      |_.controller  |_.action |_:used for|
-|GET        |/kategorien                |Categories    |index    |display a list of all categories|
-|GET        |/kategorien/neu            |Categories    |new      |return an HTML form for creating a new category|
-|POST       |/kategorien                |Categories    |create   |create a new category|
-|GET        |/kategorien/1              |Categories    |show     |display a specific category|
-|GET        |/kategorien/:id/bearbeiten |Categories    |edit     |return an HTML form for editing a category|
-|PUT        |/kategorien/1              |Categories    |update   |update a specific category|
-|DELETE     |/kategorien/1              |Categories    |destroy  |delete a specific category|
+|_. Verb |_.URL         |_.action |_. helper            |
+|GET     |photos        |index    | photos_path         |
+|GET     |photos/new    |new      | photos_path         |
+|POST    |photos        |create   | photos_path         |
+|GET     |photos/1      |show     | photo_path(id)      |
+|GET     |photos/1/edit |edit     | dmin_photo_path(id) |
+|PUT     |photos/1      |update   | photo_path(id)      |
+|DELETE  |photos/1      |destroy  | photo_path(id)      |
 
 h4. Nested Resources
 
@@ -399,7 +216,7 @@ class Ad < ActiveRecord::Base
 end
 </ruby>
 
-Each ad is logically subservient to one magazine. Nested routes allow you to capture this relationship in your routing. In this case, you might include this route declaration:
+Nested routes allow you to capture this relationship in your routing. In this case, you could include this route declaration:
 
 <ruby>
 resources :magazines do
@@ -407,31 +224,19 @@ resources :magazines do
 end
 </ruby>
 
-In addition to the routes for magazines, this declaration will also create routes for ads, each of which requires the specification of a magazine in the URL:
-
-|_.HTTP verb|_.URL                    |_.controller|_.action |_.used for|
-|GET        |/magazines/1/ads         |Ads         |index    |display a list of all ads for a specific magazine|
-|GET        |/magazines/1/ads/new     |Ads         |new      |return an HTML form for creating a new ad belonging to a specific magazine|
-|POST       |/magazines/1/ads         |Ads         |create   |create a new ad belonging to a specific magazine|
-|GET        |/magazines/1/ads/1       |Ads         |show     |display a specific ad belonging to a specific magazine|
-|GET        |/magazines/1/ads/1/edit  |Ads         |edit     |return an HTML form for editing an ad belonging to a specific magazine|
-|PUT        |/magazines/1/ads/1       |Ads         |update   |update a specific ad belonging to a specific magazine|
-|DELETE     |/magazines/1/ads/1       |Ads         |destroy  |delete a specific ad belonging to a specific magazine|
-
+In addition to the routes for magazines, this declaration will also route ads to an +AdsController+. The ad URLs require a magazine:
 
-This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+.
+|_.Verb |_.URL                    |_.action |_.used for|
+|GET    |/magazines/1/ads         |index    |display a list of all ads for a specific magazine|
+|GET    |/magazines/1/ads/new     |new      |return an HTML form for creating a new ad belonging to a specific magazine|
+|POST   |/magazines/1/ads         |create   |create a new ad belonging to a specific magazine|
+|GET    |/magazines/1/ads/1       |show     |display a specific ad belonging to a specific magazine|
+|GET    |/magazines/1/ads/1/edit  |edit     |return an HTML form for editing an ad belonging to a specific magazine|
+|PUT    |/magazines/1/ads/1       |update   |update a specific ad belonging to a specific magazine|
+|DELETE |/magazines/1/ads/1       |destroy  |delete a specific ad belonging to a specific magazine|
 
-h5(#nested-name-prefix). Using +:name_prefix+
-
-The +:name_prefix+ option overrides the automatically-generated prefix in nested route helpers. For example,
-
-<ruby>
-resources :magazines do
-  resources :ads, :name_prefix => 'periodical'
-end
-</ruby>
 
-This will create routing helpers such as +periodical_ads_url+ and +periodical_edit_ad_path+. 
+This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+. These helpers take an instance of Magazine as the first parameter (+magazine_ads_url(@magazine)+).
 
 h5. Limits to Nesting
 
@@ -455,33 +260,9 @@ The corresponding route helper would be +publisher_magazine_photo_url+, requirin
 
 TIP: _Resources should never be nested more than 1 level deep._
 
-h5. Shallow Nesting
+h4. Creating URLs From Objects
 
-The +:shallow+ option provides an elegant solution to the difficulties of deeply-nested routes. If you specify this option at any level of routing, then paths for nested resources which reference a specific member (that is, those with an +:id+ parameter) will not use the parent path prefix or name prefix. To see what this means, consider this set of routes:
-
-<ruby>
-resources :publishers, :shallow => true do
-  resources :magazines do
-    resources :photos
-  end
-end
-</ruby>
-
-This will enable recognition of (among others) these routes:
-
-<pre>
-/publishers/1           ==> publisher_path(1)
-/publishers/1/magazines ==> publisher_magazines_path(1)
-/magazines/2            ==> magazine_path(2)
-/magazines/2/photos     ==> magazines_photos_path(2)
-/photos/3               ==> photo_path(3)
-</pre>
-
-With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with. 
-
-h4. Route Generation from Arrays
-
-In addition to using the generated routing helpers, Rails can also generate RESTful routes from an array of parameters. For example, suppose you have a set of routes generated with these entries in routes.rb:
+In addition to using the routing helpers, Rails can also create URLs from an array of parameters. For example, suppose you have this set of routes:
 
 <ruby>
 resources :magazines do
@@ -489,49 +270,35 @@ resources :magazines do
 end
 </ruby>
 
-Rails will generate helpers such as magazine_ad_path that you can use in building links:
+When using +magazine_ad_path+, you can pass in instances of +Magazine+ and +Ad+ instead of the numeric IDs.
 
-<ruby>
+<erb>
 <%= link_to "Ad details", magazine_ad_path(@magazine, @ad) %>
-</ruby>
-
-Another way to refer to the same route is with an array of objects:
-
-<ruby>
-<%= link_to "Ad details", [@magazine, @ad] %>
-</ruby>
+</erb>
 
-This format is especially useful when you might not know until runtime which of several types of object will be used in a particular link.
+You can also use +url_for+ with a set of objects, and Rails will automatically determine which route you want:
 
-h4. Namespaced Resources
+<erb>
+<%= link_to "Ad details", url_for(@magazine, @ad) %>
+</erb>
 
-It's possible to do some quite complex things by combining +scope+ and +:name_prefix+. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:
+In this case, Rails will see that +@magazine+ is a +Magazine+ and +@ad+ is an +Ad+ and will therefore use the +magazine_ad_path+ helper. In helpers like +link_to+, you can specify just the object in place of the full +url_for+ call:
 
-<ruby>
-scope 'admin' do
-  resources :photos, :name_prefix => "admin", :controller => 'admin/photos'
-  scope 'photos' do
-    resources :tags, :name_prefix => 'admin_photo', :controller => 'admin/photo_tags'
-    resources :ratings, :name_prefix => 'admin_photo', :controller => 'admin/photo_ratings'
-  end
-end
-</ruby>
+<erb>
+<%= link_to "Ad details", [@magazine, @ad] %>
+</erb>
 
-The good news is that if you find yourself using this level of complexity, you can stop. Rails supports _namespaced resources_ to make placing resources in their own folder a snap. Here's the namespaced version of those same three routes:
+If you wanted to link to just a magazine, you could leave out the +Array+:
 
-<ruby>
-namespace :admin do
-  resources :photos do
-    resources :tags, :ratings
-  end
-end
-</ruby>
+<erb>
+<%= link_to "Magazine details", @magazine %>
+</erb>
 
-As you can see, the namespaced version is much more succinct than the one that spells everything out - but it still creates the same routes. For example, you'll get +admin_photos_url+ that expects to find an +Admin::PhotosController+ and that matches +admin/photos+, and +admin_photos_ratings_path+ that matches +/admin/photos/_photo_id_/ratings+, expecting to use +Admin::RatingsController+. Even though you're not specifying +path_prefix+ explicitly, the routing code will calculate the appropriate +path_prefix+ from the route nesting.
+This allows you to treat instances of your models as URLs, and is a key advantage to using the resourceful style.
 
 h4. Adding More RESTful Actions
 
-You are not limited to the seven routes that RESTful routing creates by default. If you like, you may add additional member routes (those which apply to a single instance of the resource), additional new routes (those that apply to creating a new resource), or additional collection routes (those which apply to the collection of resources as a whole).
+You are not limited to the seven routes that RESTful routing creates by default. If you like, you may add additional routes that apply to the collection or individual members of the collection.
 
 h5. Adding Member Routes
 
@@ -545,9 +312,9 @@ resources :photos do
 end
 </ruby>
 
-This will enable Rails to recognize URLs such as +/photos/1/preview+ using the GET HTTP verb, and route them to the preview action of the Photos controller. It will also create the +preview_photo_url+ and +preview_photo_path+ route helpers.
+This will recognize +/photos/1/preview+ with GET, and route to the +preview+ action of  +PhotosController+. It will also create the +preview_photo_url+ and +preview_photo_path+  helpers.
 
-Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +put+, +post+, or +delete+ here. If you don't have multiple +member+ route, you can also passing +:on+ to the routing.
+Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +put+, +post+, or +delete+ here. If you don't have multiple +member+ routes, you can also passing +:on+ to a route.
 
 <ruby>
 resources :photos do
@@ -557,7 +324,7 @@ end
 
 h5. Adding Collection Routes
 
-To add a collection route, use the +:collection+ option:
+To add a route to the collection:
 
 <ruby>
 resources :photos do
@@ -567,9 +334,9 @@ resources :photos do
 end
 </ruby>
 
-This will enable Rails to recognize URLs such as +/photos/search+ using the GET HTTP verb, and route them to the search action of the Photos controller. It will also create the +search_photos_url+ and +search_photos_path+ route helpers.
+This will enable Rails to recognize URLs such as +/photos/search+ with GET, and route  to the +search+ action of +PhotosController+. It will also create the +search_photos_url+ and +search_photos_path+ route helpers.
 
-Just as with member routes, you can passing +:on+ to the routing.
+Just as with member routes, you can pass +:on+ to a route.
 
 <ruby>
 resources :photos do
@@ -577,24 +344,17 @@ resources :photos do
 end
 </ruby>
 
-h5. Adding New Routes
-
-As of writing, Rails 3 has deprecated +:new+ option from routing. You will need to explicit define the route using +match+ method
-
-<ruby>
-resources :photos
-match 'photos/new/upload' => 'photos#upload', :as => 'upload_new_photos'
-</ruby>
-
 h5. A Note of Caution
 
-If you find yourself adding many extra actions to a RESTful route, it's time to stop and ask yourself whether you're disguising the presence of another resource that would be better split off on its own. When the +member+ and +collection+ hashes become a dumping-ground, RESTful routes lose the advantage of easy readability that is one of their strongest points.
+If you find yourself adding many extra actions to a resourceful route, it's time to stop and ask yourself whether you're disguising the presence of another resource.
 
-h3. Regular Routes
+h3. Non-Resourceful Routes
 
-In addition to RESTful routing, Rails supports regular routing - a way to map URLs to controllers and actions. With regular routing, you don't get the masses of routes automatically generated by RESTful routing. Instead, you must set up each route within your application separately.
+In addition to resource routing, Rails has powerful support for routing arbitrary URLs to actions. Here, you don't get groups of routes automatically generated by resourceful routing. Instead, you set up each route within your application separately.
 
-While RESTful routing has become the Rails standard, there are still plenty of places where the simpler regular routing works fine. You can even mix the two styles within a single application. In general, you should prefer RESTful routing _when possible_, because it will make parts of your application easier to write. But there's no need to try to shoehorn every last piece of your application into a RESTful framework if that's not a good fit.
+While you should usually use resourceful routing, there are still many places where the simpler routing is more appropriate. There's no need to try to shoehorn every last piece of your application into a resourceful framework if that's not a good fit.
+
+In particular, simple routing makes it very easy to map legacy URLs to new Rails actions.
 
 h4. Bound Parameters
 
@@ -604,80 +364,121 @@ When you set up a regular route, you supply a series of symbols that Rails maps
 match ':controller(/:action(/:id))'
 </ruby>
 
-If an incoming request of +/photos/show/1+ is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the +show+ action of the +Photos+ controller, and to make the final parameter (1) available as +params[:id]+. This route will also route the incoming request of +/photos+ to PhotosController, since +:action+ and +:id+ are optional parameters, denoted by parenthesis.
+If an incoming request of +/photos/show/1+ is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the +show+ action of the +PhotosController+, and to make the final parameter +"1"+ available as +params[:id]+. This route will also route the incoming request of +/photos+ to +PhotosController+, since +:action+ and +:id+ are optional parameters, denoted by parentheses.
 
-h4. Wildcard Components
+h4. Dynamic Segments
 
-You can set up as many wildcard symbols within a regular route as you like. Anything other than +:controller+ or +:action+ will be available to the matching action as part of the params hash. So, if you set up this route:
+You can set up as many dynamic segments within a regular route as you like. Anything other than +:controller+ or +:action+ will be available to the action as part of +params+. If you set up this route:
 
 <ruby>
 match ':controller/:action/:id/:user_id'
 </ruby>
 
-An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be set to 2.
+An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+.
 
-h4. Static Text
+h4. Static Segments
 
-You can specify static text when creating a route. In this case, the static text is used only for matching the incoming requests:
+You can specify static segments when creating a route.
 
 <ruby>
 match ':controller/:action/:id/with_user/:user_id'
 </ruby>
 
-This route would respond to URLs such as +/photos/show/1/with_user/2+.
+This route would respond to URLs such as +/photos/show/1/with_user/2+. In this case, +params+ would be <tt>{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }</tt>.
 
-h4. Querystring Parameters
+h4. The Query String
 
-Rails routing automatically picks up querystring parameters and makes them available in the +params+ hash. For example, with this route:
+The +params+ will also include any parameters from the query string. For example, with this route:
 
 <ruby>
 match ':controller/:action/:id
 </ruby>
 
-An incoming URL of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be equal to 2.
+An incoming URL of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params+ will be <tt>{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }</tt>.
 
 h4. Defining Defaults
 
-You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply defaults for these two parameters by putting it after +=>+:
+You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply them as defaults:
 
 <ruby>
 match 'photos/:id' => 'photos#show'
 </ruby>
 
-With this route, an incoming URL of +/photos/12+ would be dispatched to the +show+ action within the +Photos+ controller.
+With this route, Rails will match an incoming URL of +/photos/12+ to the +show+ action of  +PhotosController+.
 
-You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:
+You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that you do not specify as dynamic segments. For example:
 
 <ruby>
 match 'photos/:id' => 'photos#show', :defaults => { :format => 'jpg' }
 </ruby>
 
-With this route, an incoming URL of +photos/12+ would be dispatched to the +show+ action within the +Photos+ controller, and +params[:format]+ will be set to +jpg+.
+Rails would match +photos/12+ to the +show+ action of +PhotosController+, and set +params[:format]+ to +"jpg"+.
 
-h4. Named Routes
+h4. Naming Routes
 
-Regular routes need not use the +connect+ method. You can use any other name here to create a _named route_. For example,
+You can specify a name for any route using the +:as+ option.
 
 <ruby>
 match 'logout' => 'sessions#destroy', :as => :logout
 </ruby>
 
-This will do two things. First, requests to +/logout+ will be sent to the +destroy+ action of the +Sessions+ controller. Second, Rails will maintain the +logout_path+ and +logout_url+ helpers for use within your code.
+This will create +logout_path+ and +logout_url+ as named helpers in your application. Calling +logout_path+ will return +/logout+
 
-h4. Route Constraints
+h4. Segment Constraints
 
-You can use the +:constraints+ option to enforce a format for any parameter in a route:
+You can use the +:constraints+ option to enforce a format for a dynamic segment:
 
 <ruby>
 match 'photo/:id' => 'photos#show', :constraints => { :id => /[A-Z]\d{5}/ }
 </ruby>
 
-This route would respond to URLs such as +/photo/A12345+. You can more succinctly express the same route this way:
+This route would match URLs such as +/photo/A12345+. You can more succinctly express the same route this way:
 
 <ruby>
 match 'photo/:id' => 'photos#show', :id => /[A-Z]\d{5}/
 </ruby>
 
+h4. Request-Based Constraints
+
+You can also constrain a route based on any method on the <a href="action_controller_overview.html#the-request-object">Request</a> object that returns a +String+.
+
+You specify a request-based constraint the same way that you specify a segment constraint:
+
+<ruby>
+match "photo", :constraints => {:subdomain => "admin"}
+</ruby>
+
+You can also specify constrains in a block form:
+
+<ruby>
+namespace "admin" do
+  constraints :subdomain => "admin" do
+    resources :photos
+  end
+end
+</ruby>
+
+h4. Advanced Constraints
+
+If you have a more advanced constraint, you can provide an object that responds to +matches?+ that Rails should use. Let's say you wanted to route all users on a blacklist to the +BlacklistController+. You could do:
+
+<ruby>
+class BlacklistConstraint
+  def initialize
+    @ips = Blacklist.retrieve_ips
+  end
+
+  def matches?(request)
+    @ips.include?(request.remote_ip)
+  end
+end
+
+TwitterClone::Application.routes.draw do
+  match "*path" => "blacklist#index", 
+    :constraints => BlacklistConstraint.new
+end
+</ruby>
+
 h4. Route Globbing
 
 Route globbing is a way to specify that a particular parameter should be matched to all the remaining parts of a route. For example
@@ -686,89 +487,244 @@ Route globbing is a way to specify that a particular parameter should be matched
 match 'photo/*other' => 'photos#unknown'
 </ruby>
 
-This route would match +photo/12+ or +/photo/long/path/to/12+ equally well, creating an array of path segments as the value of +params[:other]+.
+This route would match +photo/12+ or +/photo/long/path/to/12+, setting +params[:other]+ to +"12"+ or +"long/path/to/12"+.
+
+h4. Redirection
+
+You can redirect any path to another path using the +redirect+ helper in your router:
+
+<ruby>
+match "/stories" => redirect("/posts")
+</ruby>
+
+You can also reuse dynamic segments from the match in the path to redirect to:
+
+<ruby>
+match "/stories/:name" => redirect("/posts/%{name}")
+</ruby>
+
+You can also provide a block to redirect, which receives the params and (optionally) the request object:
 
-h3. Formats and +respond_to+
+<ruby>
+match "/stories/:name" => redirect {|params| "/posts/#{params[:name].pluralize}" }
+match "/stories" => redirect {|p, req| "/posts/#{req.subdomain}" }
+</ruby>
+
+In all of these cases, if you don't provide the leading host (+http://www.example.com+), Rails will take those details from the current request.
 
-There's one more way in which routing can do different things depending on differences in the incoming HTTP request: by issuing a response that corresponds to what the request specifies that it will accept. In Rails routing, you can control this with the special +:format+ parameter in the route.
+h4. Routing to Rack Applications
 
-For instance, consider the second of the default routes in the boilerplate +routes.rb+ file:
+Instead of a String, like +"posts#index"+, which corresponds to the +index+ action in the +PostsController+, you can specify any <a href="rails_on_rack.html">Rack application</a> as the endpoint for a matcher.
 
 <ruby>
-match ':controller(/:action(/:id(.:format)))'
+match "/application.js" => Sprockets
 </ruby>
 
-This route matches requests such as +/photo/edit/1.xml+ or +/photo/show/2.rss+. Within the appropriate action code, you can issue different responses depending on the requested format:
+As long as +Sprockets+ responds to +call+ and returns a <tt>[status, headers, body]</tt>, the router won't know the difference between the Rack application and an action.
+
+NOTE: For the curious, +"posts#index"+ actually expands out to +PostsController.action(:index)+, which returns a valid Rack application.
+
+h4. Using +root+
+
+You can specify what Rails should route +"/"+ to with the +root+ method:
 
 <ruby>
-respond_to do |format|
-  format.html # return the default template for HTML
-  format.xml { render :xml => @photo.to_xml }
+root :to => 'pages#main'
+</ruby>
+
+You should put the +root+ route at the end of the file.
+
+h3. Customizing Resourceful Routes
+
+While the default routes and helpers generated by +resources :posts+ will usually serve you well, you may want to customize them in some way. Rails allows you to customize virtually any generic part of the resourceful helpers.
+
+h4. Specifying a Controller to Use
+
+The +:controller+ option lets you explicitly specify a controller to use for the resource. For example:
+
+<ruby>
+resources :photos, :controller => "images"
+</ruby>
+
+will recognize incoming URLs beginning with +/photo+ but route to the +Images+ controller:
+
+|_. Verb |_.URL          |_.action |
+|GET     |/photos        |index    |
+|GET     |/photos/new    |new      |
+|POST    |/photos        |create   |
+|GET     |/photos/1      |show     |
+|GET     |/photos/1/edit |edit     |
+|PUT     |/photos/1      |update   |
+|DELETE  |/photos/1      |destroy  |
+
+NOTE: Use +photos_path+, +new_photos_path+, etc. to generate URLs for this resource.
+
+h4. Specifying Constraints
+
+You can use the +:constraints+ option to specify a required format on the implicit +id+. For example:
+
+<ruby>
+resources :photos, :constraints => {:id => /[A-Z][A-Z][0-9]+/}
+</ruby>
+
+This declaration constrains the +:id+ parameter to match the supplied regular expression. So, in this case, the router would no longer match +/photos/1+ to this route. Instead, +/photos/RR27+ would match.
+
+You can specify a single constraint to a apply to a number of routes by using the block form:
+
+<ruby>
+constraints(:id => /[A-Z][A-Z][0-9]+/) do
+  resources :photos
+  resources :accounts
+end
+</ruby>
+
+NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context
+
+h4. Overriding the Named Helpers
+
+The +:as+ option lets you override the normal naming for the named route helpers. For example:
+
+<ruby>
+resources :photos, :as => "images"
+</ruby>
+
+will recognize incoming URLs beginning with +/photos+ and route the requests to +PhotosController+:
+
+|_.HTTP verb|_.URL           |_.action |_.named helper   |
+|GET        |/photos         |index    | images_path_    |
+|GET        |/photos/new     |new      | new_image_path  |
+|POST       |/photos         |create   | images_path     |
+|GET        |/photos/1       |show     | image_path      |
+|GET        |/photos/1/edit  |edit     | edit_image_path |
+|PUT        |/photos/1       |update   | image_path      |
+|DELETE     |/photos/1       |destroy  | image_path      |
+
+h4. Overriding the +new+ and +edit+ Segments
+
+The +:path_names+ option lets you override the automatically-generated "new" and "edit" segments in URLs:
+
+<ruby>
+resources :photos, :path_names => { :new => 'make', :edit => 'change' }
+</ruby>
+
+This would cause the routing to recognize URLs such as
+
+<pre>
+/photos/make
+/photos/1/change
+</pre>
+
+NOTE: The actual action names aren't changed by this option. The two URLs shown would still route to the new and edit actions.
+
+TIP: If you find yourself wanting to change this option uniformly for all of your routes, you can use a scope:
+
+<ruby>
+scope :path_names => { :new => "make" } do
+  # rest of your routes
 end
 </ruby>
 
-h4. Specifying the Format with an HTTP Header
+h4. Overriding the Named Helper Prefix
 
-If there is no +:format+ parameter in the route, Rails will automatically look at the HTTP Accept header to determine the desired format.
+You can use the :name_prefix option to add a prefix to the named route helpers that Rails generates for a route. You can use this option to prevent collisions between routes using a path scope.
 
-h4. Recognized MIME types
+<ruby>
+scope "admin" do
+  resources :photos, :name_prefix => "admin"
+end
 
-By default, Rails recognizes +html+, +text+, +json+, +csv+, +xml+, +rss+, +atom+, and +yaml+ as acceptable response types. If you need types beyond this, you can register them in your environment:
+resources :photos
+</ruby>
+
+This will provide route helpers such as +photographer_photos_path+.
+
+You could specify a name prefix to use for a group of routes in the scope:
 
 <ruby>
-Mime::Type.register "image/jpg", :jpg
+scope "admin", :name_prefix => "admin" do
+  resources :photos, :accounts
+end
+
+resources :photos, :accounts
 </ruby>
 
-h3. The Default Routes
+NOTE: The +namespace+ scope will automatically add a +:name_prefix+ as well as +:module+ and +:path+ prefixes.
+
+h4. Restricting the Routes Created
 
-When you create a new Rails application, +routes.rb+ is initialized with a default route:
+By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option tells Rails to create only the specified routes:
 
 <ruby>
-match ':controller(/:action(/:id(.:format)))'
+resources :photos, :only => [:index, :show]
 </ruby>
 
-These routes provide reasonable defaults for many URLs, if you're not using RESTful routing.
+Now, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the +create+ action) will fail.
+
+The +:except+ option specifies a route or list of routes that Rails should _not_ create:
 
-NOTE: The default routes will make every action of every controller in your application accessible to GET requests. If you've designed your application to make consistent use of RESTful and named routes, you should comment out the default routes to prevent access to your controllers through the wrong verbs. If you've had the default routes enabled during development, though, you need to be sure that you haven't unwittingly depended on them somewhere in your application - otherwise you may find mysterious failures when you disable them.
+<ruby>
+resources :photos, :except => :destroy
+</ruby>
 
-h3. The Empty Route
+In this case, Rails will create all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/:id+).
 
-Don't confuse the default routes with the empty route. The empty route has one specific purpose: to route requests that come in to the root of the web site. For example, if your site is example.com, then requests to +http://example.com+ or +http://example.com/+ will be handled by the empty route.
+TIP: If your application has many RESTful routes, using +:only+ and +:except+ to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
 
-h4. Using +root+
+h4. Translated Paths
 
-The preferred way to set up the empty route is with the +root+ command:
+Using +scope+, we can alter path names generated by resources:
 
 <ruby>
-root :to => 'pages#main'
+scope(:path_names => { :new => "neu", :edit => "bearbeiten" }) do
+  resources :categories, :path => "kategorien"
+end
 </ruby>
 
-The use of the +root+ method tells Rails that this route applies to requests for the root of the site.
+Rails now creates routes to the +CategoriesControlleR+.
 
-Because of the top-down processing of the file, the named route must be specified _before_ the call to +root+.
+|_.HTTP verb|_.URL                      |_.action |
+|GET        |/kategorien                |index    |
+|GET        |/kategorien/neu            |new      |
+|POST       |/kategorien                |create   |
+|GET        |/kategorien/1              |show     |
+|GET        |/kategorien/:id/bearbeiten |edit     |
+|PUT        |/kategorien/1              |update   |
+|DELETE     |/kategorien/1              |destroy  |
 
-h4. Connecting the Empty String
+h4. Overriding the Singular Form
 
-You can also specify an empty route by explicitly connecting the empty string:
+If you want to customize the singular name of the route in the named helpers, you can use the +:singular+ option.
 
 <ruby>
-match '' => 'pages#main'
+resources :teeth, :singular => "tooth"
+</ruby>
+
+TIP: If you want to define the singular form of a word for your entire application, you should add additional rules to the +Inflector+ instead.
+
+h4(#nested-name-prefix). Using +:name_prefix+ in Nested Resources
+
+The +:name_prefix+ option overrides the automatically-generated prefix for the parent resource in nested route helpers. For example,
+
+<ruby>
+resources :magazines do
+  resources :ads, :name_prefix => 'periodical'
+end
 </ruby>
 
-TIP: If the empty route does not seem to be working in your application, make sure that you have deleted the file +public/index.html+ from your Rails tree.
+This will create routing helpers such as +periodical_ads_url+ and +periodical_edit_ad_path+.
 
 h3. Inspecting and Testing Routes
 
-Routing in your application should not be a "black box" that you never open. Rails offers built-in tools for both inspecting and testing routes.
+Rails offers facilities for inspecting and testing your routes.
 
 h4. Seeing Existing Routes with +rake+
 
-If you want a complete list of all of the available routes in your application, run the +rake routes+ command. This will dump all of your routes to the console, in the same order that they appear in +routes.rb+. For each route, you'll see:
+If you want a complete list of all of the available routes in your application, run +rake routes+ command. This will print all of your routes, in the same order that they appear in +routes.rb+. For each route, you'll see:
 
 * The route name (if any)
 * The HTTP verb used (if the route doesn't respond to all verbs)
-* The URL pattern
-* The routing parameters that will be generated by this URL
+* The URL pattern to match
+* The routing parameters for the route
 
 For example, here's a small section of the +rake routes+ output for a RESTful route:
 
@@ -812,7 +768,7 @@ You can supply a +:method+ argument to specify the HTTP verb:
 assert_recognizes({ :controller => "photos", :action => "create" }, { :path => "photos", :method => :post })
 </ruby>
 
-You can also use the RESTful helpers to test recognition of a RESTful route:
+You can also use the resourceful helpers to test recognition of a RESTful route:
 
 <ruby>
 assert_recognizes new_photo_url, { :path => "photos", :method => :post }