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

README.rdoc

@@ -53,8 +53,8 @@ more separate. Each of these packages can be used independently outside of
 * The README file created within your application.
 * The {Getting Started with Rails}[http://guides.rubyonrails.org/getting_started.html].
 * The {Ruby on Rails Tutorial}[http://railstutorial.org/book].
-* The {Ruby on Rails guides}[http://guides.rubyonrails.org/getting_started.html].
-* The {API documentation}[http://api.rubyonrails.org].
+* The {Ruby on Rails Guides}[http://guides.rubyonrails.org].
+* The {API Documentation}[http://api.rubyonrails.org].
 
 
 == Contributing

actionpack/CHANGELOG

@@ -47,9 +47,7 @@
 
 * Symbols and strings in routes should yield the same behavior. Note this may break existing apps that were using symbols with the new routes API. [José Valim]
 
-* Add clear_helpers as a way to clean up all helpers added to this controller, maintaing just the helper with the same name as the controller. [José Valim]
-
-* See http://github.com/rails/rails/compare/v3.0.0_RC...v3.0.0_RC2 for gory details
+* Add clear_helpers as a way to clean up all helpers added to this controller, maintaining just the helper with the same name as the controller. [José Valim]
 
 * Support routing constraints in functional tests. [Andrew White]
 

actionpack/lib/action_controller/base.rb

@@ -24,7 +24,7 @@ module ActionController
   #
   # Actions, by default, render a template in the <tt>app/views</tt> directory corresponding to the name of the controller and action
   # after executing code in the action. For example, the +index+ action of the PostsController would render the
-  # template <tt>app/views/posts/index.erb</tt> by default after populating the <tt>@posts</tt> instance variable.
+  # template <tt>app/views/posts/index.html.erb</tt> by default after populating the <tt>@posts</tt> instance variable.
   #
   # Unlike index, the create action will not render a template. After performing its main purpose (creating a
   # new post), it initiates a redirect instead. This redirect works by returning an external

actionpack/lib/action_view/base.rb

@@ -18,7 +18,7 @@ module ActionView #:nodoc:
   # following loop for names:
   #
   #   <b>Names of all the people</b>
-  #   <% for person in @people %>
+  #   <% @people.each do |person| %>
   #     Name: <%= person.name %><br/>
   #   <% end %>
   #

actionpack/lib/action_view/partials.rb

@@ -12,19 +12,19 @@ module ActionView
   #
   #  <%= render :partial => "account" %>
   #
-  # This would render "advertiser/_account.erb" and pass the instance variable @account in as a local variable
+  # This would render "advertiser/_account.html.erb" and pass the instance variable @account in as a local variable
   # +account+ to the template for display.
   #
   # In another template for Advertiser#buy, we could have:
   #
   #   <%= render :partial => "account", :locals => { :account => @buyer } %>
   #
-  #   <% for ad in @advertisements %>
+  #   <% @advertisements.each do |ad| %>
   #     <%= render :partial => "ad", :locals => { :ad => ad } %>
   #   <% end %>
   #
-  # This would first render "advertiser/_account.erb" with @buyer passed in as the local variable +account+, then
-  # render "advertiser/_ad.erb" and pass the local variable +ad+ to the template for display.
+  # This would first render "advertiser/_account.html.erb" with @buyer passed in as the local variable +account+, then
+  # render "advertiser/_ad.html.erb" and pass the local variable +ad+ to the template for display.
   #
   # == The :as and :object options
   #
@@ -44,12 +44,12 @@ module ActionView
   #
   # The <tt>:object</tt> option can be used to directly specify which object is rendered into the partial;
   # useful when the template's object is elsewhere, in a different ivar or in a local variable for instance.
-  # 
+  #
   # Revisiting a previous example we could have written this code:
-  # 
+  #
   #   <%= render :partial => "account", :object => @buyer %>
   #
-  #   <% for ad in @advertisements %>
+  #   <% @advertisements.each do |ad| %>
   #     <%= render :partial => "ad", :object => ad %>
   #   <% end %>
   #
@@ -64,12 +64,12 @@ module ActionView
   #
   #   <%= render :partial => "ad", :collection => @advertisements %>
   #
-  # This will render "advertiser/_ad.erb" and pass the local variable +ad+ to the template for display. An
+  # This will render "advertiser/_ad.html.erb" and pass the local variable +ad+ to the template for display. An
   # iteration counter will automatically be made available to the template with a name of the form
   # +partial_name_counter+. In the case of the example above, the template would be fed +ad_counter+.
   #
   # The <tt>:as</tt> option may be used when rendering partials.
-  # 
+  #
   # You can specify a partial to be rendered between elements via the <tt>:spacer_template</tt> option.
   # The following example will render <tt>advertiser/_ad_divider.html.erb</tt> between each ad partial:
   #
@@ -89,7 +89,7 @@ module ActionView
   #
   #   <%= render :partial => "advertisement/ad", :locals => { :ad => @advertisement } %>
   #
-  # This will render the partial "advertisement/_ad.erb" regardless of which controller this is being called from.
+  # This will render the partial "advertisement/_ad.html.erb" regardless of which controller this is being called from.
   #
   # == Rendering objects with the RecordIdentifier
   #

railties/guides/rails_guides/generator.rb

@@ -32,7 +32,7 @@
 #
 #     Separate many using commas:
 #
-#       # generates only
+#       # generates only association_basics.html and migrations.html
 #       ONLY=assoc,migrations ruby rails_guides.rb
 #
 #     Note that if you are working on a guide generation will by default process

railties/guides/source/action_view_overview.textile

@@ -367,14 +367,14 @@ This helper makes building an ATOM feed easy. Here's a full usage example:
 *config/routes.rb*
 
 <ruby>
-map.resources :posts
+resources :posts
 </ruby>
 
 *app/controllers/posts_controller.rb*
 
 <ruby>
 def index
-  @posts = Post.find(:all)
+  @posts = Post.all
 
   respond_to do |format|
     format.html
@@ -439,7 +439,7 @@ The +capture+ method allows you to extract part of a template into a variable. Y
 <% @greeting = capture do %>
   <p>Welcome! The date and time is <%= Time.now %></p>
 <% end %>
-<ruby>
+</ruby>
 
 The captured variable can then be used anywhere else.
 
@@ -809,7 +809,7 @@ end
 Sample usage (selecting the associated Author for an instance of Post, +@post+):
 
 <ruby>
-collection_select(:post, :author_id, Author.find(:all), :id, :name_with_initial, {:prompt => true})
+collection_select(:post, :author_id, Author.all, :id, :name_with_initial, {:prompt => true})
 </ruby>
 
 If @post.author_id is already 1, this would return:
@@ -910,7 +910,7 @@ Create a select tag and a series of contained option tags for the provided objec
 Example with @post.person_id => 1:
 
 <ruby>
-select("post", "person_id", Person.find(:all).collect {|p| [ p.name, p.id ] }, { :include_blank => true })
+select("post", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, { :include_blank => true })
 </ruby>
 
 could become:

railties/guides/source/active_record_querying.textile

@@ -150,7 +150,7 @@ SQL equivalent of the above is:
 SELECT * FROM clients WHERE (clients.id IN (1,10))
 </sql>
 
-<tt>Model.find(array_of_primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception unless a matching record is found for <strong>all</strong> of the supplied primary keys.
+WARNING: <tt>Model.find(array_of_primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception unless a matching record is found for <strong>all</strong> of the supplied primary keys.
 
 h4. Retrieving Multiple Objects in Batches
 
@@ -569,9 +569,7 @@ SELECT clients.* FROM clients LEFT OUTER JOIN addresses ON addresses.client_id =
 
 h4. Using Array/Hash of Named Associations
 
-WARNING: This method only works with +INNER JOIN+,
-
-<br />
+WARNING: This method only works with +INNER JOIN+.
 
 Active Record lets you use the names of the "associations":association_basics.html defined on the model as a shortcut for specifying +JOIN+ clause for those associations when using the +joins+ method.
 

railties/guides/source/active_support_core_extensions.textile

@@ -498,7 +498,7 @@ h4. Attributes
 
 h5. +alias_attribute+
 
-Model attributes have a reader, a writer, and a predicate. You can aliase a model attribute having the corresponding three methods defined for you in one shot. As in other aliasing methods, the new name is the first argument, and the old name is the second (my mnemonic is they go in the same order as if you did an assignment):
+Model attributes have a reader, a writer, and a predicate. You can alias a model attribute having the corresponding three methods defined for you in one shot. As in other aliasing methods, the new name is the first argument, and the old name is the second (my mnemonic is they go in the same order as if you did an assignment):
 
 <ruby>
 class User < ActiveRecord::Base
@@ -563,7 +563,7 @@ h5. Internal Attributes
 
 When you are defining an attribute in a class that is meant to be subclassed name collisions are a risk. That's remarkably important for libraries.
 
-Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby builtin +attr_*+ counterparts, except they name the underlying instance variable in a way that makes collisions less likely.
+Active Support defines the macros +attr_internal_reader+, +attr_internal_writer+, and +attr_internal_accessor+. They behave like their Ruby built-in +attr_*+ counterparts, except they name the underlying instance variable in a way that makes collisions less likely.
 
 The macro +attr_internal+ is a synonym for +attr_internal_accessor+:
 
@@ -991,7 +991,7 @@ a2.x # => 2, overridden in a2
 The generation of the writer instance method can be prevented by setting the option +:instance_writer+ to false, as in
 
 <ruby>
-module AcitveRecord
+module ActiveRecord
   class Base
     class_attribute :table_name_prefix, :instance_writer => false
     self.table_name_prefix = ""
@@ -1001,7 +1001,7 @@ end
 
 A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
 
-For convenience +class_attribute+ defines also an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called +x?+.
+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?+.
 
 NOTE: Defined in +active_support/core_ext/class/attribute.rb+
 

railties/guides/source/association_basics.textile

@@ -65,7 +65,7 @@ To learn more about the different types of associations, read the next section o
 
 h3. The Types of Associations
 
-In Rails, an _association_ is a connection between two Active Record models. Associations are implemented using macro-style calls, so that you can declaratively add features to your models. For example, by declaring that one model +belongs_to+ another, you instruct Rails to maintain Primary Key–Foreign Key information between instances of the two models, and you also get a number of utility methods added to your model. Rails supports six types of association:
+In Rails, an _association_ is a connection between two Active Record models. Associations are implemented using macro-style calls, so that you can declaratively add features to your models. For example, by declaring that one model +belongs_to+ another, you instruct Rails to maintain Primary Key–Foreign Key information between instances of the two models, and you also get a number of utility methods added to your model. Rails supports six types of associations:
 
 * +belongs_to+
 * +has_one+
@@ -1135,7 +1135,7 @@ 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.find(:all, :conditions => "open = 1")
+@open_orders = @customer.orders.all(:conditions => "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.
@@ -1564,7 +1564,7 @@ h6(#has_and_belongs_to_many-collection-find). <tt><em>collection</em>.find(...)<
 The <tt><em>collection</em>.find</tt> method finds objects within the collection. It uses the same syntax and options as +ActiveRecord::Base.find+. It also adds the additional condition that the object must be in the collection.
 
 <ruby>
-@new_assemblies = @part.assemblies.find(:all,
+@new_assemblies = @part.assemblies.all(
   :conditions => ["created_at > ?", 2.days.ago])
 </ruby>
 

railties/guides/source/debugging_rails_applications.textile

@@ -269,7 +269,7 @@ If you got there by a browser request, the browser tab containing the request wi
 For example:
 
 <shell>
-@posts = Post.find(:all)
+@posts = Post.all
 (rdb:7)
 </shell>
 
@@ -302,7 +302,7 @@ This command shows you where you are in the code by printing 10 lines centered a
    3    # GET /posts.xml
    4    def index
    5      debugger
-=> 6      @posts = Post.find(:all)
+=> 6      @posts = Post.all
    7
    8      respond_to do |format|
    9        format.html # index.html.erb
@@ -380,7 +380,7 @@ Any expression can be evaluated in the current context. To evaluate an expressio
 This example shows how you can print the instance_variables defined within the current context:
 
 <shell>
-@posts = Post.find(:all)
+@posts = Post.all
 (rdb:11) instance_variables
 ["@_response", "@action_name", "@url", "@_session", "@_cookies", "@performed_render", "@_flash", "@template", "@_params", "@before_filter_chain_aborted", "@request_origin", "@_headers", "@performed_redirect", "@_request"]
 </shell>

railties/guides/source/getting_started.textile

@@ -163,7 +163,7 @@ $ rails new blog
 
 This will create a Rails application called Blog in a directory called blog.
 
-TIP: You can see all of the switches that the Rails application builder accepts by running <tt>rails -h</tt>.
+TIP: You can see all of the switches that the Rails application builder accepts by running <tt>rails new -h</tt>.
 
 After you create the blog application, switch to its folder to continue work directly in that application:
 
@@ -258,6 +258,8 @@ development:
 
 Change the username and password in the +development+ section as appropriate.
 
+TIP: You don't have to update the database configurations manually. If you had a look at the options of application generator, you have seen that one of them is named <tt>--database</tt>. It lets you choose an adapter for couple of most used relational databases. You can even run the generator repeatedly: <tt>cd .. && rails new blog --database=mysql</tt>. When you confirm the overwriting of the +config/database.yml+ file, your application will be configured for MySQL instead of SQLite.
+
 h4. Creating the Database
 
 Now that you have your database configured, it's time to have Rails create an empty database for you. You can do this by running a rake command:
@@ -298,7 +300,7 @@ To get Rails saying "Hello", you need to create at minimum a controller and a vi
 $ rails generate controller home index
 </shell>
 
-TIP: If you're on Windows, or your Ruby is set up in some non-standard fashion, you may need to explicitly pass Rails +rails+ commands to Ruby: +ruby \path\to\rails controller home index+.
+TIP: If you're on Windows, or your Ruby is set up in some non-standard fashion, you may need to explicitly pass Rails +rails+ commands to Ruby: <tt>ruby \path\to\your\application\script\rails generate controller home index</tt>.
 
 Rails will create several files for you, including +app/views/home/index.html.erb+. This is the template that will be used to display the results of the +index+ action (method) in the +home+ controller. Open this file in your text editor and edit it to contain a single line of code:
 
@@ -347,7 +349,7 @@ In the case of the blog application, you can start by generating a scaffolded Po
 $ rails generate scaffold Post name:string title:string content:text
 </shell>
 
-NOTE. While scaffolding will get you up and running quickly, the "one size fits all" code that it generates is unlikely to be a perfect fit for your application. In most cases, you'll need to customize the generated code. Many experienced Rails developers avoid scaffolding entirely, preferring to write all or most of their source code from scratch.
+NOTE. While scaffolding will get you up and running quickly, the code it generates is unlikely to be a perfect fit for your application. You'll most probably want to customize the generated code. Many experienced Rails developers avoid scaffolding entirely, preferring to write all or most of their source code from scratch. Rails, however, makes it really simple to customize templates for generated models, controllers, views and other source files. You'll find more information in the "Creating and Customizing Rails Generators & Templates":generators.html guide.
 
 The scaffold generator will build 15 files in your application, along with some folders, and edit one more. Here's a quick overview of what it creates:
 
@@ -409,7 +411,7 @@ Rails will execute this migration command and tell you it created the Posts tabl
 ==  CreatePosts: migrated (0.0020s) ===========================================
 </shell>
 
-NOTE. Because you're working in the development environment by default, this command will apply to the database defined in the +development+ section of your +config/database.yml+ file.
+NOTE. Because you're working in the development environment by default, this command will apply to the database defined in the +development+ section of your +config/database.yml+ file. If you would like to execute migrations in other environment, for instance in production, you must explicitely pass it when invoking the command: <tt>rake db:migrate RAILS_ENV=production</tt>.
 
 h4. Adding a Link
 

railties/guides/source/i18n.textile

@@ -10,7 +10,7 @@ So, in the process of _internationalizing_ your Rails application you have to:
 * Tell Rails where to find locale dictionaries
 * Tell Rails how to set, preserve and switch locale
 
-In the process of _localizing_ your application you'll probably want to do following three things:
+In the process of _localizing_ your application you'll probably want to do the following three things:
 
 * Replace or supplement Rails' default locale -- e.g. date and time formats, month names, Active Record model names, etc
 * Abstract strings in your application into keyed dictionaries -- e.g. flash messages, static text in your views, etc.
@@ -305,12 +305,12 @@ end
 # app/controllers/home_controller.rb
 class HomeController < ApplicationController
   def index
-    flash[:notice] = "Hello flash!"
+    flash[:notice] = "Hello Flash"
   end
 end
 
 # app/views/home/index.html.erb
-<h1>Hello world!</h1>
+<h1>Hello World</h1>
 <p><%= flash[:notice] %></p>
 </ruby>
 
@@ -344,8 +344,8 @@ So let's add the missing translations into the dictionary files (i.e. do the "lo
 <ruby>
 # config/locales/en.yml
 en:
-  hello_world: Hello World
-  hello_flash: Hello Flash
+  hello_world: Hello world!
+  hello_flash: Hello flash!
 
 # config/locales/pirate.yml
 pirate:
@@ -586,7 +586,7 @@ I18n.t :foo
 I18n.l Time.now
 </ruby>
 
-Explicitely passing a locale:
+Explicitly passing a locale:
 
 <ruby>
 I18n.t :foo, :locale => :de
@@ -623,7 +623,7 @@ pt:
     bar: baz
 </ruby>
 
-As you see, in both cases the toplevel key is the locale. +:foo+ is a namespace key and +:bar+ is the key for the translation "baz".
+As you see, in both cases the top level key is the locale. +:foo+ is a namespace key and +:bar+ is the key for the translation "baz".
 
 Here is a "real" example from the Active Support +en.yml+ translations YAML file: