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

7 files changed, 75 insertions, 83 deletions

diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 398d2b2392..32738fe070 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -2662,10 +2662,6 @@ h3. Extensions to +Process+
 
 ...
 
-h3. Extensions to +Pathname+
-
-...
-
 h3. Extensions to +File+
 
 h4. +atomic_write+
diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile
index ebae320ebc..ab024d7fc3 100644
--- a/railties/guides/source/command_line.textile
+++ b/railties/guides/source/command_line.textile
@@ -64,12 +64,13 @@ Without any prodding of any kind, +rails server+ will run our new shiny Rails ap
 <shell>
 $ cd commandsapp
 $ rails server
-=> Booting WEBrick...
-=> Rails 2.2.0 application started on http://0.0.0.0:3000
-=> Ctrl-C to shutdown server; call with --help for options
-[2008-11-04 10:11:38] INFO  WEBrick 1.3.1
-[2008-11-04 10:11:38] INFO  ruby 1.8.5 (2006-12-04) [i486-linux]
-[2008-11-04 10:11:38] INFO  WEBrick::HTTPServer#start: pid=18994 port=3000
+=> Booting WEBrick
+=> Rails 3.0.0 application starting in development on http://0.0.0.0:3000
+=> Call with -d to detach
+=> Ctrl-C to shutdown server
+[2010-04-18 03:20:33] INFO  WEBrick 1.3.1
+[2010-04-18 03:20:33] INFO  ruby 1.8.7 (2010-01-10) [x86_64-linux]
+[2010-04-18 03:20:33] INFO  WEBrick::HTTPServer#start: pid=26086 port=3000
 </shell>
 
 With just three commands we whipped up a Rails server listening on port 3000. Go to your browser and open "http://localhost:3000":http://localhost:3000, you will see a basic rails app running.
@@ -237,7 +238,7 @@ The migration requires that we *migrate*, that is, run some Ruby code (living in
 
 <shell>
 $ rake db:migrate
-(in /Users/mikel/rails_programs/commandsapp)
+(in /home/foobar/commandsapp)
 ==  CreateHighScores: migrating ===============================================
 -- create_table(:high_scores)
    -> 0.0026s
@@ -320,21 +321,20 @@ h4. +about+
 Check it: Version numbers for Ruby, RubyGems, Rails, the Rails subcomponents, your application's folder, the current Rails environment name, your app's database adapter, and schema version! +about+ is useful when you need to ask for help, check if a security patch might affect you, or when you need some stats for an existing Rails installation.
 
 <shell>
-$ rails about
+$ rake about
 About your application's environment
-Ruby version              1.8.6 (i486-linux)
-RubyGems version          1.3.1
-Rails version             2.2.0
-Active Record version     2.2.0
-Action Pack version       2.2.0
-Active Resource version   2.2.0
-Action Mailer version     2.2.0
-Active Support version    2.2.0
-Edge Rails revision       unknown
-Application root          /home/commandsapp
+Ruby version              1.8.7 (x86_64-linux)
+RubyGems version          1.3.6
+Rack version              1.1
+Rails version             3.0.0
+Active Record version     3.0.0
+Action Pack version       3.0.0
+Active Resource version   3.0.0
+Action Mailer version     3.0.0
+Active Support version    3.0.0
+Middleware                ActionDispatch::Static, Rack::Lock, Rack::Runtime, Rails::Rack::Logger, ActionDispatch::ShowExceptions, ActionDispatch::RemoteIp, Rack::Sendfile, ActionDispatch::Callbacks, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ParamsParser, Rack::MethodOverride, ActionDispatch::Head
+Application root          /home/foobar/commandsapp
 Environment               development
-Database adapter          sqlite3
-Database schema version   20081217073400
 </shell>
 
 h3. The Rails Advanced Command Line
@@ -526,7 +526,7 @@ You can get a list of Rake tasks available to you, which will often depend on yo
 
 <shell>
  rake --tasks
-(in /home/developer/commandsapp)
+(in /home/foobar/commandsapp)
 rake db:abort_if_pending_migrations       # Raises an error if there are pending migrations
 rake db:charset                           # Retrieves the charset for the current environment's database
 rake db:collation                         # Retrieves the collation for the current environment's database
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index cbace177f9..6052ac737a 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -87,7 +87,7 @@ 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
 
@@ -356,19 +356,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 +394,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 +503,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.
 
@@ -551,19 +550,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 +602,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 />
diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile
index e9480408f8..9182f89f5b 100644
--- a/railties/guides/source/initialization.textile
+++ b/railties/guides/source/initialization.textile
@@ -148,7 +148,7 @@ Here the only two gems we need are +rails+ and +sqlite3-ruby+, so it seems. This
 * mime-types-1.16.gem
 * polyglot-0.3.1.gem
 * rack-1.1.0.gem
-* rack-mount-0.6.1.gem
+* rack-mount-0.6.3.gem
 * rack-test-0.5.3.gem
 * rails-3.0.0.beta1.gem
 * railties-3.0.0.beta1.gem
@@ -3707,4 +3707,4 @@ The _activesupport/lib/active_support/ruby/shim.rb_ file requires methods that h
 
 For more information see the ActiveSupport Extensions guide TODO: link to relevant sections for each method.
 
-And "the REXML security fix detailed here":[http://weblog.rubyonrails.org/2008/8/23/dos-vulnerabilities-in-rexml]
\ No newline at end of file
+And "the REXML security fix detailed here":[http://weblog.rubyonrails.org/2008/8/23/dos-vulnerabilities-in-rexml]
diff --git a/railties/guides/source/performance_testing.textile b/railties/guides/source/performance_testing.textile
index f74b68b0ef..c02fabc0b2 100644
--- a/railties/guides/source/performance_testing.textile
+++ b/railties/guides/source/performance_testing.textile
@@ -246,16 +246,16 @@ Sample output of +BrowsingTest#test_homepage_wall_time.csv+:
 
 <shell>
 measurement,created_at,app,rails,ruby,platform
-0.00738224999999992,2009-01-08T03:40:29Z,,2.3.0.master.0744148,ruby-1.8.6.110,i686-darwin9.0.0
-0.00755874999999984,2009-01-08T03:46:18Z,,2.3.0.master.0744148,ruby-1.8.6.110,i686-darwin9.0.0
-0.00762099999999993,2009-01-08T03:49:25Z,,2.3.0.master.0744148,ruby-1.8.6.110,i686-darwin9.0.0
-0.00603075000000008,2009-01-08T04:03:29Z,,2.3.0.master.0744148,ruby-1.8.6.111,i686-darwin9.1.0
-0.00619899999999995,2009-01-08T04:03:53Z,,2.3.0.master.0744148,ruby-1.8.6.111,i686-darwin9.1.0
-0.00755449999999991,2009-01-08T04:04:55Z,,2.3.0.master.0744148,ruby-1.8.6.110,i686-darwin9.0.0
-0.00595999999999997,2009-01-08T04:05:06Z,,2.3.0.master.0744148,ruby-1.8.6.111,i686-darwin9.1.0
-0.00740450000000004,2009-01-09T03:54:47Z,,2.3.0.master.859e150,ruby-1.8.6.110,i686-darwin9.0.0
-0.00603150000000008,2009-01-09T03:54:57Z,,2.3.0.master.859e150,ruby-1.8.6.111,i686-darwin9.1.0
-0.00771250000000012,2009-01-09T15:46:03Z,,2.3.0.master.859e150,ruby-1.8.6.110,i686-darwin9.0.0
+0.00738224999999992,2009-01-08T03:40:29Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00755874999999984,2009-01-08T03:46:18Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00762099999999993,2009-01-08T03:49:25Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00603075000000008,2009-01-08T04:03:29Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00619899999999995,2009-01-08T04:03:53Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00755449999999991,2009-01-08T04:04:55Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00595999999999997,2009-01-08T04:05:06Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00740450000000004,2009-01-09T03:54:47Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00603150000000008,2009-01-09T03:54:57Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
+0.00771250000000012,2009-01-09T15:46:03Z,,3.0.0,ruby-1.8.7.249,x86_64-linux
 </shell>
 
 h5(#output-profiling). Profiling
diff --git a/railties/guides/source/rails_on_rack.textile b/railties/guides/source/rails_on_rack.textile
index d0d86e99f2..512be43668 100644
--- a/railties/guides/source/rails_on_rack.textile
+++ b/railties/guides/source/rails_on_rack.textile
@@ -247,7 +247,7 @@ class Poller
     if env["PATH_INFO"] =~ /^\/poller/
       [200, {"Content-Type" => "text/html"}, ["Hello, World!"]]
     else
-      [404, {"Content-Type" => "text/html"}, ["Not Found"]]
+      [404, {"Content-Type" => "text/html", "X-Cascade" => "pass"}, ["Not Found"]]
     end
   end
 end
@@ -257,23 +257,13 @@ Metal applications within +app/metal+ folders in plugins will also be discovered
 
 Metal applications are an optimization. You should make sure to "understand the related performance implications":http://weblog.rubyonrails.org/2008/12/20/performance-of-rails-metal before using it.
 
-h4. Execution Order
-
-All Metal Applications are executed by +Rails::Rack::Metal+ middleware, which is a part of the +ActionController::MiddlewareStack+ chain.
+WARNING: To continue the Metal chain execution, return an +X-Cascade+ HTTP header with a value of +pass+.
 
-Here's the primary method responsible for running the Metal applications:
+h4. Execution Order
 
-<ruby>
-def call(env)
-  @metals.keys.each do |app|
-    result = app.call(env)
-    return result unless result[0].to_i == 404
-  end
-  @app.call(env)
-end
-</ruby>
+All Metal Applications are executed in alphabetical order of their filenames, so +aaa.rb+ will come before +bbb.rb+ in the metal chain.
 
-In the code above, +@metals+ is an ordered hash of metal applications. Due to the default alphabetical ordering, +aaa.rb+ will come before +bbb.rb+ in the metal chain.
+You can override the default ordering in your environment. Simply add a line like the following to +config/application.rb+
 
 It is, however, possible to override the default ordering in your environment. Simply add a line like the following to +config/environment.rb+
 
@@ -283,8 +273,6 @@ config.metals = ["Bbb", "Aaa"]
 
 Each string in the array should be the name of your metal class. If you do this then be warned that any metal applications not listed will not be loaded.
 
-WARNING: Metal applications cannot return the HTTP Status +404+ to a client, as it is used for continuing the Metal chain execution. Please use normal Rails controllers or a custom middleware if returning +404+ is a requirement.
-
 h3. Resources
 
 h4. Learning Rack
diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile
index c4f7ff8e92..206ed6e75c 100644
--- a/railties/guides/source/testing.textile
+++ b/railties/guides/source/testing.textile
@@ -108,7 +108,7 @@ tag is considered Ruby code. When this fixture is loaded, the +size+ attribute o
 
 h5. Fixtures in Action
 
-Rails by default automatically loads all fixtures from the 'test/fixtures' folder for your unit and functional test. Loading involves three steps:
+Rails by default automatically loads all fixtures from the +test/fixtures+ folder for your unit and functional test. Loading involves three steps:
 
 * Remove any existing data from the table corresponding to the fixture
 * Load the fixture data into the table
@@ -142,7 +142,7 @@ In Rails, unit tests are what you write to test your models.
 
 For this guide we will be using Rails _scaffolding_. It will create the model, a migration, controller and views for the new resource in a single operation. It will also create a full test suite following Rails best practices. I will be using examples from this generated code and would be supplementing it with additional examples where necessary.
 
-NOTE: For more information on Rails _scaffolding_, refer to "Getting Started with Rails":getting_started.html
+NOTE: For more information on Rails <i>scaffolding</i>, refer to "Getting Started with Rails":getting_started.html
 
 When you use +rails generate scaffold+, for a resource among other things it creates a test stub in the +test/unit+ folder:
 
@@ -221,9 +221,9 @@ $ rake db:migrate
 $ rake db:test:load
 </shell>
 
-Above +rake db:migrate+ runs any pending migrations on the _development_ environment and updates +db/schema.rb+. +rake db:test:load+ recreates the test database from the current db/schema.rb. On subsequent attempts it is a good to first run +db:test:prepare+ as it first checks for pending migrations and warns you appropriately.
+Above +rake db:migrate+ runs any pending migrations on the _development_ environment and updates +db/schema.rb+. +rake db:test:load+ recreates the test database from the current +db/schema.rb+. On subsequent attempts it is a good to first run +db:test:prepare+ as it first checks for pending migrations and warns you appropriately.
 
-NOTE: +db:test:prepare+ will fail with an error if db/schema.rb doesn't exists.
+NOTE: +db:test:prepare+ will fail with an error if +db/schema.rb+ doesn't exists.
 
 h5. Rake Tasks for Preparing your Application for Testing
 
@@ -256,7 +256,7 @@ This will run all the test methods from the test case.
 
 You can also run a particular test method from the test case by using the +-n+ switch with the +test method name+.
 
-<pre>
+<shell>
 $ ruby unit/post_test.rb -n test_truth
 
 Loaded suite unit/post_test
@@ -265,7 +265,7 @@ Started
 Finished in 0.023513 seconds.
 
 1 tests, 1 assertions, 0 failures, 0 errors
-</pre>
+</shell>
 
 The +.+ (dot) above indicates a passing test. When a test fails you see an +F+; when a test throws an error you see an +E+ in its place. The last line of the output is the summary.
 
@@ -280,7 +280,7 @@ end
 
 Let us run this newly added test.
 
-<pre>
+<shell>
 $ ruby unit/post_test.rb -n test_should_not_save_post_without_title
 Loaded suite -e
 Started
@@ -292,7 +292,7 @@ test_should_not_save_post_without_title(PostTest) [/test/unit/post_test.rb:6]:
 <false> is not true.
 
 1 tests, 1 assertions, 1 failures, 0 errors
-</pre>
+</shell>
 
 In the output, +F+ denotes a failure. You can see the corresponding trace shown under +1)+ along with the name of the failing test. The next few lines contain the stack trace followed by a message which mentions the actual value and the expected value by the assertion. The default assertion messages provide just enough information to help pinpoint the error. To make the assertion failure message more readable every assertion provides an optional message parameter, as shown here:
 
@@ -305,12 +305,12 @@ end
 
 Running this test shows the friendlier assertion message:
 
-<pre>
+<shell>
   1) Failure:
 test_should_not_save_post_without_title(PostTest) [/test/unit/post_test.rb:6]:
 Saved the post without a title.
 <false> is not true.
-</pre>
+</shell>
 
 Now to get this test to pass we can add a model level validation for the _title_ field.
 
@@ -322,7 +322,7 @@ end
 
 Now the test should pass. Let us verify by running the test again:
 
-<pre>
+<shell>
 $ ruby unit/post_test.rb -n test_should_not_save_post_without_title
 Loaded suite unit/post_test
 Started
@@ -330,7 +330,7 @@ Started
 Finished in 0.193608 seconds.
 
 1 tests, 1 assertions, 0 failures, 0 errors
-</pre>
+</shell>
 
 Now if you noticed we first wrote a test which fails for a desired functionality, then we wrote some code which adds the functionality and finally we ensured that our test passes. This approach to software development is referred to as _Test-Driven Development_ (TDD).
 
@@ -348,7 +348,7 @@ end
 
 Now you can see even more output in the console from running the tests:
 
-<pre>
+<shell>
 $ ruby unit/post_test.rb -n test_should_report_error
 Loaded suite -e
 Started
@@ -361,7 +361,7 @@ NameError: undefined local variable or method `some_undefined_variable' for #<Po
     /test/unit/post_test.rb:6:in `test_should_report_error'
 
 1 tests, 0 assertions, 0 failures, 1 errors
-</pre>
+</shell>
 
 Notice the 'E' in the output. It denotes a test with error.
 
@@ -446,7 +446,7 @@ test "should get index" do
 end
 </ruby>
 
-In the +test_should_get_index+ test, Rails simulates a request on the action called index, making sure the request was successful and also ensuring that it assigns a valid +posts+ instance variable.
+In the +test_should_get_index+ test, Rails simulates a request on the action called +index+, making sure the request was successful and also ensuring that it assigns a valid +posts+ instance variable.
 
 The +get+ method kicks off the web request and populates the results into the response. It accepts 4 arguments: