Several small corrections and improvements to the Migrations and Active Record Basics guides.

1 files changed, 29 insertions, 28 deletions

diff --git a/railties/guides/source/active_record_basics.textile b/railties/guides/source/active_record_basics.textile
index cab8c80866..66ad7b0255 100644
--- a/railties/guides/source/active_record_basics.textile
+++ b/railties/guides/source/active_record_basics.textile
@@ -38,47 +38,48 @@ When writing applications using other programming languages or frameworks, it ma
 
 h4. Naming Conventions
 
-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:
+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 (e.g., book_clubs)
-* Model Class - Singular with the first letter of each word capitalized (e.g., 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|
-|LineItem      |line_items|
-|Deer          |deer|
-|Mouse         |mice|
-|Person        |people|
+|+Post+          |+posts+|
+|+LineItem+      |+line_items+|
+|+Deer+          |+deer+|
+|+Mouse+         |+mice+|
+|+Person+        |+people+|
 
 
 h4. Schema Conventions
 
 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 (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.
+* *Foreign keys* - These fields should be named following the pattern +singularized_table_name_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 Active Record instances:
 
-* *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.org/classes/ActiveRecord/Locking.html to a model.
-* *type* - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.org/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.
+* +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.org/classes/ActiveRecord/Locking.html to a model.
+* +type+ - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.org/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 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.
+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 (STI). If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling.
 
 h3. Creating Active Record Models
 
-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:
+It is 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
+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 an 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. Suppose that the +products+ table was created using an SQL sentence like:
 
 <sql>
 CREATE TABLE products (
@@ -126,21 +127,21 @@ class Product < ActiveRecord::Base
 end
 </ruby>
 
-h3. Reading and Writing Data
+h3. CRUD: Reading and Writing Data
 
 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
 
-Active Record objects can be created from a hash, a block or have its attributes manually set after creation. The _new_ method will return a new object while _create_ will return the object and save it to the database.
+Active Record objects can be created from a hash, a block or have their attributes manually set after creation. The +new+ method will return a new object while +create+ will return the object and save it to the database.
 
-For example, given a model +User+ with attributes of +name+ and +occupation+, the _create_ method call will create and save a new record into the database:
+For example, given a model +User+ with attributes of +name+ and +occupation+, the +create+ method call will create and save a new record into the database:
 
 <ruby>
   user = User.create(:name => "David", :occupation => "Code Artist")
 </ruby>
 
-Using the _new_ method, an object can be created without being saved:
+Using the +new+ method, an object can be created without being saved:
 
 <ruby>
   user = User.new
@@ -148,9 +149,9 @@ Using the _new_ method, an object can be created without being saved:
   user.occupation = "Code Artist"
 </ruby>
 
-A call to _user.save_ will commit the record to the database.
+A call to +user.save+ will commit the record to the database.
 
-Finally, passing a block to either create or new will return a new User object:
+Finally, if a block is provided, both +create+ and +new+ will yield the new object to that block for initialization:
 
 <ruby>
   user = User.new do |u|
@@ -164,7 +165,7 @@ h4. Read
 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
+  # return array with all records
   users = User.all
 </ruby>