Merge branch 'master' of git://github.com/lifo/docrails

Conflicts:
	activerecord/lib/active_record/transactions.rb

7 files changed, 104 insertions, 134 deletions

diff --git a/railties/guides/source/action_controller_overview.textile b/railties/guides/source/action_controller_overview.textile
index 0d6c66f168..0d6919a205 100644
--- a/railties/guides/source/action_controller_overview.textile
+++ b/railties/guides/source/action_controller_overview.textile
@@ -478,8 +478,6 @@ end
 
 Again, this is not an ideal example for this filter, because it's not run in the scope of the controller but gets the controller passed as an argument. The filter class has a class method +filter+ which gets run before or after the action, depending on if it's a before or after filter. Classes used as around filters can also use the same +filter+ method, which will get run in the same way. The method must +yield+ to execute the action. Alternatively, it can have both a +before+ and an +after+ method that are run before and after the action.
 
-The Rails API documentation has "more information on using filters":http://ap.rubyonrails.org/classes/ActionController/Filters/ClassMethods.html.
-
 h3. Verification
 
 Verifications make sure certain criteria are met in order for a controller or action to run. They can specify that a certain key (or several keys in the form of an array) is present in the +params+, +session+ or +flash+ hashes or that a certain HTTP method was used or that the request was made using +XMLHttpRequest+ (Ajax). The default action taken when these criteria are not met is to render a 400 Bad Request response, but you can customize this by specifying a redirect URL or rendering something else and you can also add flash messages and HTTP headers to the response. It is described in the "API documentation":http://ap.rubyonrails.org/classes/ActionController/Verification/ClassMethods.html as "essentially a special kind of before_filter".
diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index e41b5fb606..b9ad7ccbd2 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -450,7 +450,7 @@ SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You
 For example:
 
 <ruby>
-Order.group("date(created_at)".having("created_at > ?", 1.month.ago)
+Order.group("date(created_at)").having("created_at > ?", 1.month.ago)
 </ruby>
 
 The SQL that would be executed would be something like this:
diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile
index acd105c622..11ce3a5003 100644
--- a/railties/guides/source/command_line.textile
+++ b/railties/guides/source/command_line.textile
@@ -197,6 +197,8 @@ Examples:
         Creates a Post model with a string title, text body, and published flag.
 </shell>
 
+NOTE: For a list of available field types, refer to the "API documentation":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html#method-i-column for the column method for the +TableDefinition+ class.
+
 But instead of generating a model directly (which we'll be doing later), let's set up a scaffold. A *scaffold* in Rails is a full set of model, database migration for that model, controller to manipulate it, views to view and manipulate the data, and a test suite for each of the above.
 
 We will set up a simple resource called "HighScore" that will keep track of our highest score on video games we play.
diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile
index afafabd1e9..44f7a61a77 100644
--- a/railties/guides/source/configuring.textile
+++ b/railties/guides/source/configuring.textile
@@ -73,7 +73,7 @@ h4. Rails General Configuration
 
 * +config.dependency_loading+ enables or disables dependency loading during the request cycle. Setting dependency_loading to _true_ will allow new classes to be loaded during a request and setting it to _false_ will disable this behavior. Can also be enabled with +threadsafe!+.
 
-* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. All elements of this array must also be in +load_paths+.
+* +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application. All elements of this array must also be in +load_paths+.
 
 * +config.encoding+ sets up the application-wide encoding. Defaults to UTF-8.
 
@@ -101,6 +101,14 @@ h4. Rails General Configuration
 
 * +config.serve_static_assets+ configures Rails to serve static assets. Defaults to _true_, but in the production environment is turned off. The server software used to run the application should be used to serve the assets instead.
 
+* +config.session_store+ is usually set up in +config/initializers/session_store.rb+ and specifies what class to use to store the session. Custom session stores can be specified like so:
+
+<ruby>
+  config.session_store = :my_custom_store
+</ruby>
+
+This custom store must be defined as +ActionDispatch::Session::MyCustomStore+.
+
 * +config.threadsafe!+ enables +allow_concurrency+, +cache_classes+, +dependency_loading+ and +preload_frameworks+ to make the application threadsafe.
 
 WARNING: Threadsafe operation is incompatible with the normal workings of development mode Rails. In particular, automatic dependency loading and class reloading are automatically disabled when you call +config.threadsafe!+.
@@ -379,9 +387,13 @@ h3. Initialization events
 Rails has 5 initialization events which can be hooked into (listed in order that they are ran):
 
 * +before_configuration+: This is run as soon as the application constant inherits from +Rails::Application+. The +config+ calls are evaluated before this happens.
+
 * +before_initialize+: This is run directly before the initialization process of the application occurs with the +:bootstrap_hook+ initializer near the beginning of the Rails initialization process.
+
 * +to_prepare+: Run after the initializers are ran for all Railties (including the application itself), but before eager loading and the middleware stack is built. 
+
 * +before_eager_load+: This is run directly before eager loading occurs, which is the default behaviour for the _production_ environment and not for the +development+ enviroment.
+
 * +after_initialize+: Run directly after the initialization of the application, but before the application initializers are run.
 
 
@@ -407,173 +419,125 @@ The block's argument of the +initialize+ is the instance of the application itse
 
 Because +Rails::Application+ inherits from +Rails::Railtie+ (indirectly), you can use the +initializer+ method in +config/application.rb+ to define initializers for the application.
 
-Below is a comprehensive list of all the initializers found in Rails in the order that they are defined (and therefore run in, unless otherwise stated).
+h4. Initializers
 
-h4. +load_environment_hook+
+Below is a comprehensive list of all the initializers found in Rails in the order that they are defined (and therefore run in, unless otherwise stated).
 
+*+load_environment_hook+*
 Serves as a placeholder so that +:load_environment_config+ can be defined to run before it.
 
-h4. +load_active_support+
-
-Requires +active_support/dependencies+ which sets up the basis for Active Support. Optionally requires +active_support/all+ if +config.active_support.bare+ is un-truthful, which is the default.
-
-h4. +preload_frameworks+
-
-Will load all autoload dependencies of Rails automatically if +config.preload_frameworks+ is +true+ or "truthful". By default this configuration option is disabled. In Rails, when internal classes are referenced for the first time they are autoloaded. +:preload_frameworks+ loads all of this at once on initialization.
-
-h4. +initialize_logger+
-
-Initializes the logger (an +ActiveSupport::BufferedLogger+ object) for the application and makes it accessible at +Rails.logger+, providing that there's no initializer inserted before this point that has defined +Rails.logger+.
-
-h4. +initialize_cache+
-
-If +RAILS_CACHE+ isn't yet set, initializes the cache by referencing the value in +config.cache_store+ and stores the outcome as +RAILS_CACHE+. If this object responds to the +middleware+ method, its middleware is inserted before +Rack::Runtime+ in the middleware stack.
-
-h4. +set_clear_dependencies_hook+
-
-Provides a hook for +active_record.set_dispatch_hooks+ to use, which will run before this initializer.
+*+load_active_support+* Requires +active_support/dependencies+ which sets up the basis for Active Support. Optionally requires +active_support/all+ if +config.active_support.bare+ is un-truthful, which is the default.
 
-This initializer -- which runs only if +cache_classes+ is set to +false+ -- uses +ActionDispatch::Callbacks.after+ to remove the constants which have been referenced during the request from the object space so that they will be reloaded during the following request.
+*+preload_frameworks+* Will load all autoload dependencies of Rails automatically if +config.preload_frameworks+ is +true+ or "truthful". By default this configuration option is disabled. In Rails, when internal classes are referenced for the first time they are autoloaded. +:preload_frameworks+ loads all of this at once on initialization.
 
-h4. +initialize_dependency_mechanism+
+*+initialize_logger+* Initializes the logger (an +ActiveSupport::BufferedLogger+ object) for the application and makes it accessible at +Rails.logger+, providing that there's no initializer inserted before this point that has defined +Rails.logger+.
 
-If +config.cache_classes+ is set to +true+, configures +ActiveSupport::Dependencies.mechanism+ to +require+ dependencies rather than +load+ them.
+*+initialize_cache+* If +RAILS_CACHE+ isn't yet set, initializes the cache by referencing the value in +config.cache_store+ and stores the outcome as +RAILS_CACHE+. If this object responds to the +middleware+ method, its middleware is inserted before +Rack::Runtime+ in the middleware stack.
 
-h4. +bootstrap_hook+
+*+set_clear_dependencies_hook+* Provides a hook for +active_record.set_dispatch_hooks+ to use, which will run before this initializer. This initializer -- which runs only if +cache_classes+ is set to +false+ -- uses +ActionDispatch::Callbacks.after+ to remove the constants which have been referenced during the request from the object space so that they will be reloaded during the following request.
 
-Runs all configured +before_initialize+ blocks.
+*+initialize_dependency_mechanism+* If +config.cache_classes+ is set to +true+, configures +ActiveSupport::Dependencies.mechanism+ to +require+ dependencies rather than +load+ them.
 
-h4. +i18n.callbacks+
+*+bootstrap_hook+* Runs all configured +before_initialize+ blocks.
 
-In the development environment, sets up a +to_prepare+ callback which will call +I18n.reload!+ if any of the locales have changed since the last request. In production mode this callback will only run on the first request.
+*+i18n.callbacks+* In the development environment, sets up a +to_prepare+ callback which will call +I18n.reload!+ if any of the locales have changed since the last request. In production mode this callback will only run on the first request.
 
-h4. +active_support.initialize_whiny_nils+
+*+active_support.initialize_whiny_nils+* Will require +active_support/whiny_nil+ if +config.whiny_nil+ is set to +true+. This file will output errors such as:
 
-Will require +active_support/whiny_nil+ if +config.whiny_nil+ is set to +true+. This file will output errors such as:
-
-<text>
+<plain>
   Called id for nil, which would mistakenly be 4 -- if you really wanted the id of nil, use object_id
-</text>
+</plain>
 
 And:
 
-<text>
-  You have a nil object when you didn't expect it!
-  You might have expected an instance of Array.
-  The error occurred while evaluating nil.each
-</text>
-
-h4. +active_support.deprecation_behavior+
-
-Sets up deprecation reporting for environments, defaulting to +log+ for development, +notify+ for production and +stderr+ for test. If a value isn't set for +config.active_support.deprecation+ then this initializer will prompt the user to configure this line in the current environment's +config/environments+ file.
-
-h4. +active_support.initialize_time_zone+
-
-Sets the default time zone for the application based off the +config.time_zone+ setting, which defaults to "UTC".
-
-h4. +action_dispatch.configure+
-
-Configures the +ActionDispatch::Http::URL.tld_length+ to be set to the value of +config.action_dispatch.tld_length+.
-
-h4. +action_view.cache_asset_ids+
-
-Will set +ActionView::Helpers::AssetTagHelper::AssetPaths.cache_asset_ids+ to +false+ when Active Support loads, but only if +config.cache_classes+ is too.
-
-h4. +action_view.javascript_expansions+
+<plain>
+You have a nil object when you didn't expect it!
+You might have expected an instance of Array.
+The error occurred while evaluating nil.each
+</plain>
 
-Registers the expansions set up by +config.action_view.javascript_expansions+ and +config.action_view.stylesheet_expansions+ to be recognised by Action View and therefore usable in the views.
+*+active_support.deprecation_behavior+* Sets up deprecation reporting for environments, defaulting to +log+ for development, +notify+ for production and +stderr+ for test. If a value isn't set for +config.active_support.deprecation+ then this initializer will prompt the user to configure this line in the current environment's +config/environments+ file.
 
-h4. +action_view.set_configs+
+*+active_support.initialize_time_zone+* Sets the default time zone for the application based off the +config.time_zone+ setting, which defaults to "UTC".
 
-Sets up Action View by using the settings in +config.action_view+ by +send+'ing the method names as setters to +ActionView::Base+ and passing the values through.
+*+action_dispatch.configure+* Configures the +ActionDispatch::Http::URL.tld_length+ to be set to the value of +config.action_dispatch.tld_length+.
 
-h4. +action_controller.logger+
+*+action_view.cache_asset_ids+* Will set +ActionView::Helpers::AssetTagHelper::AssetPaths.cache_asset_ids+ to +false+ when Active Support loads, but only if +config.cache_classes+ is too.
 
-Sets +ActionController::Base.logger+ -- if it's not already set --  to +Rails.logger+.
+*+action_view.javascript_expansions+* Registers the expansions set up by +config.action_view.javascript_expansions+ and +config.action_view.stylesheet_expansions+ to be recognised by Action View and therefore usable in the views.
 
-h4. +action_controller.initialize_framework_caches+
+*+action_view.set_configs+* Sets up Action View by using the settings in +config.action_view+ by +send+'ing the method names as setters to +ActionView::Base+ and passing the values through.
 
-Sets +ActionController::Base.cache_store+ -- if it's not already set --  to +RAILS_CACHE+.
+*+action_controller.logger+* Sets +ActionController::Base.logger+ -- if it's not already set --  to +Rails.logger+.
 
-h4. +action_controller.set_configs+
+*+action_controller.initialize_framework_caches+* Sets +ActionController::Base.cache_store+ -- if it's not already set --  to +RAILS_CACHE+.
 
-Sets up Action Controller by using the settings in +config.action_controller+ by +send+'ing the method names as setters to +ActionController::Base+ and passing the values through.
+*+action_controller.set_configs+* Sets up Action Controller by using the settings in +config.action_controller+ by +send+'ing the method names as setters to +ActionController::Base+ and passing the values through.
 
-h4. +action_controller.compile_config_methods+
+*+action_controller.compile_config_methods+* Initializes methods for the config settings specified so that they are quicker to access.
 
-Initializes methods for the config settings specified so that they are quicker to access.
+*+active_record.initialize_timezone+* Sets +ActiveRecord::Base.time_zone_aware_attributes+ to true, as well as setting +ActiveRecord::Base.default_timezone+ to UTC. When attributes are read from the database, they will be converted into the time zone specified by +Time.zone+.
 
-h4. +active_record.initialize_timezone+
+*+active_record.logger+* Sets +ActiveRecord::Base.logger+ -- if it's not already set -- to +Rails.logger+.
 
-Sets +ActiveRecord::Base.time_zone_aware_attributes+ to true, as well as setting +ActiveRecord::Base.default_timezone+ to UTC. When attributes are read from the database, they will be converted into the time zone specified by +Time.zone+.
+*+active_record.set_configs+* Sets up Active Record by using the settings in +config.active_record+ by +send+'ing the method names as setters to +ActiveRecord::Base+ and passing the values through.
 
-h4. +active_record.logger+
+*+active_record.initialize_database+* Loads the database configuration (by default) from +config/database.yml+ and establishes a connection for the current environment.
 
-Sets +ActiveRecord::Base.logger+ -- if it's not already set -- to +Rails.logger+.
+*+active_record.log_runtime+* Includes +ActiveRecord::Railties::ControllerRuntime+ which is responsible for reporting the length of time Active Record calls took for the request back to the logger.
 
-h4. +active_record.set_configs+
+*+active_record.set_dispatch_hooks+* If +config.cache_classes+ is set to false, all reloadable connections to the database will be reset.
 
-Sets up Active Record by using the settings in +config.active_record+ by +send+'ing the method names as setters to +ActiveRecord::Base+ and passing the values through.
+*+action_mailer.logger+* Sets +ActionMailer::Base.logger+ -- if it's not already set -- to +Rails.logger+.
 
-h4. +active_record.initialize_database+
+*+action_mailer.set_configs+* Sets up Action Mailer by using the settings in +config.action_mailer+ by +send+'ing the method names as setters to +ActionMailer::Base+ and passing the values through.
 
-Loads the database configuration (by default) from +config/database.yml+ and establishes a connection for the current environment.
+*+action_mailer.compile_config_methods+* Initializes methods for the config settings specified so that they are quicker to access.
 
-h4. +active_record.log_runtime+
+*+active_resource.set_configs+* Sets up Active Resource by using the settings in +config.active_resource+ by +send+'ing the method names as setters to +ActiveResource::Base+ and passing the values through.
 
-Includes +ActiveRecord::Railties::ControllerRuntime+ which is responsible for reporting the length of time Active Record calls took for the request back to the logger.
+*+set_load_path+* This initializer runs before +bootstrap_hook+. Adds the +vendor+, +lib+, all directories of +app+ and any paths specified by +config.load_paths+ to +$LOAD_PATH+.
 
-h4. +active_record.set_dispatch_hooks+
+*+set_autoload_path+* This initializer runs before +bootstrap_hook+. Adds all sub-directories of +app+ and paths specified by +config.autoload_paths+ to +ActiveSupport::Dependencies.autoload_paths+.
 
-If +config.cache_classes+ is set to false, all reloadable connections to the database will be reset.
+*+add_routing_paths+* Loads (by default) all +config/routes.rb+ files (in the application and railties, including engines) and sets up the routes for the application.
 
-h4. +action_mailer.logger+
+*+add_locales+* Adds the files in +config/locales+ (from the application, railties and engines) to +I18n.load_path+, making available the translations in these files.
 
-Sets +ActionMailer::Base.logger+ -- if it's not already set -- to +Rails.logger+.
+*+add_view_paths+* Adds the directory +app/views+ from the application, railties and engines to the lookup path for view files for the application.
 
-h4. +action_mailer.set_configs+
+*+load_environment_config+* Loads the +config/environments+ file for the current environment.
 
-Sets up Action Mailer by using the settings in +config.action_mailer+ by +send+'ing the method names as setters to +ActionMailer::Base+ and passing the values through.
+*+append_asset_paths+* Finds asset paths for the application and all attached railties and keeps a track of the available directories in +config.static_asset_paths+.
 
-h4. +action_mailer.compile_config_methods+
+*+prepend_helpers_path+* Adds the directory +app/helpers+ from the application, railties and engines to the lookup path for helpers for the application.
 
-Initializes methods for the config settings specified so that they are quicker to access.
+*+load_config_initializers+* Loads all Ruby files from +config/initializers+ in the application, railties and engines. The files in this directory can be used to hold configuration settings that should be made after all of the frameworks and plugins are loaded.
 
-h4. +active_resource.set_configs+
-
-Sets up Active Resource by using the settings in +config.active_resource+ by +send+'ing the method names as setters to +ActiveResource::Base+ and passing the values through.
-
-h4. +set_load_path+
-
-This initializer runs before +bootstrap_hook+. Adds the +vendor+, +lib+, all directories of +app+ and any paths specified by +config.load_paths+ to +$LOAD_PATH+.
-
-h4. +set_autoload_path+
-
-This initializer runs before +bootstrap_hook+. Adds all sub-directories of +app+ and paths specified by +config.autoload_paths+ to +ActiveSupport::Dependencies.autoload_paths+.
+NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the +initializers+ folder on down.
 
-h4. +add_routing_paths+
+TIP: If you have any ordering dependency in your initializers, you can control the load order by naming. For example, +01_critical.rb+ will be loaded before +02_normal.rb+.
 
-Loads (by default) all +config/routes.rb+ files (in the application and railties, including engines) and sets up the routes for the application.
+*+engines_blank_point+* Provides a point-in-initialization to hook into if you wish to do anything before engines are loaded. After this point, all railtie and engine initializers are ran.
 
-h4. +add_locales+
+*+add_generator_templates+* Finds templates for generators at +lib/templates+ for the application, railities and engines and adds these to the +config.generators.templates+ setting, which will make the templates available for all generators to reference.
 
-Adds the files in +config/locales+ (from the application, railties and engines) to +I18n.load_path+, making available the translations in these files.
+*+ensure_autoload_once_paths_as_subset+* Ensures that the +config.autoload_once_paths+ only contains paths from +config.autoload_paths+. If it contains extra paths, then an exception will be raised.
 
-h4. +add_view_paths+
+*+add_to_prepare_blocks+* The block for every +config.to_prepare+ call in the application, a railtie or engine is added to the +to_prepare+ callbacks for Action Dispatch which will be ran per request in development, or before the first request in production.
 
-Adds the directory +app/views+ from the application, railties and engines to the lookup path for view files for the application.
+*+add_builtin_route+* If the application is running under the development environment then this will append the route for +rails/info/properties+ to the application routes. This route provides the detailed information such as Rails and Ruby version for +public/index.html+ in a default Rails application.
 
-h4. +load_environment_config+
+*+build_middleware_stack+* Builds the middleware stack for the application, returning an object which has a +call+ method which takes a Rack environment object for the request.
 
+*+eager_load!+* If +config.cache_classes+ is +true+, runs the +config.before_eager_load+ hooks and then calls +eager_load!+ which will load all the Ruby files from +config.eager_load_paths+.
 
+*+finisher_hook+* Provides a hook for after the initialization of process of the application is complete, as well as running all the +config.after_initialize+ blocks for the application, railties and engines.
 
-h4. Initializer files
+*+set_routes_reloader+* Configures Action Dispatch to reload the routes file using +ActionDispatch::Callbacks.to_prepare+.
 
-After loading the framework and any gems and plugins in your application, Rails turns to loading initialization code from +config/initializers+. The files in this directory can be used to hold configuration settings that should be made after all of the frameworks and plugins are loaded.
+*+disable_dependency_loading+*
 
-NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the +initializers+ folder on down.
-
-TIP: If you have any ordering dependency in your initializers, you can control the load order by naming. For example, +01_critical.rb+ will be loaded before +02_normal.rb+.
 
 h3. Changelog
 
diff --git a/railties/guides/source/generators.textile b/railties/guides/source/generators.textile
index a0d744333f..ee3891c43b 100644
--- a/railties/guides/source/generators.textile
+++ b/railties/guides/source/generators.textile
@@ -134,7 +134,7 @@ $ rails generate initializer core_extensions
 
 We can see that now a initializer named core_extensions was created at +config/initializers/core_extensions.rb+ with the contents of our template. That means that +copy_file+ copied a file in our source root to the destination path we gave. The method +file_name+ is automatically created when we inherit from +Rails::Generators::NamedBase+.
 
-The methods that are available for generators are covered in the "final section":#generator_methods of this guide.
+The methods that are available for generators are covered in the "final section":#generator-methods of this guide.
 
 h3. Generators Lookup
 
diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile
index 2f5c88b8c3..bc38e4a6e5 100644
--- a/railties/guides/source/routing.textile
+++ b/railties/guides/source/routing.textile
@@ -3,7 +3,7 @@ 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 code in +routes.rb+
-* Construct your own routes, using either the preferred resourceful style or with the <tt>match</tt> method
+* Construct your own routes, using either the preferred resourceful style or the <tt>match</tt> method
 * Identify what parameters to expect an action to receive
 * Automatically create paths and URLs using route helpers
 * Use advanced techniques such as constraints and Rack endpoints
@@ -50,7 +50,7 @@ Resource routing allows you to quickly declare all of the common routes for a gi
 
 h4. Resources on the Web
 
-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.
+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 requests to actions in a single controller.
 
 When your Rails application receives an incoming request for
 
@@ -470,7 +470,7 @@ This route would match paths such as +/photos/A12345+. You can more succinctly e
 match 'photos/:id' => 'photos#show', :id => /[A-Z]\d{5}/
 </ruby>
 
-+:constraints+ takes regular expression. However note that regexp anchors can't be used within constraints. For example following route will not work:
++:constraints+ takes regular expressions with the restriction that regexp anchors can't be used. For example, the following route will not work:
 
 <ruby>
 match '/:id' => 'posts#show', :constraints => {:id => /^\d/}
@@ -536,7 +536,7 @@ match 'photos/*other' => 'photos#unknown'
 
 This route would match +photos/12+ or +/photos/long/path/to/12+, setting +params[:other]+ to +"12"+ or +"long/path/to/12"+.
 
-Wildcard segments do not need to be last in a route. For example
+Wildcard segments can occur anywhere in a route. For example,
 
 <ruby>
 match 'books/*section/:title' => 'books#show'
@@ -544,7 +544,7 @@ match 'books/*section/:title' => 'books#show'
 
 would match +books/some/section/last-words-a-memoir+ with +params[:section]+ equals +"some/section"+, and +params[:title]+ equals +"last-words-a-memoir"+.
 
-Techincally a route can have even more than one wildard segment indeed, the matcher assigns segments to parameters in an intuitive way. For instance
+Technically a route can have even more than one wildcard segment. The matcher assigns segments to parameters in an intuitive way. For example,
 
 <ruby>
 match '*a/foo/*b' => 'test#index'
@@ -641,7 +641,7 @@ constraints(:id => /[A-Z][A-Z][0-9]+/) do
 end
 </ruby>
 
-NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context
+NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context.
 
 h4. Overriding the Named Helpers
 
@@ -651,7 +651,7 @@ The +:as+ option lets you override the normal naming for the named route helpers
 resources :photos, :as => "images"
 </ruby>
 
-will recognize incoming paths beginning with +/photos+ and route the requests to +PhotosController+:
+will recognize incoming paths beginning with +/photos+ and route the requests to +PhotosController+, but use the value of the :as option to name the helpers.
 
 |_.HTTP verb|_.Path          |_.action |_.named helper   |
 |GET        |/photos         |index    | images_path     |
@@ -679,7 +679,7 @@ This would cause the routing to recognize paths such as
 
 NOTE: The actual action names aren't changed by this option. The two paths 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:
+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
@@ -715,7 +715,7 @@ NOTE: The +namespace+ scope will automatically add +:as+ as well as +:module+ an
 
 h4. Restricting the Routes Created
 
-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:
+By default, Rails creates routes for the seven 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>
 resources :photos, :only => [:index, :show]
@@ -816,7 +816,7 @@ Routes should be included in your testing strategy (just like the rest of your a
 
 h5. The +assert_generates+ Assertion
 
-Use +assert_generates+ to assert that a particular set of options generate a particular path. You can use this with default routes or custom routes
++assert_generates+ asserts that a particular set of options generate a particular path and can be used with default routes or custom routes.
 
 <ruby>
 assert_generates "/photos/1", { :controller => "photos", :action => "show", :id => "1" }
@@ -825,7 +825,7 @@ assert_generates "/about", :controller => "pages", :action => "about"
 
 h5. The +assert_recognizes+ Assertion
 
-The +assert_recognizes+ assertion is the inverse of +assert_generates+. It asserts that Rails recognizes the given path and routes it to a particular spot in your application.
++assert_recognizes+ is the inverse of +assert_generates+. It asserts that a given path is recognized and routes it to a particular spot in your application.
 
 <ruby>
 assert_recognizes({ :controller => "photos", :action => "show", :id => "1" }, "/photos/1")
diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile
index c292a5d83b..733c8a755e 100644
--- a/railties/guides/source/testing.textile
+++ b/railties/guides/source/testing.textile
@@ -182,21 +182,27 @@ class PostTest < ActiveSupport::TestCase
 
 The +PostTest+ class defines a _test case_ because it inherits from +ActiveSupport::TestCase+. +PostTest+ thus has all the methods available from +ActiveSupport::TestCase+. You'll see those methods a little later in this guide.
 
-<ruby>
-def test_truth
-</ruby>
-
 Any method defined within a +Test::Unit+ test case that begins with +test+ (case sensitive) is simply called a test. So, +test_password+, +test_valid_password+ and +testValidPassword+ all are legal test names and are run automatically when the test case is run.
 
-Rails adds a +test+ method that takes a test name and a block. It generates a normal +Test::Unit+ test with method names prefixed with +test_+.
+Rails adds a +test+ method that takes a test name and a block. It generates a normal +Test::Unit+ test with method names prefixed with +test_+. So,
 
 <ruby>
 test "the truth" do
-  # ...
+  assert true
 end
 </ruby>
 
-This makes test names more readable by replacing underscores with regular language.
+acts as if you had written
+
+<ruby>
+def test_the_truth
+  assert true
+end
+</ruby>
+
+only the +test+ macro allows a more readable test name. You can still use regular method definitions though.
+
+NOTE: The method name is generated by replacing spaces with underscores. The result does not need to be a valid Ruby identifier though, the name may contain punctuation characters etc. That's because in Ruby technically any string may be a method name. Odd ones need +define_method+ and +send+ calls, but formally there's no restriction.
 
 <ruby>
 assert true
@@ -256,7 +262,7 @@ This will run all the test methods from the test case. Note that +test_helper.rb
 You can also run a particular test method from the test case by using the +-n+ switch with the +test method name+.
 
 <shell>
-$ ruby -Itest test/unit/post_test.rb -n test_truth
+$ ruby -Itest test/unit/post_test.rb -n test_the_truth
 
 Loaded suite unit/post_test
 Started
@@ -380,7 +386,7 @@ There are a bunch of different types of assertions you can use. Here's the compl
 |+assert( boolean, [msg] )+                                        |Ensures that the object/expression is true.|
 |+assert_equal( obj1, obj2, [msg] )+                               |Ensures that +obj1 == obj2+ is true.|
 |+assert_not_equal( obj1, obj2, [msg] )+                           |Ensures that +obj1 == obj2+ is false.|
-|+assert_same( obj1, obj2, [msg] )+			                       |Ensures that +obj1.equal?(obj2)+ is true.|
+|+assert_same( obj1, obj2, [msg] )+                                |Ensures that +obj1.equal?(obj2)+ is true.|
 |+assert_not_same( obj1, obj2, [msg] )+                            |Ensures that +obj1.equal?(obj2)+ is false.|
 |+assert_nil( obj, [msg] )+                                        |Ensures that +obj.nil?+ is true.|
 |+assert_not_nil( obj, [msg] )+                                    |Ensures that +obj.nil?+ is false.|
@@ -388,7 +394,7 @@ There are a bunch of different types of assertions you can use. Here's the compl
 |+assert_no_match( regexp, string, [msg] )+                        |Ensures that a string doesn't matches the regular expression.|
 |+assert_in_delta( expecting, actual, delta, [msg] )+              |Ensures that the numbers +expecting+ and +actual+ are within +delta+ of each other.|
 |+assert_throws( symbol, [msg] ) { block }+                        |Ensures that the given block throws the symbol.|
-|+assert_raise( exception1, exception2, ... ) { block }+          |Ensures that the given block raises one of the given exceptions.|
+|+assert_raise( exception1, exception2, ... ) { block }+           |Ensures that the given block raises one of the given exceptions.|
 |+assert_nothing_raised( exception1, exception2, ... ) { block }+  |Ensures that the given block doesn't raise one of the given exceptions.|
 |+assert_instance_of( class, obj, [msg] )+                         |Ensures that +obj+ is of the +class+ type.|
 |+assert_kind_of( class, obj, [msg] )+                             |Ensures that +obj+ is or descends from +class+.|