Bevy of typo corrections

1 files changed, 44 insertions, 45 deletions

diff --git a/railties/doc/guides/source/form_helpers.txt b/railties/doc/guides/source/form_helpers.txt
index 238115e2f6..095df857a2 100644
--- a/railties/doc/guides/source/form_helpers.txt
+++ b/railties/doc/guides/source/form_helpers.txt
@@ -28,7 +28,7 @@ The most basic form helper is `form_tag`.
 
 When called without arguments like this, it creates a form element that has the current page for action attribute and "POST" as method (some line breaks added for readability):
 
-.Sample rendering of `form_tag`
+.Sample output from `form_tag`
 ----------------------------------------------------------------------------
 <form action="/home/index" method="post">
   <div style="margin:0;padding:0">
@@ -92,9 +92,9 @@ TIP: For every form input, an ID attribute is generated from its name ("q" in th
 Multiple hashes in form helper attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By now you've seen that the `form_tag` helper accepts 2 arguments: the path for the action attribute and an options hash. This hash specifies the method of form submission and HTML  options such as the form element's class.
+By now you've seen that the `form_tag` helper accepts 2 arguments: the path for the action and an options hash. This hash specifies the method of form submission and HTML  options such as the form element's class.
 
-Identical to the `link_to` helper, the path argument doesn't have to be given as string or a named route. It can be a hash of URL parameters that Rails' routing mechanism will turn into a valid URL. Still, you cannot simply write this:
+As with the `link_to` helper, the path argument doesn't have to be given a string. It can be a hash of URL parameters that Rails' routing mechanism will turn into a valid URL. Still, you cannot simply write this:
 
 .A bad way to pass multiple hashes as method arguments
 ----------------------------------------------------------------------------
@@ -207,13 +207,13 @@ then the controller code should use
 ---------------------------
 params[:query]
 ---------------------------
-to retrieve the value entered by the user. When naming inputs be aware that Rails uses certain conventions that control whether values appear at the top level of the params hash, inside an array or a nested hash and so on. You can read more about them in the <<parameter_names,parameter names>> section.
+to retrieve the value entered by the user. When naming inputs be aware that Rails uses certain conventions that control whether values appear at the top level of the params hash, inside an array or a nested hash and so on. You can read more about them in the <<parameter_names,parameter names>> section. For details on the precise usage of these helpers, please refer to the http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html[API documentation].
 
 Model object helpers
 ~~~~~~~~~~~~~~~~~~~~~
-These are designed to work with a model object (commonly an Active Record object but this need not be the case). These lack the _tag suffix, from example `text_field`, `text_area`
+These are designed to work with a model object (commonly an Active Record object but this need not be the case). These lack the _tag suffix, for example `text_field`, `text_area`.
 
-For the latter the first parameter is the name of an instance variable and the second is the name of attribute to be edited. Rails will set the value of the input control to the current value of that attribute for the object and set an appropriate input name. If your controller has defined `@person` and that person's name is Henry then a form containing:
+For these helpers the first arguement is the name of an instance variable and the second is the name a method (usually an attribute) to call on that object. Rails will set the value of the input control to the return value of that method for the object and set an appropriate input name. If your controller has defined `@person` and that person's name is Henry then a form containing:
 
 ---------------------------
 <%= text_field(:person, :name) %>
@@ -222,15 +222,11 @@ will produce output similar to
 ---------------------------
 <input id="person_name" name="person[name]" type="text" value="Henry"/>
 ---------------------------
-The value entered by the user will be stored in
----------------------------
-params[:person][:name]
----------------------------
-The params[:person] hash is suitable for passing to `Person.new` or, if `@person` is an instance of Person, `@person.update_attributes`.
+Upon form submission the value entered by the user will be stored in `params[:person][:name]`. The params[:person] hash is suitable for passing to `Person.new` or, if `@person` is an instance of Person, `@person.update_attributes`.
 
-[NOTE]
+[WARNING]
 ============================================================================
-You must pass the name of an instance variable, i.e. `:person` or `"person"`, not an actual instance of person.
+You must pass the name of an instance variable, i.e. `:person` or `"person"`, not an actual instance of your model object.
 ============================================================================
 Forms that deal with model attributes
 -------------------------------------
@@ -271,19 +267,9 @@ The resulting HTML is:
   <input name="commit" type="submit" value="Create" />
 </form>
 ----------------------------------------------------------------------------
-The name passed to `form_for` used controls where in the params hash the form values will appear. Here the name is `article` and so all the inputs have names of the form `article[attribute_name]`. Accordingly, in the `create` action `params[:article]` will be a hash with keys :title and :body. You can read more about the significance of input names in the <<parameter_names,parameter names>> section.
-
-The helper methods called on the form builder are identical to the model object helpers except that it is not necessary to specify which object is being edited since this is already managed by the form builder. They will pre-fill the form control with the value read from the corresponding attribute in the model. For example, if you created the article instance by supplying an initial value for the title in the controller:
-
-----------------------------------------------------------------------------
-@article = Article.new(:title => "Rails makes forms easy")
-----------------------------------------------------------------------------
+The name passed to `form_for` controls where in the params hash the form values will appear. Here the name is `article` and so all the inputs have names of the form `article[attribute_name]`. Accordingly, in the `create` action `params[:article]` will be a hash with keys `:title` and `:body`. You can read more about the significance of input names in the <<parameter_names,parameter names>> section.
 
-... the corresponding input will be rendered with a value:
-
-----------------------------------------------------------------------------
-<input id="post_title" name="post[title]" size="30" type="text" value="Rails makes forms easy" />
-----------------------------------------------------------------------------
+The helper methods called on the form builder are identical to the model object helpers except that it is not necessary to specify which object is being edited since this is already managed by the form builder.
 
 Relying on record identification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -343,7 +329,7 @@ Here is what our wanted markup might look like:
 </select>
 ----------------------------------------------------------------------------
 
-Here you have a list of cities where their names are presented to the user, but internally you want to handle just their IDs so you keep them in value attributes. Let's see how Rails can help out here.
+Here you have a list of cities where their names are presented to the user, but internally the application only wants to handle their IDs so they are used as the options' value attributes. Let's see how Rails can help out here.
 
 The select tag and options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -399,7 +385,7 @@ Select boxes for dealing with models
 
 Until now you've seen how to make generic select boxes, but in most cases our form controls will be tied to a specific database model. So, to continue from our previous examples, let's assume that you have a "Person" model with a `city_id` attribute.
 
-Consistent with other form helpers, when dealing with models you drop the `"_tag"` suffix from `select_tag` that you used in previous examples:
+Consistent with other form helpers, when dealing with models you drop the `_tag` suffix from `select_tag`.
 
 ----------------------------------------------------------------------------
 # controller:
@@ -420,11 +406,11 @@ As before, if you were to use `select` helper on a form builder scoped to `@pers
 
 [WARNING] 
 =============================
-If you are using `select` (or similar helpers such as `collection_select`, `select_tag`) to set a `belongs_to` association you must pass the name of the foreign key (in the example above `city_id`), not the name of association itself. Active Record will raise an error along the lines of
+If you are using `select` (or similar helpers such as `collection_select`, `select_tag`) to set a `belongs_to` association you must pass the name of the foreign key (in the example above `city_id`), not the name of association itself. If you specify `city` instead of `city_id Active Record will raise an error along the lines of
 --------
 ActiveRecord::AssociationTypeMismatch: City(#17815740) expected, got Fixnum(#1138750)
 --------
-when you pass the params hash to `Person.new` or `update_attributes` if you specify `city` instead of `city_id`. Another way of looking at this is that form helpers only edit attributes.
+when you pass the params hash to `Person.new` or `update_attributes`. Another way of looking at this is that form helpers only edit attributes.
 ============================
 Option tags from a collection of arbitrary objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -481,7 +467,7 @@ Both of these families of helpers will create a series of select boxes for the d
 
 Barebones helpers
 ~~~~~~~~~~~~~~~~~
-The `select_*` family of helpers take as their first argument an instance of Date, Time or DateTime that is used as the currently selected value. You may omit this parameter, in which case the current date is used. for example
+The `select_*` family of helpers take as their first argument an instance of Date, Time or DateTime that is used as the currently selected value. You may omit this parameter, in which case the current date is used. For example
 
 -----------
 <%= select_date Date::today, :prefix => :start_date %>
@@ -496,7 +482,7 @@ The above inputs would result in `params[:start_date]` being a hash with keys :y
 -----------
 Date::civil(params[:start_date][:year].to_i, params[:start_date][:month].to_i, params[:start_date][:day].to_i)
 -----------
-The :prefix option controls where in the params hash the date components will be placed. Here it was set to `start_date`, if omitted it will default to `date`
+The :prefix option controls where in the params hash the date components will be placed. Here it was set to `start_date`, if omitted it will default to `date`.
 
 Model object helpers
 ~~~~~~~~~~~~~~~~~~~~
@@ -512,10 +498,9 @@ outputs (with the actual option values omitted for brevity)
 <select id="person_birth_date_3i" name="person[birth_date(3i)]"> ... </select>
 --------------
 which results in a params hash like
-[source, ruby]
--------------
+--------------
 {:person => {'birth_date(1i)' => '2008', 'birth_date(2i)' => '11', 'birth_date(3i)' => '22'}}
--------------
+--------------
 
 When this is passed to `Person.new`, Active Record spots that these parameters should all be used to construct the `birth_date` attribute and uses the suffixed information to determine in which order it should pass these parameters to functions such as `Date::civil`.
 
@@ -523,9 +508,9 @@ Common options
 ~~~~~~~~~~~~~~
 Both families of helpers use the same core set of functions to generate the individual select tags and so both accept largely the same options. In particular, by default Rails will generate year options 5 years either side of the current year. If this is not an appropriate range, the `:start_year` and `:end_year` options override this. For an exhaustive list of the available options, refer to the http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html[API documentation].
 
-As a rule of thumb you should be using `date_select` when working with model objects and `select_date` in others cases, such as a search for which filters results by date.
+As a rule of thumb you should be using `date_select` when working with model objects and `select_date` in others cases, such as a search form which filters results by date.
 
-NOTE:In many cases the built in date pickers are clumsy as they do not aid the user in working out the relationship between the date and the day of the week
+NOTE: In many cases the built in date pickers are clumsy as they do not aid the user in working out the relationship between the date and the day of the week.
 
 Form builders
 -------------
@@ -544,6 +529,8 @@ can be replaced with
 <% end %>
 ----------
 by defining a LabellingFormBuilder class similar to the following:
+
+[source, ruby]
 -------
 class LabellingFormBuilder < FormBuilder
   def text_field attribute, options={}
@@ -583,11 +570,11 @@ which produces the following output:
 
 File Uploads
 --------------
-A common task is uploaded some sort of file, whether it's a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the form's encoding *MUST* be set to multipart/form-data. If you forget to do this the file will not be uploaded. This can be done by passing `:multi_part => true` as an HTML option. This means that in the case of `form_tag` it must be passed in the second options hash and in the case of `form_for` inside the `:html` hash.
+A common task is uploading some sort of file, whether it's a picture of a person or a CSV file containing data to process. The most important thing to remember with file uploads is that the form's encoding *MUST* be set to multipart/form-data. If you forget to do this the file will not be uploaded. This can be done by passing `:multi_part => true` as an HTML option. This means that in the case of `form_tag` it must be passed in the second options hash and in the case of `form_for` inside the `:html` hash.
 
 The following two forms both upload a file. 
 -----------
-<% form_tag({:action => :upload}, :multipart => true)  do %>
+<% form_tag({:action => :upload}, :multipart => true) do %>
   <%= file_field_tag 'picture' %>
 <% end %>
 
@@ -601,6 +588,7 @@ What gets uploaded
 ~~~~~~~~~~~~~~~~~~
 The object in the params hash is an instance of a subclass of IO. Depending on the size of the uploaded file it may in fact be a StringIO or an instance of File backed by a temporary file. In both cases the object will have an `original_filename` attribute containing the name the file had on the user's computer and a `content_type` attribute containing the MIME type of the uploaded file. The following snippet saves the uploaded content in `#\{RAILS_ROOT\}/public/uploads` under the same name as the original file (assuming the form was the one in the previous example).
 
+[source, ruby]
 -----------------
 def upload
   uploaded_io = params[:person][:picture]
@@ -625,12 +613,15 @@ action for a Person model, `params[:model]` would usually be a hash of all the a
 Fundamentally HTML forms don't know about any sort of structured data. All they know about is name-value pairs. Rails tacks some conventions onto parameter names which it uses to express some structure.
 
 [TIP]
-==============
+========================
 You may find you can try out examples in this section faster by using the console to directly invoke Rails' parameter parser. For example
+
 -------------
-ActionController::RequestParser.parse_query_parameters "name=fred&phone=0123456789" #=> {"name"=>"fred", "phone"=>"0123456789"}
+ActionController::RequestParser.parse_query_parameters "name=fred&phone=0123456789"
+#=> {"name"=>"fred", "phone"=>"0123456789"}
 -------------
-==============
+========================
+
 Basic structures
 ~~~~~~~~~~~~~~~
 The two basic structures are arrays and hashes. Hashes mirror the syntax used for accessing the value in the params. For example if a form contains
@@ -638,19 +629,25 @@ The two basic structures are arrays and hashes. Hashes mirror the syntax used fo
 <input id="person_name" name="person[name]" type="text" value="Henry"/>
 -----------------
 the params hash will contain
+
+[source, ruby]
 -----------------
 {'person' => {'name' => 'Henry'}}
 -----------------
+and `params[\'name\']` will retrieve the submitted value in the controller.
+
 Hashes can be nested as many levels as required, for example
 ------------------
 <input id="person_address_city" name="person[address][city]" type="text" value="New York"/>
 ------------------
 will result in the params hash being
+
+[source, ruby]
 -----------------
 {'person' => {'address' => {'city' => 'New York'}}}
 -----------------
 
-Normally Rails ignores duplicate parameter names. If the parameter name contains [] then they will be accumulated in an array. If we wanted people to be able to input multiple phone numbers, we could place this in our form:
+Normally Rails ignores duplicate parameter names. If the parameter name contains [] then they will be accumulated in an array. If you wanted people to be able to input multiple phone numbers, your could place this in the form:
 -----------------
 <input name="person[phone_number][]" type="text"/>
 <input name="person[phone_number][]" type="text"/>
@@ -660,13 +657,13 @@ This would result in `params[:person][:phone_number]` being an array.
 
 Combining them
 ~~~~~~~~~~~~~~
-We can mix and match these two concepts. For example, one element of a hash might be an array as in previous example, or you can have an array of hashes. For example a form might let you create any number of addresses by repeating the following form fragment
+We can mix and match these two concepts. For example, one element of a hash might be an array as in the previous example, or you can have an array of hashes. For example a form might let you create any number of addresses by repeating the following form fragment
 -----------------
 <input name="addresses[][line1]" type="text"/>
 <input name="addresses[][line2]" type="text"/>
 <input name="addresses[][city]" type="text"/>
 -----------------
-This would result in `params[:addresses]` being an array of hashes with keys `line1, `line2` and `city`. Rails decides to start accumulating values in a new hash whenever it encounters a input name that already exists in the current hash.
+This would result in `params[:addresses]` being an array of hashes with keys `line1`, `line2` and `city`. Rails decides to start accumulating values in a new hash whenever it encounters a input name that already exists in the current hash.
 
 The one restriction is that although hashes can be nested arbitrarily deep then can be only one level of "arrayness". Frequently arrays can be usually replaced by hashes, for example instead of having an array of model objects one can have a hash of model objects keyed by their id.
 
@@ -698,11 +695,13 @@ Assuming our person had two addresses, with ids 23 and 45 this would create outp
 </form>
 --------
 This will result in a params hash that looks like
+
+[source, ruby]
 --------
 {'person' => {'name' => 'Bob', 'address' => { '23' => {'city' => 'Paris'}, '45' => {'city' => 'London'} }}}
 --------
 
-Rails knows that all these inputs should be part of the person hash because you called `fields_for` on the first form builder. By specifying an `:index` option you're telling rails that instead of naming the inputs `person[address][city]` it should insert a [] between the address and the city, with the appropriate index value. If you pass an Active Record object as we did then Rails will call `to_param` on it, which by default returns the database id. This is often useful it is then easy to locate which Address record should be modified but you could pass numbers with some other significance, strings or even nil (which will result in an array parameter being created).
+Rails knows that all these inputs should be part of the person hash because you called `fields_for` on the first form builder. By specifying an `:index` option you're telling rails that instead of naming the inputs `person[address][city]` it should insert that index surrounded by [] between the address and the city. If you pass an Active Record object as we did then Rails will call `to_param` on it, which by default returns the database id. This is often useful it is then easy to locate which Address record should be modified but you could pass numbers with some other significance, strings or even nil (which will result in an array parameter being created).
 
 To create more intricate nestings, you can specify the first part of the input name (`person[address]` in the previous example) explicitly, for example
 --------