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

* 'master' of git@github.com:lifo/docrails:
  Complete draft of configuring guide; add configuring guide to index; regenerate HTML.
  FIx bad date in Guide changelog.
  Update table syntax in guides to fix deprecation warnings during build.
  Regenarate html

5 files changed, 161 insertions, 121 deletions

diff --git a/railties/doc/guides/source/configuring.txt b/railties/doc/guides/source/configuring.txt
index 945e48cd45..489e205eb1 100644
--- a/railties/doc/guides/source/configuring.txt
+++ b/railties/doc/guides/source/configuring.txt
@@ -6,23 +6,43 @@ This guide covers the configuration and initialization features available to Rai
 * Adjust the behavior of your Rails applications
 * Add additional code to be run at application start time
 
+NOTE: The first edition of this Guide was written from the Rails 2.3 source code. While the information it contains is broadly applicable to Rails 2.2, backwards compatibility is not guaranteed.
+	
 == Locations for Initialization Code
 
-preinitializers
-environment.rb first
-env-specific files
-initializers (load_application_initializers)
-after-initializer
+Rails offers (at least) five good spots to place initialization code:
+	
+* Preinitializers
+* environment.rb
+* Environment-specific Configuration Files
+* Initializers (load_application_initializers)
+* After-Initializers
 
 == Using a Preinitializer
 
-== Initialization Process Settings
+Rails allows you to use a preinitializer to run code before the framework itself is loaded. If you save code in +RAILS_ROOT/config/preinitializer.rb+, that code will be the first thing loaded, before any of the framework components (Active Record, Action Pack, and so on.) If you want to change the behavior of one of the classes that is used in the initialization process, you can do so in this file.
 
 == Configuring Rails Components
 
+In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The +environment.rb+ and environment-specific configuration files (such as +config/environments/production.rb+) allow you to specify the various settings that you want to pass down to all of the components. For example, the default Rails 2.3 +environment.rb+ file includes one setting:
+
+[source, ruby]
+-------------------------------------------------------
+config.time_zone = 'UTC'
+-------------------------------------------------------
+
+This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same +config+ object:
+
+[source, ruby]
+-------------------------------------------------------
+config.active_record.colorize_logging = false
+-------------------------------------------------------
+
+Rails will use that particular setting to configure Active Record.
+
 === Configuring Active Record
 
-+ActiveRecord::Base+ includej a variety of configuration options:
++ActiveRecord::Base+ includes a variety of configuration options:
 
 +logger+ accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed on to any new database connections made. You can retrieve this logger by calling +logger+ on either an ActiveRecord model class or an ActiveRecord model instance. Set to nil to disable logging.
 
@@ -125,21 +145,21 @@ There are a number of settings available on +ActionMailer::Base+:
 
 +smtp_settings+ allows detailed configuration for the +:smtp+ delivery method. It accepts a hash of options, which can include any of these options:
 
-* <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
-* <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it.
-* <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
-* <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
-* <tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
-* <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
+* +:address+ - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
+* +:port+ - On the off chance that your mail server doesn't run on port 25, you can change it.
+* +:domain+ - If you need to specify a HELO domain, you can do it here.
+* +:user_name+ - If your mail server requires authentication, set the username in this setting.
+* +:password+ - If your mail server requires authentication, set the password in this setting.
+* +:authentication+ - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of +:plain+, +:login+, +:cram_md5+.
 
 +sendmail_settings+ allows detailed configuration for the +sendmail+ delivery method. It accepts a hash of options, which can include any of these options:
 
-* <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
-* <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
+* +:location+ - The location of the sendmail executable. Defaults to +/usr/sbin/sendmail+.
+* +:arguments+ - The command line arguments. Defaults to +-i -t+.
 
 +raise_delivery_errors+ specifies whether to raise an error if email delivery cannot be completed. It defaults to +true+.
 
-+delivery_method+ defines the delivery method. The allowed values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, and <tt>:test</tt>.
++delivery_method+ defines the delivery method. The allowed values are +:smtp+ (default), +:sendmail+, and +:test+.
 
 +perform_deliveries+ specifies whether mail will actually be delivered. By default this is +true+; it can be convenient to set it to +false+ for testing.
 
@@ -151,7 +171,7 @@ There are a number of settings available on +ActionMailer::Base+:
 
 +default_implicit_parts_order+ - When a message is built implicitly (i.e. multiple parts are assembled from templates
 which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to
-<tt>["text/html", "text/enriched", "text/plain"]</tt>. Items that appear first in the array have higher priority in the mail client
++["text/html", "text/enriched", "text/plain"]+. Items that appear first in the array have higher priority in the mail client
 and appear last in the mime encoded message.
 
 === Configuring Active Resource
@@ -174,21 +194,46 @@ There are a few configuration options available in Active Support:
 
 Active Model currently has a single configuration setting:
 
-+ActiveModel::Errors.default_error_messages is an array containing all of the validation error messages.
++ActiveModel::Errors.default_error_messages+ is an array containing all of the validation error messages.
 
 == Using Initializers
- organization, controlling load order
+
+After it loads the framework plus any gems and plugins in your application, Rails turns to loading initializers. An initializer is any file of ruby code stored under +/config/initializers+ in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and plugins are loaded.
+
+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+.
 
 == Using an After-Initializer
 
+After-initializers are run (as you might guess) after any initializers are loaded. You can supply an +after_initialize+ block (or an array of such blocks) by setting up +config.after_initialize+ in any of the Rails configuration files:
+
+[source, ruby]
+------------------------------------------------------------------
+config.after_initialize do
+  SomeClass.init
+end
+------------------------------------------------------------------
+
+WARNING: Some parts of your application, notably observers and routing, are not yet set up at the point where the +after_initialize+ block is called.
+
 == Rails Environment Settings
 
-ENV
+Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails:
+
++ENV['RAILS_ENV']+ defines the Rails environment (production, development, test, and so on) that Rails will run under.
+
++ENV['RAILS_RELATIVE_URL_ROOT']+ is used by the routing code to recognize URLs when you deploy your application to a subdirectory.
+
++ENV["RAILS_ASSET_ID"]+ will override the default cache-busting timestamps that Rails generates for downloadable assets.
+
++ENV["RAILS_CACHE_ID"]+ and +ENV["RAILS_APP_VERSION"]+ are used to generate expanded cache keys in Rails' caching code. This allows you to have multiple separate caches from the same application.
+
++ENV['RAILS_GEM_VERSION']+ defines the version of the Rails gems to use, if +RAILS_GEM_VERSION+ is not defined in your +environment.rb+ file.
 
 == Changelog ==
 
 http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/28[Lighthouse ticket]
 
+* January 3, 2009: First reasonably complete draft by link:../authors.html#mgunderloy[Mike Gunderloy]
 * November 5, 2008: Rough outline by link:../authors.html#mgunderloy[Mike Gunderloy]
-
-need to look for def self. ???
diff --git a/railties/doc/guides/source/getting_started_with_rails.txt b/railties/doc/guides/source/getting_started_with_rails.txt
index 58eff9fd3d..7e87c2935e 100644
--- a/railties/doc/guides/source/getting_started_with_rails.txt
+++ b/railties/doc/guides/source/getting_started_with_rails.txt
@@ -163,24 +163,23 @@ $ cd blog
 
 In any case, Rails will create a folder in your working directory called +blog+. Open up that folder and explore its contents. Most of the work in this tutorial will happen in the +app/+ folder, but here's a basic rundown on the function of each folder that Rails creates in a new application by default:
 
-[grid="all"]
-`-----------`-----------------------------------------------------------------------------------------------------------------------------
-File/Folder Purpose
-------------------------------------------------------------------------------------------------------------------------------------------
-+README+		This is a brief instruction manual for your application. Use it to tell others what your application does, how to set it up, and so on.
-+Rakefile+	This file contains batch jobs that can be run from the terminal.
-+app/+		Contains the controllers, models, and views for your application. You'll focus on this folder for the remainder of this guide.
-+config/+		Configure your application's runtime rules, routes, database, and more.
-+db/+			Shows your current database schema, as well as the database migrations. You'll learn about migrations shortly.
-+doc/+		In-depth documentation for your application.
-+lib/+		Extended modules for your application (not covered in this guide).
-+log/+		Application log files.
-+public/+		The only folder seen to the world as-is.  This is where your images, javascript, stylesheets (CSS), and other static files go.
-+script/+		Scripts provided by Rails to do recurring tasks, such as benchmarking, plugin installation, and starting the console or the web server.
-+test/+		Unit tests, fixtures, and other test apparatus. These are covered in link:../testing_rails_applications.html[Testing Rails Applications]
-+tmp/+		Temporary files
-+vendor/+		A place for third-party code. In a typical Rails application, this includes Ruby Gems, the Rails source code (if you install it into your project) and plugins containing additional prepackaged functionality.
--------------------------------------------------------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|File/Folder |Purpose
+|+README+		|This is a brief instruction manual for your application. Use it to tell others what your application does, how to set it up, and so on.
+|+Rakefile+	|This file contains batch jobs that can be run from the terminal.
+|+app/+		|Contains the controllers, models, and views for your application. You'll focus on this folder for the remainder of this guide.
+|+config/+		|Configure your application's runtime rules, routes, database, and more.
+|+db/+			|Shows your current database schema, as well as the database migrations. You'll learn about migrations shortly.
+|+doc/+		|In-depth documentation for your application.
+|+lib/+		|Extended modules for your application (not covered in this guide).
+|+log/+		|Application log files.
+|+public/+		|The only folder seen to the world as-is.  This is where your images, javascript, stylesheets (CSS), and other static files go.
+|+script/+		|Scripts provided by Rails to do recurring tasks, such as benchmarking, plugin installation, and starting the console or the web server.
+|+test/+		|Unit tests, fixtures, and other test apparatus. These are covered in link:../testing_rails_applications.html[Testing Rails Applications]
+|+tmp/+		|Temporary files
+|+vendor/+		|A place for third-party code. In a typical Rails application, this includes Ruby Gems, the Rails source code (if you install it into your project) and plugins containing additional prepackaged functionality.
+|==========================================================================================================
 
 === Configuring a Database
 
@@ -339,25 +338,24 @@ NOTE: While scaffolding will get you up and running quickly, the "one size fits
 
 The scaffold generator will build 13 files in your application, along with some folders, and edit one more. Here's a quick overview of what it creates:
 
-[grid="all"]
-`---------------------------------------------`--------------------------------------------------------------------------------------------
-File                                          Purpose
-------------------------------------------------------------------------------------------------------------------------------------------
-app/models/post.rb                            The Post model
-db/migrate/20081013124235_create_posts.rb     Migration to create the posts table in your database (your name will include a different timestamp)
-app/views/posts/index.html.erb                A view to display an index of all posts 
-app/views/posts/show.html.erb                 A view to display a single post
-app/views/posts/new.html.erb                  A view to create a new post
-app/views/posts/edit.html.erb                 A view to edit an existing post
-app/views/layouts/posts.html.erb              A view to control the overall look and feel of the other posts views
-public/stylesheets/scaffold.css               Cascading style sheet to make the scaffolded views look better
-app/controllers/posts_controller.rb           The Posts controller
-test/functional/posts_controller_test.rb      Functional testing harness for the posts controller
-app/helpers/posts_helper.rb                   Helper functions to be used from the posts views
-config/routes.rb                              Edited to include routing information for posts
-test/fixtures/posts.yml                       Dummy posts for use in testing
-test/unit/post_test.rb                        Unit testing harness for the posts model
--------------------------------------------------------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|File                                          |Purpose
+|app/models/post.rb                            |The Post model
+|db/migrate/20081013124235_create_posts.rb     |Migration to create the posts table in your database (your name will include a different timestamp)
+|app/views/posts/index.html.erb                |A view to display an index of all posts 
+|app/views/posts/show.html.erb                 |A view to display a single post
+|app/views/posts/new.html.erb                  |A view to create a new post
+|app/views/posts/edit.html.erb                 |A view to edit an existing post
+|app/views/layouts/posts.html.erb              |A view to control the overall look and feel of the other posts views
+|public/stylesheets/scaffold.css               |Cascading style sheet to make the scaffolded views look better
+|app/controllers/posts_controller.rb           |The Posts controller
+|test/functional/posts_controller_test.rb      |Functional testing harness for the posts controller
+|app/helpers/posts_helper.rb                   |Helper functions to be used from the posts views
+|config/routes.rb                              |Edited to include routing information for posts
+|test/fixtures/posts.yml                       |Dummy posts for use in testing
+|test/unit/post_test.rb                        |Unit testing harness for the posts model
+|==========================================================================================================
 
 === Running a Migration
 
diff --git a/railties/doc/guides/source/index.txt b/railties/doc/guides/source/index.txt
index 174267d630..cd536873e7 100644
--- a/railties/doc/guides/source/index.txt
+++ b/railties/doc/guides/source/index.txt
@@ -132,8 +132,10 @@ CAUTION: still a basic draft
 This guide introduces you to the basic concepts and features of the Rails I18n API and shows you how to localize your application.
 ***********************************************************
 
-
-
+.link:configuring.html[Configuring Rails Applications]
+***********************************************************
+This guide covers the basic configuration settings for a Rails application.
+***********************************************************
 
 Authors who have contributed to complete guides are listed link:authors.html[here].
 
diff --git a/railties/doc/guides/source/layouts_and_rendering.txt b/railties/doc/guides/source/layouts_and_rendering.txt
index 5834307d7b..23cb83c512 100644
--- a/railties/doc/guides/source/layouts_and_rendering.txt
+++ b/railties/doc/guides/source/layouts_and_rendering.txt
@@ -1028,7 +1028,7 @@ There are several ways of getting similar results with differents sub-templating
 
 http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/15[Lighthouse ticket]
 
-* December 27, 2007: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates
+* December 27, 2008: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates
 * December 27, 2008: Information on new rendering defaults by link:../authors.html#mgunderloy[Mike Gunderloy] 
 * November 9, 2008: Added partial collection counter by link:../authors.html#mgunderloy[Mike Gunderloy] 
 * November 1, 2008: Added +:js+ option for +render+ by link:../authors.html#mgunderloy[Mike Gunderloy] 
diff --git a/railties/doc/guides/source/routing_outside_in.txt b/railties/doc/guides/source/routing_outside_in.txt
index 3f6c80de5c..235832e4f3 100644
--- a/railties/doc/guides/source/routing_outside_in.txt
+++ b/railties/doc/guides/source/routing_outside_in.txt
@@ -132,18 +132,17 @@ map.resources :photos
 
 creates seven different routes in your application:
 
-[grid="all"]
-`----------`---------------`-----------`--------`-------------------------------------------
-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
---------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|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]+.
 
@@ -197,17 +196,16 @@ map.resource :geocoder
 
 creates six different routes in your application:
 
-[grid="all"]
-`----------`---------------`-----------`--------`-------------------------------------------
-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
---------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|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.
 
@@ -245,18 +243,17 @@ map.resources :photos, :controller => "images"
 
 will recognize incoming URLs containing +photo+ but route the requests to the Images controller: 
 
-[grid="all"]
-`----------`---------------`-----------`--------`-------------------------------------------
-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 a image
-PUT        /photos/1       Images      update   update a specific image
-DELETE     /photos/1       Images      destroy  delete a specific image
---------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|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 a 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.
 
@@ -328,18 +325,17 @@ map.resources :photos, :as => "images"
 
 will recognize incoming URLs containing +image+ but route the requests to the Photos controller: 
 
-[grid="all"]
-`----------`---------------`-----------`--------`-------------------------------------------
-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
---------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|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
+|==========================================================================================================
 
 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.
 
@@ -452,18 +448,17 @@ end
 
 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:
 
-[grid="all"]
-`----------`-----------------------`-----------`--------`-------------------------------------------
-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
---------------------------------------------------------------------------------------------
+[options="header"]
+|==========================================================================================================
+|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
+|==========================================================================================================
 
 This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+.