railties 3.0.0.beta4 → 3.0.0.rc

data/CHANGELOG

@@ -1,25 +1,43 @@
+*Rails 3.0.0 [release candidate] (July 26th, 2010)*
+
+* Application generation: --skip-testunit and --skip-activerecord become --skip-test-unit
+  and --skip-active-record respectively. [fxn]
+
+* Added console to Rails::Railtie as a hook called just after console starts. [José Valim]
+
+* Rails no longer autoload code in lib for application. You need to explicitly require it. [José Valim]
+
+* Rails::LogSubscriber was renamed to ActiveSupport::LogSubscriber [José Valim]
+
+* config.load_(once_)paths in config/application.rb got renamed to config.autoload_(once_)paths. [fxn]
+
+* Abort generation/booting on Ruby 1.9.1. [fxn]
+
+* Made the rails command work even when you're in a subdirectory [Chad Fowler]
+
+
 *Rails 3.0.0 [beta 4] (June 8th, 2010)*
 
-* Version bump
-* Removed Rails Metal [YK & JV].
+* Removed Rails Metal [Yehuda Katz, José Valim].
+
 
 *Rails 3.0.0 [beta 3] (April 13th, 2010)*
 
-* Renamed config.cookie_secret to config.secret_token and pass it as env key. [JV]
+* Renamed config.cookie_secret to config.secret_token and pass it as env key. [José Valim]
 
 
 *Rails 3.0.0 [beta 2] (April 1st, 2010)*
 
-* Session store configuration has changed [YK & CL]
+* Session store configuration has changed [Yehuda Katz, Carl Lerche]
 
     config.session_store :cookie_store, {:key => "..."}
     config.cookie_secret = "fdsfhisdghfidugnfdlg"
 
 * railtie_name and engine_name are deprecated. You can now add any object to
-  the configuration object: config.your_plugin = {} [JV]
+  the configuration object: config.your_plugin = {} [José Valim]
 
 * Added config.generators.templates to provide alternative paths for the generators
-  to look for templates [JV]
+  to look for templates [José Valim]
 
 *Rails 3.0.0 [beta 1] (February 4, 2010)*
 

data/README.rdoc

@@ -0,0 +1,25 @@
+= Railties -- Gluing the Engine to the Rails
+
+Railties is responsible to glue all frameworks together. Overall, it:
+
+* handles all the bootstrapping process for a Rails application;
+
+* manager rails command line interface;
+
+* provides Rails generators core;
+
+
+== Download
+
+The latest version of Railties can be installed with Rubygems:
+
+* gem install railties
+
+Documentation can be found at 
+
+* http://api.rubyonrails.org
+
+
+== License
+
+Railties is released under the MIT license.

data/guides/source/3_0_release_notes.textile

@@ -32,11 +32,11 @@ h3. Upgrading to Rails 3
 
 If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 2.3.5 and make sure your application still runs as expected before attempting to update to Rails 3. Then take heed of the following changes:
 
-h4. Rails 3 requires Ruby 1.8.7+
+h4. Rails 3 requires at least Ruby 1.8.7
 
 Rails 3.0 requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. Rails 3.0 is also compatible with Ruby 1.9.2.
 
-TIP: Note that Ruby 1.8.7 p248 and p249 has marshaling bugs that crash Rails 3.0.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.
+TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails 3.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.
 
 h4. Rails Application object
 
@@ -339,7 +339,9 @@ h5. Other Changes
 * You no longer need to place a minus sign at the end of a ruby interpolation inside an ERb template to remove the trailing carriage return in the HTML output.
 * Added +grouped_collection_select+ helper to Action View.
 * +content_for?+ has been added allowing you to check for the existence of content in a view before rendering.
-
+* passing +:value => nil+ to form helpers will set the field's +value+ attribute to nil as opposed to using the default value
+* passing +:id => nil+ to form helpers will cause those fields to be rendered with no +id+ attribute
+* passing +:alt => nil+ to +image_tag+ will cause the +img+ tag to render with no +alt+ attribute
 
 h3. Active Model
 

data/guides/source/action_controller_overview.textile

@@ -338,6 +338,25 @@ end
 
 Note that while for session values you set the key to +nil+, to delete a cookie value you should use +cookies.delete(:key)+.
 
+h3. Rendering xml and json data
+
+ActionController makes it extremely easy to render +xml+ or +json+ data. If you generate a controller using scaffold then your controller would look something like this.
+
+<ruby>
+class UsersController < ApplicationController
+  def index
+    @users = User.all
+    respond_to do |format|
+      format.html # index.html.erb
+      format.xml  { render :xml => @users}
+    end
+  end
+end
+</ruby>
+
+Notice that in the above case code is <tt>render :xml => @users</tt> and not <tt>render :xml => @users.to_xml</tt>. That is because if the input is not string then rails automatically invokes +to_xml+ . 
+
+
 h3. Filters
 
 Filters are methods that are run before, after or "around" a controller action. 

data/guides/source/active_record_basics.textile

@@ -32,16 +32,16 @@ Active Record gives us several mechanisms, the most important being the ability
 * Validate models before they get persisted to the database
 * Perform database operations in an object-oriented fashion.
 
-h3. Convention over Configuration in ActiveRecord
+h3. Convention over Configuration in Active Record
 
-When writing applications using other programming languages or frameworks, it may be necessary to write a lot of configuration code. This is particularly true for ORM frameworks in general. However, if you follow the conventions adopted by Rails, you'll need to write very little configuration (in some case no configuration at all) when creating ActiveRecord models. The idea is that if you configure your applications in the very same way most of the times then this should be the default way. In this cases, explicit configuration would be needed only in those cases where you can't follow the conventions for any reason.
+When writing applications using other programming languages or frameworks, it may be necessary to write a lot of configuration code. This is particularly true for ORM frameworks in general. However, if you follow the conventions adopted by Rails, you'll need to write very little configuration (in some case no configuration at all) when creating Active Record models. The idea is that if you configure your applications in the very same way most of the times then this should be the default way. In this cases, explicit configuration would be needed only in those cases where you can't follow the conventions for any reason.
 
 h4. Naming Conventions
 
-By default, ActiveRecord uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class +Book+, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the camelCase form, while the table name must contain the words separated by underscores. Examples:
+By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class +Book+, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the camelCase form, while the table name must contain the words separated by underscores. Examples:
 
-* Database Table - Plural with underscores separating words i.e. (book_clubs)
-* Model Class - Singular with the first letter of each word capitalized i.e. (BookClub)
+* Database Table - Plural with underscores separating words (e.g., book_clubs)
+* Model Class - Singular with the first letter of each word capitalized (e.g., BookClub)
 
 |_.Model / Class |_.Table / Schema |
 |Post          |posts|
@@ -53,30 +53,32 @@ By default, ActiveRecord uses some naming conventions to find out how the mappin
 
 h4. Schema Conventions
 
-ActiveRecord uses naming conventions for the columns in database tables, depending on the purpose of these columns.
+Active Record uses naming conventions for the columns in database tables, depending on the purpose of these columns.
 
-* *Foreign keys* - These fields should be named following the pattern table_id i.e. (item_id, order_id). These are the fields that ActiveRecord will look for when you create associations between your models.
-* *Primary keys* - By default, ActiveRecord will use an integer column named "id" as the table's primary key. When using "Rails Migrations":migrations.html to create your tables, this column will be automatically created.
+* *Foreign keys* - These fields should be named following the pattern table_id (e.g., item_id, order_id). These are the fields that Active Record will look for when you create associations between your models.
+* *Primary keys* - By default, Active Record will use an integer column named "id" as the table's primary key. When using "Rails Migrations":migrations.html to create your tables, this column will be automatically created.
 
-There are also some optional column names that will create additional features to ActiveRecord instances:
+There are also some optional column names that will create additional features to Active Record instances:
 
-* *created_at / created_on* - ActiveRecord will store the current date and time to this field when creating the record.
-* *updated_at / updated_on* - ActiveRecord will store the current date and times to this field when updating the record.
+* *created_at* - Automatically gets set to the current date and time when the record is first created.
+* *created_on* - Automatically gets set to the current date when the record is first created.
+* *updated_at* - Automatically gets set to the current date and time whenever the record is updated.
+* *updated_on* - Automatically gets set to the current date whenever the record is updated.
 * *lock_version* - Adds "optimistic locking":http://api.rubyonrails.com/classes/ActiveRecord/Locking.html to a model.
 * *type* - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.com/classes/ActiveRecord/Base.html
 * *(table_name)_count* - Used to cache the number of belonging objects on associations. For example, a +comments_count+ column in a +Post+ class that has many instances of +Comment+ will cache the number of existent comments for each post.
 
-NOTE: While these column names are optional they are in fact reserved by ActiveRecord. Steer clear of reserved keywords unless you want the extra functionality. For example, "type" is a reserved keyword used to designate a table using Single Table Inheritance. If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling.
+NOTE: While these column names are optional they are in fact reserved by Active Record. Steer clear of reserved keywords unless you want the extra functionality. For example, "type" is a reserved keyword used to designate a table using Single Table Inheritance. If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling.
 
-h3. Creating ActiveRecord Models
+h3. Creating Active Record Models
 
-It's very easy to create ActiveRecord models. All you have to do is to subclass the ActiveRecord::Base class and you're good to go:
+It's very easy to create Active Record models. All you have to do is to subclass the +ActiveRecord::Base+ class and you're good to go:
 
 <ruby>
 class Product < ActiveRecord::Base; end
 </ruby>
 
-This will create a +Product+ model, mapped to a *products* table at the database. By doing this you'll also have the ability to map the columns of each row in that table with the attributes of the instances of your model. So, suppose that the *products* table was created using a SQL sentence like:
+This will create a +Product+ model, mapped to a *products* table at the database. By doing this you'll also have the ability to map the columns of each row in that table with the attributes of the instances of your model. So, suppose that the *products* table was created using an SQL sentence like:
 
 <sql>
 CREATE TABLE products (
@@ -99,12 +101,15 @@ h3. Overriding the Naming Conventions
 What if you need to follow a different naming convention or need to use your Rails application with a legacy database? No problem, you can easily override the default conventions.
 
 You can use the +ActiveRecord::Base.set_table_name+ method to specify the table name that should be used:
+
 <ruby>
 class Product < ActiveRecord::Base
   set_table_name "PRODUCT"
 end
 </ruby>
+
 If you do so, you will have to define manually the class name that is hosting the fixtures (class_name.yml) using the +set_fixture_class+ method in your test definition:
+
 <ruby>
 class FunnyJoke < ActiveSupport::TestCase
   set_fixture_class :funny_jokes => 'Joke'
@@ -113,7 +118,8 @@ class FunnyJoke < ActiveSupport::TestCase
 end
 </ruby>
 
-It's also possible to override the column that should be used as the table's primary key. Use the +ActiveRecord::Base.set_primary_key+ method for that:
+It's also possible to override the column that should be used as the table's primary key using the +ActiveRecord::Base.set_primary_key+ method:
+
 <ruby>
 class Product < ActiveRecord::Base
   set_primary_key "product_id"
@@ -122,7 +128,7 @@ end
 
 h3. Reading and Writing Data
 
-CRUD is an acronym for the four verbs we use to operate on data: Create, Read, Update, Delete. Active Record automatically creates methods to allow an application to read and manipulate data stored within its tables. 
+CRUD is an acronym for the four verbs we use to operate on data: *C*reate, *R*ead, *U*pdate and *D*elete. Active Record automatically creates methods to allow an application to read and manipulate data stored within its tables.
 
 h4. Create
 
@@ -155,7 +161,7 @@ Finally, passing a block to either create or new will return a new User object:
 
 h4. Read
 
-ActiveRecord provides a rich API for accessing data within a database. Below are a few examples of different data access methods provided by ActiveRecord.
+Active Record provides a rich API for accessing data within a database. Below are a few examples of different data access methods provided by Active Record.
 
 <ruby>
   # return all records
@@ -163,7 +169,7 @@ ActiveRecord provides a rich API for accessing data within a database. Below are
 </ruby>
 
 <ruby>
-  # return first record
+  # return the first record
   user = User.first
 </ruby>
 
@@ -201,11 +207,11 @@ Likewise, once retrieved an Active Record object can be destroyed which removes
 
 h3. Validations
 
-Active Record allows you to validate the state of a model before it gets written into the database. There are several methods that you can use to check your models and validate that an attribute value is not empty, is unique and not already in the database, follows a specific format and many more. You can learn more about validations in the "Active Record Validations and Callbacks guide":activerecord_validations_callbacks.html#validations-overview.
+Active Record allows you to validate the state of a model before it gets written into the database. There are several methods that you can use to check your models and validate that an attribute value is not empty, is unique and not already in the database, follows a specific format and many more. You can learn more about validations in the "Active Record Validations and Callbacks guide":active_record_validations_callbacks.html#validations-overview.
 
 h3. Callbacks
 
-Active Record callbacks allow you to attach code to certain events in the life-cycle of your models. This enables you to add behavior to your models by transparently executing code when those events occur, like when you create a new record, update it, destroy it and so on. You can learn more about callbacks in the "Active Record Validations and Callbacks guide":activerecord_validations_callbacks.html#callbacks-overview.
+Active Record callbacks allow you to attach code to certain events in the life-cycle of your models. This enables you to add behavior to your models by transparently executing code when those events occur, like when you create a new record, update it, destroy it and so on. You can learn more about callbacks in the "Active Record Validations and Callbacks guide":active_record_validations_callbacks.html#callbacks-overview.
 
 h3. Migrations
 

data/guides/source/active_record_querying.textile

@@ -51,7 +51,7 @@ Active Record will perform queries on the database for you and is compatible wit
 
 h3. Retrieving Objects from the Database
 
-To retrieve objects from the database, Active Record provides several finder methods. These methods allows you to pass arguments into it to perform certain queries on your database without the need of writing raw SQL.
+To retrieve objects from the database, Active Record provides several finder methods. Each finder method allows you to pass arguments into it to perform certain queries on your database without writing raw SQL.
 
 The methods are:
 * +where+
@@ -66,7 +66,7 @@ The methods are:
 * +readonly+
 * +from+
 
-All of these methods return a Relation
+All of the above methods return an instance of <tt>ActiveRecord::Relation</tt>.
 
 Primary operation of <tt>Model.find(options)</tt> can be summarized as:
 
@@ -86,7 +86,7 @@ Using <tt>Model.find(primary_key)</tt>, you can retrieve the object correspondin
 <ruby>
 # Find the client with primary key (id) 10.
 client = Client.find(10)
-=> #<Client id: 10, name: => "Ryan">
+=> #<Client id: 10, first_name: => "Ryan">
 </ruby>
 
 SQL equivalent of the above is:
@@ -103,7 +103,7 @@ h5. +first+
 
 <ruby>
 client = Client.first
-=> #<Client id: 1, name: => "Lifo">
+=> #<Client id: 1, first_name: => "Lifo">
 </ruby>
 
 SQL equivalent of the above is:
@@ -120,7 +120,7 @@ h5. +last+
 
 <ruby>
 client = Client.last
-=> #<Client id: 221, name: => "Russel">
+=> #<Client id: 221, first_name: => "Russel">
 </ruby>
 
 SQL equivalent of the above is:
@@ -140,7 +140,7 @@ h5. Using Multiple Primary Keys
 <ruby>
 # Find the clients with primary keys 1 and 10.
 client = Client.find(1, 10) # Or even Client.find([1, 10])
-=> [#<Client id: 1, name: => "Lifo">, #<Client id: 10, name: => "Ryan">]
+=> [#<Client id: 1, first_name: => "Lifo">, #<Client id: 10, first_name: => "Ryan">]
 </ruby>
 
 SQL equivalent of the above is:
@@ -227,7 +227,7 @@ h4. Pure String Conditions
 
 If you'd like to add conditions to your find, you could just specify them in there, just like +Client.where("orders_count = '2'")+. This will find all clients where the +orders_count+ field's value is 2.
 
-WARNING: Building your own conditions as pure strings can leave you vulnerable to SQL injection exploits. For example, +Client.where("name LIKE '%#{params[:name]}%'")+ is not safe. See the next section for the preferred way to handle conditions using an array.
+WARNING: Building your own conditions as pure strings can leave you vulnerable to SQL injection exploits. For example, +Client.where("first_name LIKE '%#{params[:first_name]}%'")+ is not safe. See the next section for the preferred way to handle conditions using an array.
 
 h4. Array Conditions
 
@@ -337,7 +337,7 @@ Just like in Ruby. If you want a shorter syntax be sure to check out the "Hash C
 
 h4. Hash Conditions
 
-Active Record also allows you to pass in a hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them:
+Active Record also allows you to pass in hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them:
 
 NOTE: Only equality, range and subset checking are possible with Hash conditions.
 
@@ -347,7 +347,7 @@ h5. Equality Conditions
 Client.where({ :locked => true })
 </ruby>
 
-The field name does not have to be a symbol it can also be a string:
+The field name can also be a string:
 
 <ruby>
 Client.where({ 'locked' => true })
@@ -447,33 +447,33 @@ h4. Limit and Offset
 
 To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +limit+ and +offset+ methods on the relation.
 
-If you want to limit the amount of records to a certain subset of all the records retrieved you usually use +limit+ for this, sometimes coupled with +offset+. Limit is the maximum number of records that will be retrieved from a query, and offset is the number of records it will start reading from from the first record of the set. For example:
+You can use +limit+ to specify the number of records to be retrieved, and use +offset+ to specify the number of records to skip before starting to return the records. For example
 
 <ruby>
 Client.limit(5)
 </ruby>
 
-This code will return a maximum of 5 clients and because it specifies no offset it will return the first 5 clients in the table. The SQL it executes will look like this:
+will return a maximum of 5 clients and because it specifies no offset it will return the first 5 in the table. The SQL it executes looks like this:
 
 <sql>
 SELECT * FROM clients LIMIT 5
 </sql>
 
-Or chaining both +limit+ and +offset+:
+Adding +offset+ to that
 
 <ruby>
-Client.limit(5).offset(5)
+Client.limit(5).offset(30)
 </ruby>
 
-This code will return a maximum of 5 clients and because it specifies an offset this time, it will return these records starting from the 5th client in the clients table. The SQL looks like:
+will return instead a maximum of 5 clients beginning with the 31st. The SQL looks like:
 
 <sql>
-SELECT * FROM clients LIMIT 5, 5
+SELECT * FROM clients LIMIT 5, 30
 </sql>
 
 h4. Group
 
-To apply +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find.
+To apply a +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find.
 
 For example, if you want to find a collection of the dates orders were created on:
 
@@ -491,7 +491,7 @@ SELECT * FROM orders GROUP BY date(created_at)
 
 h4. Having
 
-SQL uses +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can specify the +HAVING+ clause to the SQL fired by the +Model.find+ using +:having+ option on the find.
+SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can add the +HAVING+ clause to the SQL fired by the +Model.find+ by adding the +:having+ option to the find.
 
 For example:
 
@@ -517,7 +517,7 @@ Any attempt to alter or destroy the readonly records will not succeed, raising a
 Client.first.readonly(true)
 </ruby>
 
-If you assign this record to a variable client, calling the following code will raise an +ActiveRecord::ReadOnlyRecord+ exception:
+For example, calling the following code will raise an +ActiveRecord::ReadOnlyRecord+ exception:
 
 <ruby>
 client = Client.first.readonly(true)
@@ -527,7 +527,9 @@ client.save
 
 h4. Locking Records for Update
 
-Locking is helpful for preventing the race conditions when updating records in the database and ensuring atomic updated. Active Record provides two locking mechanism:
+Locking is helpful for preventing race conditions when updating records in the database and ensuring atomic updates.
+
+Active Record provides two locking mechanisms:
 
 * Optimistic Locking
 * Pessimistic Locking
@@ -538,13 +540,13 @@ Optimistic locking allows multiple users to access the same record for edits, an
 
 <strong>Optimistic locking column</strong>
 
-In order to use optimistic locking, the table needs to have a column called +lock_version+. Each time the record is updated, Active Record increments the +lock_version+ column and the locking facilities ensure that records instantiated twice will let the last one saved raise an +ActiveRecord::StaleObjectError+ exception if the first was also updated. Example:
+In order to use optimistic locking, the table needs to have a column called +lock_version+. Each time the record is updated, Active Record increments the +lock_version+ column. If an update request is made with a lower value in the +lock_version+ field than is currently in the +lock_version+ column in the database, the update request will fail with an +ActiveRecord::StaleObjectError+. Example:
 
 <ruby>
 c1 = Client.find(1)
 c2 = Client.find(1)
 
-c1.name = "Michael"
+c1.first_name = "Michael"
 c1.save
 
 c2.name = "should fail"
@@ -569,7 +571,7 @@ end
 
 h5. Pessimistic Locking
 
-Pessimistic locking uses locking mechanism provided by the underlying database. Passing +:lock => true+ to +Model.find+ obtains an exclusive lock on the selected rows. +Model.find+ using +:lock+ are usually wrapped inside a transaction for preventing deadlock conditions.
+Pessimistic locking uses a locking mechanism provided by the underlying database. Passing +:lock => true+ to +Model.find+ obtains an exclusive lock on the selected rows. +Model.find+ using +:lock+ are usually wrapped inside a transaction for preventing deadlock conditions.
 
 For example:
 
@@ -601,7 +603,7 @@ end
 
 h3. Joining Tables
 
-<tt>Model.find</tt> provides a +:joins+ option for specifying +JOIN+ clauses on the resulting SQL. There multiple different ways to specify the +:joins+ option:
+<tt>Model.find</tt> provides a +:joins+ option for specifying +JOIN+ clauses on the resulting SQL. There are multiple ways to specify the +:joins+ option:
 
 h4. Using a String SQL Fragment
 
@@ -698,7 +700,7 @@ time_range = (Time.now.midnight - 1.day)..Time.now.midnight
 Client.joins(:orders).where('orders.created_at' => time_range)
 </ruby>
 
-An alternative and cleaner syntax to this is to nest the hash conditions:
+An alternative and cleaner syntax is to nest the hash conditions:
 
 <ruby>
 time_range = (Time.now.midnight - 1.day)..Time.now.midnight
@@ -727,7 +729,7 @@ This code looks fine at the first sight. But the problem lies within the total n
 
 <strong>Solution to N <plus> 1 queries problem</strong>
 
-Active Record lets you specify all the associations in advanced that are going to be loaded. This is possible by specifying the +includes+ method of the +Model.find+ call. With +includes+, Active Record ensures that all the specified associations are loaded using minimum possible number of queries.
+Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the +includes+ method of the +Model.find+ call. With +includes+, Active Record ensures that all of the specified associations are loaded using the minimum possible number of queries.
 
 Revisiting the above case, we could rewrite +Client.all+ to use eager load addresses:
 
@@ -749,7 +751,7 @@ SELECT addresses.* FROM addresses
 
 h4. Eager Loading Multiple Associations
 
-Active Record lets you eager load any possible number of associations with a single +Model.find+ call by using an array, hash, or a nested hash of array/hash with the +includes+ method.
+Active Record lets you eager load any number of associations with a single +Model.find+ call by using an array, hash, or a nested hash of array/hash with the +includes+ method.
 
 h5. Array of Multiple Associations 
 
@@ -765,7 +767,7 @@ h5. Nested Associations Hash
 Category.find(1).includes(:posts => [{:comments => :guest}, :tags])
 </ruby>
 
-The above code finds the category with id 1 and eager loads all the posts associated with the found category. Additionally, it will also eager load every posts' tags and comments. Every comment's guest association will get eager loaded as well.
+This will find the category with id 1 and eager load all of the associated posts, the associated posts' tags and comments, and every comment's guest association.
 
 h4. Specifying Conditions on Eager Loaded Associations
 
@@ -773,32 +775,32 @@ Even though Active Record lets you specify conditions on the eager loaded associ
 
 h3. Dynamic Finders
 
-For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +name+ on your +Client+ model for example, you get +find_by_name+ and +find_all_by_name+ for free from Active Record. If you have also have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+.
+For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +first_name+ on your +Client+ model for example, you get +find_by_first_name+ and +find_all_by_first_name+ for free from Active Record. If you have also have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+.
 
 You can do +find_last_by_*+ methods too which will find the last record matching your argument.
 
 You can specify an exclamation point (<tt>!</tt>) on the end of the dynamic finders to get them to raise an +ActiveRecord::RecordNotFound+ error if they do not return any records, like +Client.find_by_name!("Ryan")+
 
-If you want to find both by name and locked, you can chain these finders together by simply typing +and+ between the fields for example +Client.find_by_name_and_locked("Ryan", true)+.
+If you want to find both by name and locked, you can chain these finders together by simply typing +and+ between the fields for example +Client.find_by_first_name_and_locked("Ryan", true)+.
 
 
-There's another set of dynamic finders that let you find or create/initialize objects if they aren't found. These work in a similar fashion to the other finders and can be used like +find_or_create_by_name(params[:name])+. Using this will firstly perform a find and then create if the find returns +nil+. The SQL looks like this for +Client.find_or_create_by_name("Ryan")+:
+There's another set of dynamic finders that let you find or create/initialize objects if they aren't found. These work in a similar fashion to the other finders and can be used like +find_or_create_by_first_name(params[:first_name])+. Using this will first perform a find and then create if the find returns +nil+. The SQL looks like this for +Client.find_or_create_by_first_name("Ryan")+:
 
 <sql>
-SELECT * FROM clients WHERE (clients.name = 'Ryan') LIMIT 1
+SELECT * FROM clients WHERE (clients.first_name = 'Ryan') LIMIT 1
 BEGIN
-INSERT INTO clients (name, updated_at, created_at, orders_count, locked)
+INSERT INTO clients (first_name, updated_at, created_at, orders_count, locked)
   VALUES('Ryan', '2008-09-28 15:39:12', '2008-09-28 15:39:12', 0, '0')
 COMMIT
 </sql>
 
-+find_or_create+'s sibling, +find_or_initialize+, will find an object and if it does not exist will act similar to calling +new+ with the arguments you passed in. For example:
++find_or_create+'s sibling, +find_or_initialize+, will find an object and if it does not exist will act similarly to calling +new+ with the arguments you passed in. For example:
 
 <ruby>
-client = Client.find_or_initialize_by_name('Ryan')
+client = Client.find_or_initialize_by_first_name('Ryan')
 </ruby>
 
-will either assign an existing client object with the name "Ryan" to the client local variable, or initialize a new object similar to calling +Client.new(:name => 'Ryan')+. From here, you can modify other fields in client by calling the attribute setters on it: +client.locked = true+ and when you want to write it to the database just call +save+ on it.
+will either assign an existing client object with the name "Ryan" to the client local variable, or initialize a new object similar to calling +Client.new(:first_name => 'Ryan')+. From here, you can modify other fields in client by calling the attribute setters on it: +client.locked = true+ and when you want to write it to the database just call +save+ on it.
 
 h3. Finding by SQL
 
@@ -836,7 +838,7 @@ Client.exists?(1,2,3)
 Client.exists?([1,2,3])
 </ruby>
 
-Further more, +exists+ takes a +conditions+ option much like find:
+The +exists+ method may also take a +conditions+ option much like find:
 
 <ruby>
 Client.exists?(:conditions => "first_name = 'Ryan'")
@@ -869,7 +871,7 @@ SELECT count(*) AS count_all FROM clients WHERE (first_name = 'Ryan')
 You can also use the +includes+ or +joins+ methods for this to do something a little more complex:
 
 <ruby>
-Client.count.where("clients.first_name = 'Ryan' AND orders.status = 'received'").includes("orders")
+Client.where("clients.first_name = 'Ryan' AND orders.status = 'received'").includes("orders").count
 </ruby>
 
 Which will execute: