railties 3.0.0.beta3 → 3.0.0.beta4

data/guides/source/credits.html.erb

@@ -43,6 +43,10 @@ Ruby on Rails Guides: Credits
   Jeff Dean is a software engineer with <a href="http://pivotallabs.com">Pivotal Labs</a>.
 <% end %>
 
+<%= author('Mikel Lindsaar', 'raasdnil') do %>
+  Mikel Lindsaar has been working with Rails since 2006 and is the author of the Ruby <a href="http://github.com/mikel/mail">Mail gem</a> and core contributor (he helped re-write Action Mailer's API). Mikel is the founder of <a href="http://rubyx.com/">RubyX</a>, has a <a href="http://lindsaar.net/">blog</a> and <a href="http://twitter.com/raasdnil">tweets</a>.
+<% end %>
+
 <%= author('Cássio Marques', 'cmarques') do %>
   Cássio Marques is a Brazilian software developer working with different programming languages such as Ruby, JavaScript, CPP and Java, as an independent consultant. He blogs at <a href="http://cassiomarques.wordpress.com">/* CODIFICANDO */</a>, which is mainly written in Portuguese, but will soon get a new section for posts with English translation.
 <% end %>
@@ -58,7 +62,3 @@ Ruby on Rails Guides: Credits
 <%= author('Heiko Webers', 'hawe') do %>
   Heiko Webers is the founder of <a href="http://www.bauland42.de">bauland42</a>, a German web application security consulting and development company focused on Ruby on Rails. He blogs at the <a href="http://www.rorsecurity.info">Ruby on Rails Security Project</a>. After 10 years of desktop application development, Heiko has rarely looked back.
 <% end %>
-
-<%= author('Mikel Lindsaar', 'raasdnil') do %>
-  Mikel Lindsaar has been working with Rails since 2006 and is the author of the Ruby Mail gem and core contributor (he helped re-write Action Mailer's API). Mikel has a <a href="http://lindsaar.net/">blog</a> and <a href="http://twitter.com/raasdnil">tweets</a>.
-<% end %>

data/guides/source/debugging_rails_applications.textile

@@ -136,7 +136,7 @@ config.logger = Logger.new(STDOUT)
 config.logger = Log4r::Logger.new("Application Log")
 </ruby>
 
-TIP: By default, each log is created under +RAILS_ROOT/log/+ and the log file name is +environment_name.log+.
+TIP: By default, each log is created under +Rails.root/log/+ and the log file name is +environment_name.log+.
 
 h4. Log Levels
 
@@ -680,7 +680,7 @@ h3. Plugins for Debugging
 
 There are some Rails plugins to help you to find errors and debug your application. Here is a list of useful plugins for debugging:
 
-* "Footnotes":http://github.com/drnic/rails-footnotes/tree/master: Every Rails page has footnotes that give request information and link back to your source via TextMate.
+* "Footnotes":http://github.com/josevalim/rails-footnotes: Every Rails page has footnotes that give request information and link back to your source via TextMate.
 * "Query Trace":http://github.com/ntalbott/query_trace/tree/master: Adds query origin tracing to your logs.
 * "Query Stats":http://github.com/dan-manges/query_stats/tree/master: A Rails plugin to track database queries.
 * "Query Reviewer":http://code.google.com/p/query-reviewer/: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of warnings for each query that it analyzed.

data/guides/source/form_helpers.textile

@@ -205,7 +205,7 @@ Upon form submission the value entered by the user will be stored in +params[:pe
 
 WARNING: You must pass the name of an instance variable, i.e. +:person+ or +"person"+, not an actual instance of your model object.
 
-Rails provides helpers for displaying the validation errors associated with a model object. These are covered in detail by the "Active Record Validations and Callbacks":./activerecord_validations_callbacks.html#_using_the_tt_errors_tt_collection_in_your_view_templates guide.
+Rails provides helpers for displaying the validation errors associated with a model object. These are covered in detail by the "Active Record Validations and Callbacks":./activerecord_validations_callbacks.html#displaying-validation-errors-in-the-view guide.
 
 h4. Binding a Form to an Object
 
@@ -255,7 +255,7 @@ You can create a similar binding without actually creating  +<form>+ tags
 <erb>
 <%= form_for :person, @person, :url => { :action => "create" } do |person_form| %>
   <%= person_form.text_field :name %>
-  <% fields_for @person.contact_detail do |contact_details_form| %>
+  <%= fields_for @person.contact_detail do |contact_details_form| %>
     <%= contact_details_form.text_field :phone_number %>
   <% end %>
 <% end %>
@@ -280,7 +280,7 @@ The Article model is directly available to users of the application, so -- follo
 map.resources :articles
 </ruby>
 
-TIP: Declaring a resource has a number of side-affects. See "Rails Routing From the Outside In":routing.html#restful-routing-the-rails-default for more information on setting up and using resources.
+TIP: Declaring a resource has a number of side-affects. See "Rails Routing From the Outside In":routing.html#resource-routing-the-rails-default for more information on setting up and using resources.
 
 When dealing with RESTful resources, calls to +form_for+ can get significantly easier if you rely on *record identification*. In short, you can just pass the model instance and have Rails figure out model name and the rest:
 
@@ -697,7 +697,7 @@ You might want to render a form with a set of edit fields for each of a person's
 <%= form_for @person do |person_form| %>
   <%= person_form.text_field :name %>
   <% for address in @person.addresses %>
-    <% person_form.fields_for address, :index => address do |address_form|%>
+    <%= person_form.fields_for address, :index => address do |address_form|%>
       <%= address_form.text_field :city %>
     <% end %>
   <% end %>
@@ -725,7 +725,7 @@ Rails knows that all these inputs should be part of the person hash because you
 To create more intricate nestings, you can specify the first part of the input name (+person[address]+ in the previous example) explicitly, for example
 
 <erb>
-<% fields_for 'person[address][primary]', address, :index => address do |address_form| %>
+<%= fields_for 'person[address][primary]', address, :index => address do |address_form| %>
   <%= address_form.text_field :city %>
 <% end %>
 </erb>
@@ -741,7 +741,7 @@ As a general rule the final input name is the concatenation of the name given to
 As a shortcut you can append [] to the name and omit the +:index+ option. This is the same as specifying +:index => address+ so
 
 <erb>
-<% fields_for 'person[address][primary][]', address do |address_form| %>
+<%= fields_for 'person[address][primary][]', address do |address_form| %>
   <%= address_form.text_field :city %>
 <% end %>
 </erb>
@@ -752,6 +752,7 @@ h3. Building Complex Forms
 
 Many apps grow beyond simple forms editing a single object. For example when creating a Person you might want to allow the user to (on the same form) create multiple address records (home, work, etc.). When later editing that person the user should be able to add, remove or amend addresses as necessary. While this guide has shown you all the pieces necessary to handle this, Rails does not yet have a standard end-to-end way of accomplishing this, but many have come up with viable approaches. These include:
 
+* As of Rails 2.3, Rails includes "Nested Attributes":./2_3_release_notes.html#nested-attributes and "Nested Object Forms":./2_3_release_notes.html#nested-object-forms
 * Ryan Bates' series of Railscasts on "complex forms":http://railscasts.com/episodes/75
 * Handle Multiple Models in One Form from "Advanced Rails Recipes":http://media.pragprog.com/titles/fr_arr/multiple_models_one_form.pdf
 * Eloy Duran's "complex-forms-examples":http://github.com/alloy/complex-form-examples/ application

data/guides/source/generators.textile

@@ -20,7 +20,7 @@ h3. First contact
 When you create an application using the +rails+ command, you are in fact using a Rails generator. After that, you can get a list of all available generators by just invoking +rails generate+:
 
 <shell>
-$ rails myapp
+$ rails new myapp
 $ cd myapp
 $ rails generate
 </shell>
@@ -88,9 +88,7 @@ And it will create a new generator as follow:
 
 <ruby>
 class InitializerGenerator < Rails::Generators::NamedBase
-  def self.source_root
-    @source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
-  end
+  source_root File.expand_path("../templates", __FILE__)
 end
 </ruby>
 
@@ -115,9 +113,7 @@ And now let's change the generator to copy this template when invoked:
 
 <ruby>
 class InitializerGenerator < Rails::Generators::NamedBase
-  def self.source_root
-    @source_root ||= File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
-  end
+  source_root File.expand_path("../templates", __FILE__)
 
   def copy_initializer_file
     copy_file "initializer.rb", "config/initializers/#{file_name}.rb"
@@ -135,21 +131,18 @@ We can see that now a initializer named foo was created at +config/initializers/
 
 h3. Generators lookup
 
-Now that we know how to create generators, we must know where Rails looks for generators before invoking them. When we invoke the initializer generator, Rails looks at the following paths in the given order:
+With our first generator created, we must discuss briefly generators lookup. The way Rails finds generators is exactly the same way Ruby find files, i.e. using +$LOAD_PATHS+.
+
+For instance, when you say +rails g initializer foo+, rails knows you want to invoke the initializer generator and then search for the following generators in the $LOAD_PATHS:
 
 <shell>
-RAILS_APP/lib/generators
-RAILS_APP/lib/rails_generators
-RAILS_APP/vendor/plugins/*/lib/generators
-RAILS_APP/vendor/plugins/*/lib/rails_generators
-GEMS_PATH/*/lib/generators
-GEMS_PATH/*/lib/rails_generators
-~/rails/generators
-~/rails/rails_generators
-RAILS_GEM/lib/rails/generators
+rails/generators/initializer/initializer_generator.rb
+generators/initializer/initializer_generator.rb
+rails/generators/initializer_generator.rb
+generators/initializer_generator.rb
 </shell>
 
-First Rails looks for generators in your application, then in plugins and/or gems, then in your home and finally the builtin generators. One very important thing to keep in mind is that in Rails 3.0 and after it only looks for generators in gems being used in your application. So if you have rspec installed as a gem, but it's not declared in your application, Rails won't be able to invoke it.
+If none of them is found, it raises an error message.
 
 h3. Customizing your workflow
 
@@ -183,7 +176,6 @@ $ rails generate scaffold User name:string
       create      app/views/users/show.html.erb
       create      app/views/users/new.html.erb
       create      app/views/users/_form.html.erb
-      create      app/views/layouts/users.html.erb
       invoke    test_unit
       create      test/functional/users_controller_test.rb
       invoke    helper
@@ -284,7 +276,7 @@ end
 end
 </ruby>
 
-Now, when the helper generator is invoked and let's say test unit is configured as test framework, it will try to invoke both +MyHelper::Generators::TestUnitGenerator+ and +TestUnit::Generators::MyHelperGenerator+. Since none of those are defined, we can tell our generator to invoke +TestUnit::Generators::HelperGenerator+ instead, which is defined since it's a Rails hook. To do that, we just need to add:
+Now, when the helper generator is invoked and let's say test unit is configured as test framework, it will try to invoke both +MyHelper::Generators::TestUnitGenerator+ and +TestUnit::Generators::MyHelperGenerator+. Since none of those are defined, we can tell our generator to invoke +TestUnit::Generators::HelperGenerator+ instead, which is defined since it's a Rails generator. To do that, we just need to add:
 
 <ruby>
   # Search for :helper instead of :my_helper
@@ -330,14 +322,10 @@ config.generators do |g|
   g.template_engine :erb
   g.test_framework  :shoulda, :fixture => false
   g.stylesheets     false
-end
-</ruby>
 
-And at the end of the same file:
-
-<ruby>
-require 'rails/generators'
-Rails::Generators.fallbacks[:shoulda] = :test_unit
+  # Add a fallback!
+  g.fallbacks[:should] = :test_unit
+end
 </ruby>
 
 Now, if create a Comment scaffold, you will see that shoulda generators are being invoked, and at the end, they are just falling back to test unit generators:
@@ -369,10 +357,12 @@ $ rails generate scaffold Comment body:text
       create        test/unit/helpers/comments_helper_test.rb
 </shell>
 
-Such tool allows your generators to have single responsibility, increasing the code reuse and reducing the amount of code duplication.
+Such tool allows your generators to have single responsibility, increasing the code reuse and reducing the amount of duplication.
 
 h3. Changelog
 
 "Lighthouse Ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/102
 
-* November 20, 2009: First release version by José Valim
+* April 30, 2010: Reviewed by José Valim
+
+* November 20, 2009: First version by José Valim

data/guides/source/getting_started.textile

@@ -16,6 +16,9 @@ h3. Guide Assumptions
 This guide is designed for beginners who want to get started with a Rails application from scratch. It does not assume that you have any prior experience with Rails. However, to get the most out of it, you need to have some prerequisites installed:
 
 * The "Ruby":http://www.ruby-lang.org/en/downloads language version 1.8.7 or higher
+
+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.
+
 * The "RubyGems":http://rubyforge.org/frs/?group_id=126 packaging system
 * A working installation of the "SQLite3 Database":http://www.sqlite.org
 
@@ -87,11 +90,11 @@ Action View manages the views of your Rails application. It can create both HTML
 
 h5. Action Dispatch
 
-Action Dispatch handles routing of web requests and dispatches them as you want, either to your application, any other Rack application.
+Action Dispatch handles routing of web requests and dispatches them as you want, either to your application or any other Rack application.
 
 h5. Action Mailer
 
-Action Mailer is a framework for building e-mail services. You can use Action Mailer to send emails based on flexible templates, or to receive and process incoming email.
+Action Mailer is a framework for building e-mail services. You can use Action Mailer to receive and process incoming email and send simple plain text or complex multipart emails based on flexible templates.
 
 h5. Active Model
 
@@ -157,7 +160,7 @@ The best way to use this guide is to follow each step as it happens, no code or
 To begin, open a terminal, navigate to a folder where you have rights to create files, and type:
 
 <shell>
-$ rails blog
+$ rails new blog
 </shell>
 
 This will create a Rails application called Blog in a directory called blog.
@@ -232,13 +235,13 @@ If you choose to use MySQL instead of the shipped Sqlite3 database, your +config
 
 <yaml>
 development:
-adapter: mysql
-encoding: utf8
-database: blog_development
-pool: 5
-username: root
-password:
-socket: /tmp/mysql.sock
+  adapter: mysql
+  encoding: utf8
+  database: blog_development
+  pool: 5
+  username: root
+  password:
+  socket: /tmp/mysql.sock
 </yaml>
 
 If your development computer's MySQL installation includes a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the +development+ section as appropriate.
@@ -249,12 +252,12 @@ Finally if you choose to use PostgreSQL, your +config/database.yml+ will be cust
 
 <yaml>
 development:
-adapter: postgresql
-encoding: unicode
-database: blog_development
-pool: 5
-username: blog
-password:
+  adapter: postgresql
+  encoding: unicode
+  database: blog_development
+  pool: 5
+  username: blog
+  password:
 </yaml>
 
 Change the username and password in the +development+ section as appropriate.
@@ -356,19 +359,18 @@ The scaffold generator will build 15 files in your application, along with some
 |_.File                                       |_.Purpose|
 |db/migrate/20100207214725_create_posts.rb.rb    |Migration to create the posts table in your database (your name will include a different timestamp)|
 |app/models/post.rb                           |The Post model|
-|test/unit/post_test.rb                       |Unit testing harness for the posts model|
 |test/fixtures/posts.yml                      |Dummy posts for use in testing|
 |app/controllers/posts_controller.rb          |The Posts controller|
 |app/views/posts/index.html.erb               |A view to display an index of all posts |
 |app/views/posts/edit.html.erb                |A view to edit an existing post|
 |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/_form.html.erb               |A view to control the overall look and feel of the other posts views|
-|app/views/layouts/posts.html.erb             |A view to control the overall look and feel of the other posts views|
+|app/views/posts/_form.html.erb               |A partial to control the overall look and feel of the form used in edit and new views|
+|app/helpers/posts_helper.rb                  |Helper functions to be used from the post views|
+|test/unit/post_test.rb                       |Unit testing harness for the posts model|
 |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/unit/helpers/posts_helper_test.rb       |Unit testing harness for the posts helper|
+|config/routes.rb                             |Edited to include routing information for posts|
 |public/stylesheets/scaffold.css              |Cascading style sheet to make the scaffolded views look better|
 
 h4. Running a Migration
@@ -395,7 +397,7 @@ class CreatePosts < ActiveRecord::Migration
 end
 </ruby>
 
-The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date.  The +up+ command in this case creates a +posts+ table with two string columns and a text column.  It also is creating two timestamp fields to track record creation and updating.  More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide.
+The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date.  The +up+ command in this case creates a +posts+ table with two string columns and a text column.  It also creates two timestamp fields to track record creation and updating.  More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide.
 
 At this point, you can use a rake command to run the migration:
 
@@ -504,7 +506,7 @@ def index
 end
 </ruby>
 
-This code sets the +@posts+ instance variable to an array of all posts in the database. +Post.all+ calls the +Post+ model to return all of the posts that are currently in the database, with no limiting conditions.
++Post.all+ calls the +Post+ model to return all of the posts currently in the database. The result of this call is an array containing the posts which has been saved in an instance variable called +@posts+.
 
 TIP: For more information on finding records with Active Record, see "Active Record Query Interface":active_record_querying.html.
 
@@ -543,7 +545,7 @@ The +respond_to+ block handles both HTML and XML calls to this action. If you br
 This view iterates over the contents of the +@posts+ array to display content and links. A few things to note in the view:
 
 * +link_to+ builds a hyperlink to a particular destination
-* +edit_post_path+ is a helper that Rails provides as part of RESTful routing. You'll see a variety of these helpers for the different actions that the controller includes.
+* +edit_post_path+ and +new_post_path+ are helpers that Rails provides as part of RESTful routing. You'll see a variety of these helpers for the different actions that the controller includes.
 
 NOTE. In previous versions of Rails, you had to use +&lt;%=h post.name %&gt;+ so that any HTML would be escaped before being inserted into the page.  In Rails 3.0, this is now the default.  To get unescaped HTML, you now use +&lt;%= raw post.name %&gt;+.
 
@@ -551,19 +553,19 @@ TIP: For more details on the rendering process, see "Layouts and Rendering in Ra
 
 h4. Customizing the Layout
 
-The view is only part of the story of how HTML is displayed in your web browser. Rails also has the concept of +layouts+, which are containers for views. When Rails renders a view to the browser, it does so by putting the view's HTML into a layout's HTML. The +rails generate scaffold+ command automatically created a default layout, +app/views/layouts/posts.html.erb+, for the posts. Open this layout in your editor and modify the +body+ tag:
+The view is only part of the story of how HTML is displayed in your web browser. Rails also has the concept of +layouts+, which are containers for views. When Rails renders a view to the browser, it does so by putting the view's HTML into a layout's HTML. In previous versions of Rails, the +rails generate scaffold+ command would automatically create a controller specific layout, like +app/views/layouts/posts.html.erb+, for the posts controller. However this has been changed in Rails 3.0. A application specific +layout+ is used for all the controllers and can be found in +app/views/layouts/application.html.erb+. Open this layout in your editor and modify the +body+ tag:
 
 <erb>
 <!DOCTYPE html>
 <html>
 <head>
-  <title>Posts: <%= controller.action_name %></title>
-  <%= stylesheet_link_tag 'scaffold' %>
+  <title>Blog</title>
+  <%= stylesheet_link_tag :all %>
+  <%= javascript_include_tag :defaults %>
+  <%= csrf_meta_tag %>
 </head>
 <body style="background: #EEEEEE;">
 
-<p class="notice"><%= notice %></p>
-
 <%= yield %>
 
 </body>
@@ -603,7 +605,16 @@ If you take a look at +views/posts/_form.html.erb+ file, you will see the follow
 
 <erb>
 <%= form_for(@post) do |f| %>
-  <%= f.error_messages %>
+  <% if @post.errors.any? %>
+  <div id="errorExplanation">
+    <h2><%= pluralize(@post.errors.count, "error") %> prohibited this post from being saved:</h2>
+    <ul>
+    <% @post.errors.full_messages.each do |msg| %>
+      <li><%= msg %></li>
+    <% end %>
+    </ul>
+  </div>
+  <% end %>
 
   <div class="field">
     <%= f.label :name %><br />
@@ -654,7 +665,7 @@ def create
 end
 </ruby>
 
-The +create+ action instantiates a new Post object from the data supplied by the user on the form, which Rails makes available in the +params+ hash. After successfully saving the new post, returns the appropriate format that the user has requested (HTML in our case). It then redirects the user to the resulting post +show+ action and sets a notice to the user that the Post was successfully created.
+The +create+ action instantiates a new Post object from the data supplied by the user on the form, which Rails makes available in the +params+ hash. After successfully saving the new post, +create+ returns the appropriate format that the user has requested (HTML in our case). It then redirects the user to the resulting post +show+ action and sets a notice to the user that the Post was successfully created.
 
 If the post was not successfully saved, due to a validation error, then the controller returns the user back to the +new+ action with any error messages so that the user has the chance to fix the error and try again.
 
@@ -678,6 +689,8 @@ end
 The +show+ action uses +Post.find+ to search for a single record in the database by its id value. After finding the record, Rails displays it by using +show.html.erb+:
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -742,7 +755,7 @@ def update
 end
 </ruby>
 
-In the +update+ action, Rails first uses the +:id+ parameter passed back from the edit view to locate the database record that's being edited. The +update_attributes+ call then takes the rest of the parameters from the request and applies them to this record. If all goes well, the user is redirected to the post's +show+ view. If there are any problems, it's back to +edit+ to correct them.
+In the +update+ action, Rails first uses the +:id+ parameter passed back from the edit view to locate the database record that's being edited. The +update_attributes+ call then takes the rest of the parameters from the request and applies them to this record. If all goes well, the user is redirected to the post's +show+ view. If there are any problems, it's back to the +edit+ view to correct them.
 
 h4. Destroying a Post
 
@@ -764,7 +777,7 @@ The +destroy+ method of an Active Record model instance removes the correspondin
 
 h3. Adding a Second Model
 
-Now that you've seen what's in a model built with scaffolding, it's time to add a second model to the application. The second model will handle comments on blog posts.
+Now that you've seen how a model built with scaffolding looks like, it's time to add a second model to the application. The second model will handle comments on blog posts.
 
 h4. Generating a Model
 
@@ -878,18 +891,21 @@ With the model in hand, you can turn your attention to creating a matching contr
 $ rails generate controller Comments
 </shell>
 
-This creates four files:
+This creates four files and one empty directory:
 
 * +app/controllers/comments_controller.rb+ - The controller
 * +app/helpers/comments_helper.rb+ - A view helper file
 * +test/functional/comments_controller_test.rb+ - The functional tests for the controller
 * +test/unit/helpers/comments_helper_test.rb+ - The unit tests for the helper
+* +app/views/comments/+ - Views of the controller are stored here
 
 Like with any blog, our readers will create their comments directly after reading the post, and once they have added their comment, will be sent back to the post show page to see their comment now listed.  Due to this, our +CommentsController+ is there to provide a method to create comments and delete SPAM comments when they arrive.
 
 So first, we'll wire up the Post show template (+/app/views/posts/show.html.erb+) to let us make a new comment:
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -940,11 +956,13 @@ end
 
 You'll see a bit more complexity here than you did in the controller for posts. That's a side-effect of the nesting that you've set up; each request for a comment has to keep track of the post to which the comment is attached, thus the initial find action to the Post model to get the post in question.
 
-In addition, the code takes advantage of some of the methods available for an association. For example, in the +new+ method, it calls
+In addition, the code takes advantage of some of the methods available for an association. We use the +create+ method on +@post.comments+ to create and save the comment. This will automatically link the comment so that it belongs to that particular post.
 
-Once we have made the new comment, we send the user back to the +post_path(@post)+ URL.  This runs the +show+ action of the +PostsController+ which then renders the +show.html.erb+ template where we want the comment to show, so then, we'll add that to the +app/view/posts/show.html.erb+.
+Once we have made the new comment, we send the user back to the original post using the +post_path(@post)+ helper. As we have already seen, this calls the +show+ action of the +PostsController+ which in turn renders the +show.html.erb+ template. This is where we want the comment to show, so let's add that to the +app/view/posts/show.html.erb+.
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -1000,11 +1018,11 @@ Now you can add posts and comments to your blog and have them show up in the rig
 
 h3. Refactorization
 
-Now that we have Posts and Comments working, we can take a look at the +app/views/posts/show.html.erb+ template, it is getting long and awkward, we can use partials to clean this up.
+Now that we have Posts and Comments working, if we take a look at the +app/views/posts/show.html.erb+ template, it's getting long and awkward. We can use partials to clean this up.
 
 h4. Rendering Partial Collections
 
-First will make a comment partial to extract showing all the comments for the post, so make a file +app/views/comments/_comment.html.erb+ and put into it:
+First we will make a comment partial to extract showing all the comments for the post. Create the file +app/views/comments/_comment.html.erb+ and put the following into it:
 
 <erb>
 <p>
@@ -1021,6 +1039,8 @@ First will make a comment partial to extract showing all the comments for the po
 Then in the +app/views/posts/show.html.erb+ you can change it to look like the following:
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -1090,6 +1110,8 @@ Lets also move that new comment section out to it's own partial, again, you crea
 Then you make the +app/views/posts/show.html.erb+ look like the following:
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -1120,7 +1142,7 @@ Then you make the +app/views/posts/show.html.erb+ look like the following:
 
 The second render just defines the partial template we want to render, <tt>comments/form</tt>, Rails is smart enough to spot the forward slash in that string and realise that you want to render the <tt>_form.html.erb</tt> file in the <tt>app/views/comments</tt> directory.
 
-The +@post+ object is available any partials rendered in the view because we defined it as an instance variable.
+The +@post+ object is available to any partials rendered in the view because we defined it as an instance variable.
 
 h3. Deleting Comments
 
@@ -1172,7 +1194,7 @@ The +destroy+ action will find the post we are looking at, locate the comment wi
 
 h4. Deleting Associated Objects
 
-If you decide at some point to delete a post, you likely want to delete the comments associated with that post as well. You can do so by taking advantage of the association option +dependent+. All you need to do is modify the +post.rb+ as follows:
+If you delete a post then it's associated comments will also need to be deleted. Otherwise they would simply occupy space in the database. Rails allows you to use the +dependent+ option of an association to achieve this. Modify the Post model, +app/models/post.rb+, as follows:
 
 <ruby>
 class Post < ActiveRecord::Base
@@ -1185,9 +1207,9 @@ end
 
 h3. Security
 
-Before you publish your blog online, you will most likely want to prevent just anyone from being able to add, edit and delete posts or delete comments.
+If you were to publish your blog online, anybody would be able to add, edit and delete posts or delete comments.
 
-Rails provides a very simple http authentication system that will work nicely in this situation.  First, we enable simple HTTP based authentication in our <tt>app/controllers/application_controller.rb</tt>:
+Rails provides a very simple HTTP authentication system that will work nicely in this situation. First, we enable simple HTTP based authentication in our <tt>app/controllers/application_controller.rb</tt>:
 
 <ruby>
 class ApplicationController < ActionController::Base
@@ -1242,7 +1264,7 @@ Now if you try to create a new post, you will be greeted with a basic HTTP Authe
 
 h3. Building a Multi-Model Form
 
-Another piece of your average blog is the ability to tag posts.  This requires that your application edits more than one thing on a single form.  Rails offers support for nested forms.
+Another feature of your average blog is the ability to tag posts. To implement this feature your application needs to interact with more than one model on a single form. Rails offers support for nested forms.
 
 To demonstrate this, we will add support for giving each post multiple tags, right in the form where you create the post. First, create a new model to hold the tags:
 
@@ -1279,7 +1301,16 @@ We will modify +views/posts/_form.html.erb+ to render a partial to make a tag:
 <erb>
 <% @post.tags.build %>
 <%= form_for(@post) do |post_form| %>
-  <%= post_form.error_messages %>
+  <% if @post.errors.any? %>
+  <div id="errorExplanation">
+    <h2><%= pluralize(@post.errors.count, "error") %> prohibited this post from being saved:</h2>
+    <ul>
+    <% @post.errors.full_messages.each do |msg| %>
+      <li><%= msg %></li>
+    <% end %>
+    </ul>
+  </div>
+  <% end %>
 
   <div class="field">
     <%= post_form.label :name %><br />
@@ -1302,16 +1333,16 @@ We will modify +views/posts/_form.html.erb+ to render a partial to make a tag:
 <% end %>
 </erb>
 
-This example shows another option of the render helper, being able to pass in local variables, in this case, we want the local variable +form+ in the partial to refer to the +post_form+ object.
+Note that we have changed the +f+ in +form_for(@post) do |f|+ to +post_form+ to make it easier to understand what is going on.
 
-You will also note that we also have changed the +f+ in <tt>form_for(@post) do |f|</tt> to <tt>post_form</tt> to clarify what is going on somewhat.
+This example shows another option of the render helper, being able to pass in local variables, in this case, we want the local variable +form+ in the partial to refer to the +post_form+ object.
 
 We also add a <tt>@post.tags.build</tt> at the top of this form, this is to make sure there is a new tag ready to have it's name filled in by the user.  If you do not build the new tag, then the form will not appear as there is no new Tag object ready to create.
 
 Now create the folder <tt>app/views/tags</tt> and make a file in there called <tt>_form.html.erb</tt> which contains the form for the tag:
 
 <erb>
-<% form.fields_for :tags do |tag_form| %>
+<%= form.fields_for :tags do |tag_form| %>
   <div class="field">
     <%= tag_form.label :name, 'Tag:' %>
     <%= tag_form.text_field :name %>
@@ -1328,6 +1359,8 @@ Now create the folder <tt>app/views/tags</tt> and make a file in there called <t
 Finally, we will edit the <tt>app/views/posts/show.html.erb</tt> template to show our tags.
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -1381,6 +1414,8 @@ end
 Now you can edit the view in <tt>app/views/posts/show.html.erb</tt> to look like this:
 
 <erb>
+<p class="notice"><%= notice %></p>
+
 <p>
   <b>Name:</b>
   <%= @post.name %>
@@ -1427,14 +1462,36 @@ Rails also comes with built-in help that you can generate using the rake command
 * Running +rake doc:guides+ will put a full copy of the Rails Guides in the +doc/guides+ folder of your application. Open +doc/guides/index.html+ in your web browser to explore the Guides.
 * Running +rake doc:rails+ will put a full copy of the API documentation for Rails in the +doc/api+ folder of your application. Open +doc/api/index.html+ in your web browser to explore the API documentation.
 
+h3. Configuration Gotchas
+
+The easiest way to work with Rails is to store all external data as UTF-8. If you don't, Ruby libraries and Rails will often be able to convert your native data into UTF-8, but this doesn't always work reliably, so you're better off ensuring that all external data is UTF-8.
+
+If you have made a mistake in this area, the most common symptom is a black diamond with a question mark inside appearing in the browser. Another common symptom is characters like "ü" appearing instead of "ü". Rails takes a number of internal steps to mitigate common causes of these problems that can be automatically detected and corrected. However, if you have external data that is not stored as UTF-8, it can occasionally result in these kinds of issues that cannot be automatically detected by Rails and corrected.
+
+Two very common sources of data that are not UTF-8:
+* Your text editor: Most text editors (such as Textmate), default to saving files as
+  UTF-8. If your text editor does not, this can result in special characters that you
+  enter in your templates (such as é) to appear as a diamond with a question mark inside
+  in the browser. This also applies to your I18N translation files.
+  Most editors that do not already default to UTF-8 (such as some versions of
+  Dreamweaver) offer a way to change the default to UTF-8. Do so.
+* Your database. Rails defaults to converting data from your database into UTF-8 at
+  the boundary. However, if your database is not using UTF-8 internally, it may not
+  be able to store all characters that your users enter. For instance, if your database
+  is using Latin-1 internally, and your user enters a Russian, Hebrew, or Japanese
+  character, the data will be lost forever once it enters the database. If possible,
+  use UTF-8 as the internal storage of your database.
 
 h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/2
 
+* May 16, 2010: Added a section on configuration gotchas to address common encoding problems that people might have by "Yehuda Katz":http://www.yehudakatz.com
+* April 30, 2010: Fixes, editing and updating of code samples by "Rohit Arondekar":http://rohitarondekar.com
+* April 25, 2010: Couple of more minor fixups "Mikel Lindsaar":credits.html#raasdnil
 * April 1, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
-* February 8, 2010: Full re-write for Rails 3.0-beta, added helpers and before_filters, refactored code by "Mikel Lindsaar":credits:html#raasdnil
-* January 24, 2010: Re-write for Rails 3.0 by "Mikel Lindsaar":credits:html#raasdnil
+* February 8, 2010: Full re-write for Rails 3.0-beta, added helpers and before_filters, refactored code by "Mikel Lindsaar":credits.html#raasdnil
+* January 24, 2010: Re-write for Rails 3.0 by "Mikel Lindsaar":credits.html#raasdnil
 * July 18, 2009: Minor cleanup in anticipation of Rails 2.3.3 by "Mike Gunderloy":credits.html#mgunderloy
 * February 1, 2009: Updated for Rails 2.3 by "Mike Gunderloy":credits.html#mgunderloy
 * November 3, 2008: Formatting patch from Dave Rothlisberger