Merge with docrails

1 files changed, 21 insertions, 22 deletions

diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile
index c31307e77f..c26a5cd6ee 100644
--- a/railties/guides/source/routing.textile
+++ b/railties/guides/source/routing.textile
@@ -131,7 +131,7 @@ map.resources :photos
 
 creates seven different routes in your application:
 
-|_.HTTP verb  |_.URL             |_.controller  |_.action   |_.used for|
+|_.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|
@@ -188,7 +188,7 @@ map.resource :geocoder
 
 creates six different routes in your application:
 
-|_.HTTP verb  |_.URL             |_.controller  |_.action   |_.used for|
+|_.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|
@@ -231,7 +231,7 @@ map.resources :photos, :controller => "images"
 
 will recognize incoming URLs containing +photo+ but route the requests to the Images controller:
 
-|_.HTTP verb  |_.URL             |_.controller  |_.action   |_.used for|
+|_.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|
@@ -250,9 +250,9 @@ Rails allows you to group your controllers into namespaces by saving them in fol
 map.resources :adminphotos, :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 +adminphoto_path+ helper, and you follow a link generated with +<%= link_to "show", adminphoto(1) %>+ 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 +<%= link_to "show", {:controller => "photos", :action => "show"} %>+ because Rails will generate the show URL relative to the current URL.
+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 +adminphoto_path+ helper, and you follow a link generated with +&lt;%= link_to "show", adminphoto(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: +<%= link_to "show", {:controller => "/photos", :action => "show"} %>+
+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+ option instead of a path:
 
@@ -304,7 +304,7 @@ map.resources :photos, :as => "images"
 
 will recognize incoming URLs containing +image+ but route the requests to the Photos controller:
 
-|_.HTTP verb  |_.URL             |_.controller  |_.action   |_:used for|
+|_.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|
@@ -330,7 +330,7 @@ This would cause the routing to recognize URLs such as
 /photos/1/change
 </pre>
 
-NOTE: The actual action names aren't changed by this option; the two URLs show would still route to the new and edit actions.
+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:
 
@@ -362,8 +362,10 @@ 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:
 
 <ruby>
-map.resources :photos, :path_prefix => '/photographers/:photographer_id', :name_prefix => 'photographer_'
-map.resources :photos, :path_prefix => '/agencies/:agency_id', :name_prefix => 'agency_'
+map.resources :photos, :path_prefix => '/photographers/:photographer_id',
+  :name_prefix => 'photographer_'
+map.resources :photos, :path_prefix => '/agencies/:agency_id',
+  :name_prefix => 'agency_'
 </ruby>
 
 This combination will give you route helpers such as +photographer_photos_path+ and +agency_edit_photo_path+ to use in your code.
@@ -386,7 +388,7 @@ The +:except+ option specifies a route or list of routes that should _not_ be ge
 map.resources :photos, :except => :destroy
 </ruby>
 
-In this case, all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/_id_+) will be generated.
+In this case, all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/<em>id</em>+) will be generated.
 
 In addition to an action or a list of actions, you can also supply the special symbols +:all+ or +:none+ to the +:only+ and +:except+ options.
 
@@ -414,9 +416,11 @@ map.resources :magazines do |magazine|
 end
 </ruby>
 
+TIP: Further below you'll learn about a convenient shortcut for this construct:<br/>+map.resources :magazines, :has_many => :ads+.
+
 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|
+|_.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|
@@ -491,7 +495,7 @@ However, without the use of +name_prefix => nil+, deeply-nested resources quickl
 
 The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular "article":http://weblog.jamisbuck.org/2007/2/5/nesting-resources by Jamis Buck proposes a rule of thumb for good Rails design:
 
-_Resources should never be nested more than 1 level deep._
+TIP: _Resources should never be nested more than 1 level deep._
 
 h5. Shallow Nesting
 
@@ -612,13 +616,7 @@ map.resources :photos, :new => { :upload => :post }
 
 This will enable Rails to recognize URLs such as +/photos/upload+ using the POST HTTP verb, and route them to the upload action of the Photos controller. It will also create a +upload_photos+ route helper.
 
-TIP: If you want to redefine the verbs accepted by one of the standard actions, you can do so by explicitly mapping that action. For example:
-
-<ruby>
-map.resources :photos, :new => { :new => :any }
-</ruby>
-
-This will allow the new action to be invoked by any request to +photos/new+, no matter what HTTP verb you use.
+TIP: If you want to redefine the verbs accepted by one of the standard actions, you can do so by explicitly mapping that action. For example:<br/>+map.resources :photos, :new => { :new => :any }+<br/>This will allow the new action to be invoked by any request to +photos/new+, no matter what HTTP verb you use.
 
 h5. A Note of Caution
 
@@ -680,10 +678,11 @@ map.connect 'photos/:id', :controller => 'photos', :action => 'show'
 
 With this route, an incoming URL of +/photos/12+ would be dispatched to the +show+ action within the +Photos+ controller.
 
-You an 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 are not explicitly defined elsewhere in the route. For example:
 
 <ruby>
-map.connect 'photos/:id', :controller => 'photos', :action => 'show', :defaults => { :format => 'jpg' }
+map.connect 'photos/:id', :controller => 'photos', :action => '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+.
@@ -899,6 +898,6 @@ h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/3
 
-* October 4, 2008: Added additional detail on specifying verbs for resource member/collection routes , by "Mike Gunderloy":credits.html#mgunderloy
+* October 4, 2008: Added additional detail on specifying verbs for resource member/collection routes, by "Mike Gunderloy":credits.html#mgunderloy
 * September 23, 2008: Added section on namespaced controllers and routing, by "Mike Gunderloy":credits.html#mgunderloy
 * September 10, 2008: initial version by "Mike Gunderloy":credits.html#mgunderloy