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

15 files changed, 143 insertions, 99 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 085afb57c1..cb289fd693 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -122,18 +122,19 @@ module ActionMailer #:nodoc:
   #
   #   <%= users_url(:host => "example.com") %>
   #
-  # You want to avoid using the <tt>name_of_route_path</tt> form of named routes because it doesn't
-  # make sense to generate relative URLs in email messages.
+  # You should use the <tt>named_route_url</tt> style (which generates absolute URLs) and avoid using the 
+  # <tt>named_route_path</tt> style (which generates relative URLs), since clients reading the mail will 
+  # have no concept of a current URL from which to determine a relative path.
   #
   # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt>
   # option as a configuration option in <tt>config/application.rb</tt>:
   #
   #   config.action_mailer.default_url_options = { :host => "example.com" }
   #
-  # If you do decide to set a default <tt>:host</tt> for your mailers you want to use the
-  # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. This will ensure that absolute URLs are
-  # generated because the <tt>url_for</tt> view helper will, by default, generate relative URLs when a
-  # <tt>:host</tt> option isn't explicitly provided.
+  # When you decide to set a default <tt>:host</tt> for your mailers, then you need to make sure to use the
+  # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. Since the <tt>url_for</tt> view helper 
+  # will generate relative URLs by default when a <tt>:host</tt> option isn't explicitly provided, passing
+  # <tt>:only_path => false</tt> will ensure that absolute URLs are generated.
   #
   # = Sending mail
   #
@@ -148,9 +149,9 @@ module ActionMailer #:nodoc:
   #
   # = Multipart Emails
   #
-  # Multipart messages can also be used implicitly because Action Mailer will automatically
-  # detect and use multipart templates, where each template is named after the name of the action, followed
-  # by the content type. Each such detected template will be added as separate part to the message.
+  # Multipart messages can also be used implicitly because Action Mailer will automatically detect and use 
+  # multipart templates, where each template is named after the name of the action, followed by the content 
+  # type. Each such detected template will be added as a separate part to the message.
   #
   # For example, if the following templates exist:
   # * signup_notification.text.erb
@@ -732,3 +733,4 @@ module ActionMailer #:nodoc:
     ActiveSupport.run_load_hooks(:action_mailer, self)
   end
 end
+
diff --git a/actionmailer/lib/action_mailer/delivery_methods.rb b/actionmailer/lib/action_mailer/delivery_methods.rb
index b324ba790d..d1467fb526 100644
--- a/actionmailer/lib/action_mailer/delivery_methods.rb
+++ b/actionmailer/lib/action_mailer/delivery_methods.rb
@@ -1,7 +1,7 @@
 require 'tmpdir'
 
 module ActionMailer
-  # This modules handles everything related to the delivery, from registering new
+  # This module handles everything related to mail delivery, from registering new
   # delivery methods to configuring the mail object to be sent.
   module DeliveryMethods
     extend ActiveSupport::Concern
diff --git a/actionpack/lib/abstract_controller/layouts.rb b/actionpack/lib/abstract_controller/layouts.rb
index 8f73e244d7..d6f75bded0 100644
--- a/actionpack/lib/abstract_controller/layouts.rb
+++ b/actionpack/lib/abstract_controller/layouts.rb
@@ -81,11 +81,12 @@ module AbstractController
   #   class EmployeeController < BankController
   #     layout nil
   #
-  # The InformationController uses "bank_standard" inherited from the BankController, the VaultController overwrites
-  # and picks the layout dynamically, and the EmployeeController doesn't want to use a layout at all.
-  #
-  # The TellerController uses +teller.html.erb+, and TillController inherits that layout and
-  # uses it as well.
+  # In these examples:
+  # * The InformationController uses the "bank_standard" layout, inherited from BankController.
+  # * The TellerController follows convention and uses +app/views/layouts/teller.html.erb+.
+  # * The TillController inherits the layout from TellerController and uses +teller.html.erb+ as well.
+  # * The VaultController chooses a layout dynamically by calling the <tt>access_level_layout</tt> method.
+  # * The EmployeeController does not use a layout at all.
   #
   # == Types of layouts
   #
@@ -138,8 +139,8 @@ module AbstractController
   #
   #   end
   #
-  # This will assign "weblog_standard" as the WeblogController's layout  except for the +rss+ action, which will not wrap a layout
-  # around the rendered view.
+  # This will assign "weblog_standard" as the WeblogController's layout for all actions except for the +rss+ action, which will 
+  # be rendered directly, without wrapping a layout around the rendered view.
   #
   # Both the <tt>:only</tt> and <tt>:except</tt> condition can accept an arbitrary number of method references, so
   # #<tt>:except => [ :rss, :text_only ]</tt> is valid, as is <tt>:except => :rss</tt>.
@@ -158,7 +159,7 @@ module AbstractController
   #     end
   #   end
   #
-  # This will render the help action with the "help" layout instead of the controller-wide "weblog_standard" layout.
+  # This will override the controller-wide "weblog_standard" layout, and will render the help action with the "help" layout instead.
   module Layouts
     extend ActiveSupport::Concern
 
diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb
index c03c77cb4a..d14c5f940b 100644
--- a/actionpack/lib/action_controller/base.rb
+++ b/actionpack/lib/action_controller/base.rb
@@ -31,7 +31,7 @@ module ActionController
   # "302 Moved" HTTP response that takes the user to the index action.
   #
   # These two methods represent the two basic action archetypes used in Action Controllers. Get-and-show and do-and-redirect.
-  # Most actions are variations of these themes.
+  # Most actions are variations on these themes.
   #
   # == Requests
   #
@@ -116,8 +116,8 @@ module ActionController
   #
   #   Title: <%= @post.title %>
   #
-  # You don't have to rely on the automated rendering. Especially actions that could result in the rendering of different templates will use
-  # the manual rendering methods:
+  # You don't have to rely on the automated rendering. For example, actions that could result in the rendering of different templates 
+  # will use the manual rendering methods:
   #
   #   def search
   #     @results = Search.find(params[:query])
@@ -132,9 +132,9 @@ module ActionController
   #
   # == Redirects
   #
-  # Redirects are used to move from one action to another. For example, after a <tt>create</tt> action, which stores a blog entry to a database,
-  # we might like to show the user the new entry. Because we're following good DRY principles (Don't Repeat Yourself), we're going to reuse (and redirect to)
-  # a <tt>show</tt> action that we'll assume has already been created. The code might look like this:
+  # Redirects are used to move from one action to another. For example, after a <tt>create</tt> action, which stores a blog entry to the
+  # database, we might like to show the user the new entry. Because we're following good DRY principles (Don't Repeat Yourself), we're 
+  # going to reuse (and redirect to) a <tt>show</tt> action that we'll assume has already been created. The code might look like this:
   #
   #   def create
   #     @entry = Entry.new(params[:entry])
@@ -146,7 +146,9 @@ module ActionController
   #     end
   #   end
   #
-  # In this case, after saving our new entry to the database, the user is redirected to the <tt>show</tt> method which is then executed.
+  # In this case, after saving our new entry to the database, the user is redirected to the <tt>show</tt> method, which is then executed.
+  # Note that this is an external HTTP-level redirection which will cause the browser to make a second request (a GET to the show action),
+  # and not some internal re-routing which calls both "create" and then "show" within one request.
   #
   # Learn more about <tt>redirect_to</tt> and what options you have in ActionController::Redirecting.
   #
diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 4a411caabc..d70ae4196b 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -55,9 +55,9 @@ module ActionView
       #
       # ==== Relying on named routes
       #
-      # If you instead of a hash pass a record (like an Active Record or Active Resource) as the options parameter,
-      # you'll trigger the named route for that record. The lookup will happen on the name of the class. So passing
-      # a Workshop object will attempt to use the +workshop_path+ route. If you have a nested route, such as
+      # Passing a record (like an Active Record or Active Resource) instead of a Hash as the options parameter will 
+      # trigger the named route for that record. The lookup will happen on the name of the class. So passing a 
+      # Workshop object will attempt to use the +workshop_path+ route. If you have a nested route, such as
       # +admin_workshop_path+ you'll have to call that explicitly (it's impossible for +url_for+ to guess that route).
       #
       # ==== Examples
@@ -112,13 +112,13 @@ module ActionView
         end
       end
 
-      # Creates a link tag of the given +name+ using a URL created by the set
-      # of +options+. See the valid options in the documentation for
-      # +url_for+. It's also possible to pass a string instead
-      # of an options hash to get a link tag that uses the value of the string as the
-      # href for the link, or use <tt>:back</tt> to link to the referrer - a JavaScript back
-      # link will be used in place of a referrer if none exists. If +nil+ is passed as
-      # a name, the link itself will become the name.
+      # Creates a link tag of the given +name+ using a URL created by the set of +options+.
+      # See the valid options in the documentation for +url_for+. It's also possible to 
+      # pass a String instead of an options hash, which generates a link tag that uses the
+      # value of the String as the href for the link. Using a <tt>:back</tt> Symbol instead
+      # of an options hash will generate a link to the referrer (a JavaScript back link
+      # will be used in place of a referrer if none exists). If +nil+ is passed as the name
+      # the value of the link itself will become the name.
       #
       # ==== Signatures
       #
diff --git a/activesupport/lib/active_support/backtrace_cleaner.rb b/activesupport/lib/active_support/backtrace_cleaner.rb
index 0e6bc30fa2..8f8deb9692 100644
--- a/activesupport/lib/active_support/backtrace_cleaner.rb
+++ b/activesupport/lib/active_support/backtrace_cleaner.rb
@@ -1,12 +1,12 @@
 module ActiveSupport
-  # Many backtraces include too much information that's not relevant for the context. This makes it hard to find the signal
-  # in the backtrace and adds debugging time. With a BacktraceCleaner, you can setup filters and silencers for your particular
-  # context, so only the relevant lines are included.
+  # Backtraces often include many lines that are not relevant for the context under review. This makes it hard to find the 
+  # signal amongst the backtrace noise, and adds debugging time. With a BacktraceCleaner, filters and silencers are used to
+  # remove the noisy lines, so that only the most relevant lines remain.
   #
-  # If you need to reconfigure an existing BacktraceCleaner, like the one in Rails, to show as much as possible, you can always
-  # call BacktraceCleaner#remove_silencers! Also, if you need to reconfigure an existing BacktraceCleaner so that it does not
-  # filter or modify the paths of any lines of the backtrace, you can call BacktraceCleaner#remove_filters! These two methods
-  # will give you a completely untouched backtrace.
+  # Filters are used to modify lines of data, while silencers are used to remove lines entirely.  The typical filter use case
+  # is to remove lengthy path information from the start of each line, and view file paths relevant to the app directory 
+  # instead of the file system root.  The typical silencer use case is to exclude the output of a noisy library from the 
+  # backtrace, so that you can focus on the rest.
   #
   # ==== Example:
   #
@@ -15,13 +15,18 @@ module ActiveSupport
   #   bc.add_silencer { |line| line =~ /mongrel|rubygems/ }
   #   bc.clean(exception.backtrace) # will strip the Rails.root prefix and skip any lines from mongrel or rubygems
   #
+  # To reconfigure an existing BacktraceCleaner (like the default one in Rails) and show as much data as possible, you can 
+  # always call <tt>BacktraceCleaner#remove_silencers!</tt>, which will restore the backtrace to a pristine state.  If you 
+  # need to reconfigure an existing BacktraceCleaner so that it does not filter or modify the paths of any lines of the 
+  # backtrace, you can call BacktraceCleaner#remove_filters! These two methods will give you a completely untouched backtrace.
+  #
   # Inspired by the Quiet Backtrace gem by Thoughtbot.
   class BacktraceCleaner
     def initialize
       @filters, @silencers = [], []
     end
 
-    # Returns the backtrace after all filters and silencers has been run against it. Filters run first, then silencers.
+    # Returns the backtrace after all filters and silencers have been run against it. Filters run first, then silencers.
     def clean(backtrace, kind = :silent)
       filtered = filter(backtrace)
 
@@ -45,8 +50,8 @@ module ActiveSupport
       @filters << block
     end
 
-    # Adds a silencer from the block provided. If the silencer returns true for a given line, it'll be excluded from the
-    # clean backtrace.
+    # Adds a silencer from the block provided. If the silencer returns true for a given line, it will be excluded from 
+    # the clean backtrace.
     #
     # Example:
     #
@@ -57,7 +62,7 @@ module ActiveSupport
     end
 
     # Will remove all silencers, but leave in the filters. This is useful if your context of debugging suddenly expands as
-    # you suspect a bug in the libraries you use.
+    # you suspect a bug in one of the libraries you use.
     def remove_silencers!
       @silencers = []
     end
diff --git a/activesupport/lib/active_support/log_subscriber.rb b/activesupport/lib/active_support/log_subscriber.rb
index 1c4dd24227..6296c1d4b8 100644
--- a/activesupport/lib/active_support/log_subscriber.rb
+++ b/activesupport/lib/active_support/log_subscriber.rb
@@ -3,8 +3,8 @@ require 'active_support/core_ext/class/attribute'
 
 module ActiveSupport
   # ActiveSupport::LogSubscriber is an object set to consume ActiveSupport::Notifications
-  # with solely purpose of logging. The log subscriber dispatches notifications to a
-  # registered object based on its given namespace.
+  # with the sole purpose of logging them. The log subscriber dispatches notifications to 
+  # a registered object based on its given namespace.
   #
   # An example would be Active Record log subscriber responsible for logging queries:
   #
@@ -109,8 +109,8 @@ module ActiveSupport
 
     # Set color by using a string or one of the defined constants. If a third
     # option is set to true, it also adds bold to the string. This is based
-    # on Highline implementation and it automatically appends CLEAR to the end
-    # of the returned String.
+    # on the Highline implementation and will automatically append CLEAR to the
+    # end of the returned String.
     #
     def color(text, color, bold=false)
       return text unless colorize_logging
diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile
index b4ce60fcaa..e3871a3c34 100644
--- a/railties/guides/source/active_record_querying.textile
+++ b/railties/guides/source/active_record_querying.textile
@@ -57,6 +57,7 @@ The methods are:
 * +group+
 * +order+
 * +reorder+
+* +reverse_order+
 * +limit+
 * +offset+
 * +joins+
@@ -550,6 +551,32 @@ In case the +reorder+ clause is not used, the SQL executed would be:
 SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC
 </sql>
 
+h4. +reverse_order+
+
+The +reverse_order+ method reverses the ordering clause if specified.
+
+<ruby>
+Client.where("orders_count > 10").order(:name).reverse_order
+</ruby>
+
+The SQL that would be executed:
+<sql>
+SELECT * FROM clients WHERE orders_count > 10 ORDER BY name DESC
+</sql>
+
+If no ordering clause is specified in the query, the +reverse_order+ orders by the primary key in reverse order.
+
+<ruby>
+Client.where("orders_count > 10").reverse_order
+</ruby>
+
+The SQL that would be executed:
+<sql>
+SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC
+</sql>
+
+This method accepts *no* arguments.
+
 h3. Readonly Objects
 
 Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 221d20fee6..7f33cc4df5 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -947,7 +947,7 @@ h4. Class Attributes
 
 h5. +class_attribute+
 
-The method +class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy:
+The method +class_attribute+ declares one or more inheritable class attributes that can be overridden at any level down the hierarchy.
 
 <ruby>
 class A
@@ -983,7 +983,7 @@ self.default_params = {
 }.freeze
 </ruby>
 
-They can be also accessed and overridden at the instance level:
+They can be also accessed and overridden at the instance level.
 
 <ruby>
 A.x = 1
@@ -996,7 +996,7 @@ a1.x # => 1, comes from A
 a2.x # => 2, overridden in a2
 </ruby>
 
-The generation of the writer instance method can be prevented by setting the option +:instance_writer+ to false, as in
+The generation of the writer instance method can be prevented by setting the option +:instance_writer+ to +false+.
 
 <ruby>
 module ActiveRecord
@@ -1009,8 +1009,20 @@ end
 
 A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
 
+The generation of the reader instance method can be prevented by setting the option +:instance_reader+ to +false+.
+
+<ruby>
+class A
+  class_attribute :x, :instance_reader => false
+end
+
+A.x = 1 # NoMethodError
+</ruby>
+
 For convenience +class_attribute+ also defines an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called +x?+.
 
+When +:instance_reader+ is +false+, the instance predicate returns a +NoMethodError+ just like the reader method.
+
 NOTE: Defined in +active_support/core_ext/class/attribute.rb+
 
 h5. +cattr_reader+, +cattr_writer+, and +cattr_accessor+
diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile
index 1b444811a2..78683b743c 100644
--- a/railties/guides/source/asset_pipeline.textile
+++ b/railties/guides/source/asset_pipeline.textile
@@ -6,30 +6,28 @@ By referring to this guide you will be able to:
 * Understand what the asset pipeline is and what it does
 * Properly organize your application assets
 * Understand the benefits of the asset pipeline
-* Adding a preprocessor to the pipeline
+* Adding a pre-processor to the pipeline
 * Package assets with a gem
 
 endprologue.
 
 h3. What Is The Asset Pipeline?
 
-With Rails 3.1 comes a new feature known as the asset pipeline. The asset pipeline provides features that have usually been implemented by external gems, such as Jammit and Sprockets. These gems would serve concatenated or compressed versions of the assets of an application, such as stylesheets or javascript files so that the number of requests made to the server are lessened, making the page load faster.
-
-By having this now as a core feature of Rails, all developers can benefit from the power of having their assets pre-processed, compressed and minified by one central gem, Sprockets.
+With Rails 3.1 comes a new feature known as the asset pipeline. The asset pipeline provides features that have usually been implemented by external gems, such as "Jammit":http://documentcloud.github.com/jammit and "Sprockets.":http://getsprockets.org  These gems are popular for being able to serve concatenated or compressed versions of the assets of an application, such as Cascade Style Sheets (CSS) or JavaScript (JS) files so that the number of requests made to the server are reduced, making the page load faster. Rails 3.1 includes the Sprockets gem.
 
 h3. How to Use the Asset Pipeline
 
-In previous versions of Rails, all assets lived under the +public+ directory in directories such as +images+, +javascripts+ and +stylesheets+. With Rails 3.1, the preferred location for these assets is now the +app/assets+ directory. Files in this directory will be served by the Sprockets middleware included in the sprockets gem.
+In previous versions of Rails, all assets lived under the +public+ directory in directories such as +images+, +javascripts+ and +stylesheets+. With the asset pipeline, the preferred location for these assets is now the +app/assets+ directory. Files in this directory will be served by the Sprockets middleware included in the sprockets gem.
 
 This is not to say that assets can (or should) no longer be placed in +public+. They still can be, they will just be served by the application or the web server which is running the application and served just like normal files. You would only use +app/assets+ if you wish your files to undergo some pre-processing before they are served.
 
-When a scaffold or controller is generated for the application, Rails will also generate a JavaScript (or CoffeeScript if the +coffee-script+ gem is in the +Gemfile+) and CSS (or SCSS if +sass-rails+ is in the +Gemfile+) file for that controller. For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. It's in these files that JavaScript and CSS unique to this part of the application belong.
+When a scaffold or controller is generated for the application, Rails will also generate a JavaScript file (or CoffeeScript if the +coffee-script+ gem is in the +Gemfile+) and a Cascade Style Sheet file (or SCSS if +sass-rails+ is in the +Gemfile+) file for that controller. For example, if a +ProjectsController+ is generated, there will be a new file at +app/assets/javascripts/projects.js.coffee+ and another at +app/assets/stylesheets/projects.css.scss+. You should put any JavaScript or CSS unique to a controller inside their respective asset files.
 
 h4. Asset Organization
 
 Assets can be placed inside an application in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+.
 
-+app/assets+ is for assets that are owned by the application, such as custom images, javascript files or stylesheets.
++app/assets+ is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets.
 
 +lib/assets+ is for your own libraries' code that doesn't really fit into the scope of the application or those libraries which are shared across applications.
 
@@ -39,7 +37,7 @@ Any subdirectory that exists within these three locations will be added to the s
 
 h4. External Assets
 
-Assets can also come from external sources such as engines. A good example of this is the +jquery_rails+ gem which comes with Rails 3.1 as standard. This gem contains an engine class which inherits from +Rails::Engine+. By doing this, Rails is informed that the directory for this gem may contain assets and the +app/assets+, +lib/assets+ and +vendor/assets+ directories of this engine are added to the search path of Sprockets.
+Assets can also come from external sources such as engines. A good example of this is the +jquery-rails+ gem which comes with Rails as the standard JavaScript library gem. This gem contains an engine class which inherits from +Rails::Engine+. By doing this, Rails is informed that the directory for this gem may contain assets and the +app/assets+, +lib/assets+ and +vendor/assets+ directories of this engine are added to the search path of Sprockets.
 
 h4. Serving Assets
 
@@ -49,21 +47,9 @@ To serve assets, we can use the same tags that we are generally familiar with:
   <%= image_tag "rails.png" %>
 </erb>
 
-Providing that assets are enabled within our application (+Rails.application.config.assets.enabled+ is set to +true+), this file will be served by Sprockets unless a file at +public/images/rails.png+ exists, in which case that file will be served. If there is no file at +public/images+, Sprockets will look through the available paths until it finds a file that matches the name and then will serve it, first looking in the application's assets directories and then falling back to the various engines of the application.
-
-To include a JavaScript file we can still use the familiar +javascript_include_tag+.
-
-<erb>
-  <%= javascript_include_tag "application" %>
-</erb>
-
-Similarly, to include a CSS file we can also still use +stylesheet_link_tag+.
-
-<erb>
-  <%= stylesheet_link_tag "application" %>
-</erb>
+Providing that assets are enabled within our application (+config.assets.enabled+ in your environment is set to +true+), this file will be served by Sprockets unless a file at +public/assets/rails.png+ exists, in which case that file will be served. Otherwise, Sprockets will look through the available paths until it finds a file that matches the name and then will serve it, first looking in the application's assets directories and then falling back to the various engines of the application.
 
-These files could just be straight JavaScript or CSS files, or they could be _manifest files_.
+Sprockets does not add any new methods to require your assets, we still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+. You can use it to include from the normal public directory or the assets directory.
 
 h4. Manifest Files and Directives
 
@@ -72,22 +58,22 @@ Sprockets allows some assets to be manifest files. These manifest files require
 For example, in the default Rails application there's a +app/assets/javascripts/application.js+ file which contains the following lines:
 
 <plain>
-  //= require jquery
-  //= require jquery_ujs
-  //= require_tree .
+//= require jquery
+//= require jquery_ujs
+//= require_tree .
 </plain>
 
-In JS files, directives begin with +//=+. In this case, the file is using the +require+ directive twice and the +require_tree+ directive once. The +require+ directive tells Sprockets that we would like to require a file called +jquery.js+ that is available somewhere in the search path for Sprockets. By default, this is located inside the +vendor/assets/javascripts+ directory contained within the +jquery_rails+ gem. An identical event takes place for the +jquery_ujs+ require specified here also.
+In JavaScript files, directives begin with +//=+. In this case, the following file is using the +require+ directive and the +require_tree+ directive. The +require+ directive tells Sprockets that we would like to require a file called +jquery.js+ that is available somewhere in the search path for Sprockets. By default, this is located inside the +vendor/assets/javascripts+ directory contained within the +jquery-rails+ gem. An identical event takes place for the +jquery_ujs+ require specified here also.
 
-The +require_tree .+ directive tells Sprockets to include _all_ JavaScript files in this directory into the output. A path relative to the file can be specified if only certain files are required to be loaded.
+The +require_tree .+ directive tells Sprockets to include _all_ JavaScript files in this directory into the output. Only a path relative to the file can be specified.
 
 There's also a default +app/assets/stylesheets/application.css+ file which contains these lines:
 
 <plain>
-  /* ...
-  *= require_self
-  *= require_tree .
-  */
+/* ...
+*= require_self
+*= require_tree .
+*/
 </plain>
 
 The directives that work in the JavaScript files will also work in stylesheets, obviously requiring stylesheets rather than JavaScript files. The +require_tree+ directive here works the same way as the JavaScript one, requiring all stylesheets from the current directory.
@@ -98,7 +84,7 @@ h4. Preprocessing
 
 Based on the extensions of the assets, Sprockets will do preprocessing on the files. With the default gemset that comes with Rails, when a controller or a scaffold is generated, a CoffeeScript file and a SCSS file will be generated in place of a regular JavaScript and CSS file. The example used before was a controller called "projects", which generated an +app/assets/javascripts/projects.js.coffee+ and a +app/assets/stylesheets/projects.css.scss+ file.
 
-When these files are requested, they will be processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and SCSS respectively.
+When these files are requested, they will be processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and CSS respectively.
 
 In addition to this single layer of pre-processing, we can also put on additional extensions to the end of the file in order for them to be processed using other languages first. For example, we could call our stylesheet +app/assets/stylesheets/projects.css.scss.erb+ it would first be processed as ERB, then SCSS and finally served as CSS. We could also do this with our JavaScript file, calling it +app/assets/javascripts/projects.js.coffee.erb+.
 
@@ -106,4 +92,15 @@ Keep in mind that the order of these pre-processors is important. For example, i
 
 h4. Compressing Assets
 
-WIP: Compressed Assets in Rails are served ... how? 
\ No newline at end of file
+The default Gemfile also includes the "uglifier":https://github.com/lautis/uglifier gem. This gem wraps "UglifierJS":https://github.com/mishoo/UglifyJS (written for NodeJS) in Ruby. It compress your code by removing white spaces and other magical things like changing your if and else statements to ternary operators when possible. 
+
+Sprockets also turns on "Gzip":http://en.wikipedia.org/wiki/Gzip (.gz) when possible (by checking the user's headers). Gzip is a file compression technique, much like the ever so popular "zip" file, except it's more open source friendly. Gzip should not modify the contents of the file, but simply the size of the file.
+
+h4. Adding Assets to Your Gems
+
+To include your assets inside of a gem, simple package it in +lib/assets+ as you would in +app/assets+. You should append or prepend the name of your gem though, this should help avoid name conflicts with other gems or the user's application.
+
+h4. Making Your Library or Gem a Pre-Processor
+
+"You should be able to register [your gems] on Tilt and Sprockets will find them." - Josh 
+Tilt: https://github.com/rtomayko/tilt
\ No newline at end of file
diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile
index 458bfefad8..3c2497e83a 100644
--- a/railties/guides/source/association_basics.textile
+++ b/railties/guides/source/association_basics.textile
@@ -1120,11 +1120,9 @@ h6(#has_many-collection-find). <tt><em>collection</em>.find(...)</tt>
 The <tt><em>collection</em>.find</tt> method finds objects within the collection. It uses the same syntax and options as +ActiveRecord::Base.find+.
 
 <ruby>
-@open_orders = @customer.orders.all(:conditions => "open = 1")
+@open_orders = @customer.orders.where(:open => 1)
 </ruby>
 
-NOTE: Starting Rails 3, supplying options to +ActiveRecord::Base.find+ method is discouraged. Use <tt><em>collection</em>.where</tt> instead when you need to pass conditions.
-
 h6(#has_many-collection-where). <tt><em>collection</em>.where(...)</tt>
 
 The <tt><em>collection</em>.where</tt> method finds objects within the collection based on the conditions supplied but the objects are loaded lazily meaning that the database is queried only when the object(s) are accessed.
diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile
index c7e45c0a23..4314d00f2e 100644
--- a/railties/guides/source/form_helpers.textile
+++ b/railties/guides/source/form_helpers.textile
@@ -777,7 +777,7 @@ If you need to post some data to an external resource it is still great to build
 Sometimes when you submit data to an external resource, like payment gateway, fields you can use in your form are limited by an external API. So you may want not to generate an +authenticity_token+ hidden field at all. For doing this just pass +false+ to the +:authenticity_token+ option:
 
 <erb>
-<%= form_tag 'http://farfar.away/form', :authenticity_token => 'external_token') do %>
+<%= form_tag 'http://farfar.away/form', :authenticity_token => false) do %>
   Form contents
 <% end %>
 </erb>
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index 3011f7136b..6aca5d3420 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -5,7 +5,7 @@ This guide covers getting up and running with Ruby on Rails. After reading it, y
 * Installing Rails, creating a new Rails application, and connecting your application to a database
 * The general layout of a Rails application
 * The basic principles of MVC (Model, View Controller) and RESTful design
-* How to quickly generate the starting pieces of a Rails application.
+* How to quickly generate the starting pieces of a Rails application
 
 endprologue.
 
@@ -205,8 +205,8 @@ h4. Configuring a Database
 Just about every Rails application will interact with a database. The database to use is specified in a configuration file, +config/database.yml+.
 If you open this file in a new Rails application, you'll see a default database configuration using SQLite3. The file contains sections for three different environments in which Rails can run by default:
 
-* The +development+ environment is used on your development computer as you interact manually with the application
-* The +test+ environment is used to run automated tests
+* The +development+ environment is used on your development computer as you interact manually with the application.
+* The +test+ environment is used to run automated tests.
 * The +production+ environment is used when you deploy your application for the world to use.
 
 h5. Configuring an SQLite3 Database
@@ -289,7 +289,7 @@ development:
   database: blog_development
   username: blog
   password:
-<yaml>
+</yaml>
 
 Change the username and password in the +development+ section as appropriate.
 
@@ -448,10 +448,10 @@ h4. Adding a Link
 
 To hook the posts up to the home page you've already created, you can add a link to the home page. Open +app/views/home/index.html.erb+ and modify it as follows:
 
-<code lang="ruby">
+<ruby>
 <h1>Hello, Rails!</h1>
 <%= link_to "My Blog", posts_path %>
-</code>
+</ruby>
 
 The +link_to+ method is one of Rails' built-in view helpers. It creates a hyperlink based on text to display and where to go - in this case, to the path for posts.
 
diff --git a/railties/guides/source/performance_testing.textile b/railties/guides/source/performance_testing.textile
index a4187a3135..dbe6f97f5c 100644
--- a/railties/guides/source/performance_testing.textile
+++ b/railties/guides/source/performance_testing.textile
@@ -151,7 +151,7 @@ Performance tests can be run in two modes: Benchmarking and Profiling.
 
 h5. Benchmarking
 
-Benchmarking makes it easy to quickly gather a few metrics about each test tun. By default, each test case is run +4 times+ in benchmarking mode.
+Benchmarking makes it easy to quickly gather a few metrics about each test tun. By default, each test case is run *4 times* in benchmarking mode.
 
 To run performance tests in benchmarking mode:
 
@@ -161,7 +161,7 @@ $ rake test:benchmark
 
 h5. Profiling
 
-Profiling allows you to make an in-depth analysis of each of your tests by using an external profiler. Depending on your Ruby interpreter, this profiler can be native (Rubinius, JRuby) or not (MRI, which uses RubyProf). By default, each test case is run +1 time+ in profiling mode.
+Profiling allows you to make an in-depth analysis of each of your tests by using an external profiler. Depending on your Ruby interpreter, this profiler can be native (Rubinius, JRuby) or not (MRI, which uses RubyProf). By default, each test case is run *once* in profiling mode.
 
 To run performance tests in profiling mode:
 
diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile
index db9c7545c8..cc55d1f756 100644
--- a/railties/guides/source/testing.textile
+++ b/railties/guides/source/testing.textile
@@ -944,7 +944,7 @@ The built-in +test/unit+ based testing is not the only way to test Rails applica
 * "Factory Girl":https://github.com/thoughtbot/factory_girl/tree/master, a replacement for fixtures.
 * "Machinist":https://github.com/notahat/machinist/tree/master, another replacement for fixtures.
 * "Shoulda":http://www.thoughtbot.com/projects/shoulda, an extension to +test/unit+ with additional helpers, macros, and assertions.
-* "RSpec":http://rspec.info/, a behavior-driven development framework
+* "RSpec":http://relishapp.com/rspec, a behavior-driven development framework
 
 h3. Changelog