Merge commit 'docrails/master'

actionpack/lib/action_controller/caching/pages.rb

@@ -41,7 +41,7 @@ module Pages
         ##
         # :singleton-method:
         # The cache directory should be the document root for the web server and is set using <tt>Base.page_cache_directory = "/document/root"</tt>.
-        # For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>RAILS_ROOT + "/public"</tt>). Changing
+        # For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>Rails.root + "/public"</tt>). Changing
         # this setting can be useful to avoid naming conflicts with files in <tt>public/</tt>, but doing so will likely require configuring your
         # web server to look in the new location for cached files.
         @@page_cache_directory = ''

activerecord/RUNNING_UNIT_TESTS

@@ -14,7 +14,7 @@ connection.rb otherwise (on Postgres, at least) tests for default values will fa
 
 The easiest way to run the unit tests is through Rake. The default task runs
 the entire test suite for all the adapters. You can also run the suite on just
-one adapter by using the tasks test_mysql, test_sqlite, test_postgresql or any
+one adapter by using the tasks test_mysql, test_sqlite3, test_postgresql or any
 of the other test_ tasks. For more information, checkout the full array of rake
 tasks with "rake -T"
 

railties/guides/source/3_0_release_notes.textile

@@ -20,14 +20,10 @@ endprologue.
 
 WARNING: Rails 3.0 is currently in beta. This means that there are probably bugs and that you should "report them":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/overview if you see them. You also may not want to run the NORAD nuclear launch application off a beta version. But if you're starting development on a new application and you don't mind getting wind in your hair, please do jump on board!
 
-TIP: To install the Rails 3 prerelease beta using rubygems you have to install all the Rails dependencies first as these will not be installed for you by rubygems:
+To install the last Rails 3 beta:
 
 <shell>
 # Use sudo if your setup requires it
-gem install tzinfo builder i18n memcache-client rack \
-  rake rack-test erubis mail text-format \
-  thor bundler
-gem install rack-mount -v=0.4
 gem install rails --pre
 </shell>
 
@@ -187,7 +183,7 @@ Railties generators got a huge amount of attention in Rails 3.0, basically:
 * Rails templates API and generators API were merged (they are the same as the former).
 * Generators are no longer loaded from special paths anymore, they are just found in the Ruby load path, so calling <tt>rails generate foo</tt> will look for <tt>generators/foo_generator</tt>.
 * New generators provide hooks, so any template engine, ORM, test framework can easily hook in.
-* New generators allow you to override the templates by placing a copy at <tt>RAILS_ROOT/lib/templates</tt>.
+* New generators allow you to override the templates by placing a copy at <tt>Rails.root/lib/templates</tt>.
 * <tt>Rails::Generators::TestCase</tt> is also supplied so you can create your own generators and test them.
 
 Also, the views generated by Railties generators had some overhaul:

railties/guides/source/command_line.textile

@@ -530,7 +530,7 @@ You can get a list of Rake tasks available to you, which will often depend on yo
 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
-rake db:create                            # Create the database defined in config/database.yml for the current RAILS_ENV
+rake db:create                            # Create the database defined in config/database.yml for the current Rails.env
 ...
 ...
 rake tmp:pids:clear                       # Clears all files in tmp/pids

railties/guides/source/configuring.textile

@@ -163,7 +163,7 @@ WARNING: Threadsafe operation in incompatible with the normal workings of develo
 
 The caching code adds two additional settings:
 
-* +ActionController::Base.page_cache_directory+ sets the directory where Rails will create cached pages for your web server. The default is +Rails.public_path+ (which is usually set to +RAILS_ROOT + "/public"+).
+* +ActionController::Base.page_cache_directory+ sets the directory where Rails will create cached pages for your web server. The default is +Rails.public_path+ (which is usually set to +Rails.root + "/public"+).
 
 * +ActionController::Base.page_cache_extension+ sets the extension to be used when generating pages for the cache (this is ignored if the incoming request already has an extension). The default is +.html+.
 

railties/guides/source/debugging_rails_applications.textile

@@ -136,7 +136,7 @@ config.logger = Logger.new(STDOUT)
 config.logger = Log4r::Logger.new("Application Log")
 </ruby>
 
-TIP: By default, each log is created under +RAILS_ROOT/log/+ and the log file name is +environment_name.log+.
+TIP: By default, each log is created under +Rails.root/log/+ and the log file name is +environment_name.log+.
 
 h4. Log Levels
 

railties/guides/source/getting_started.textile

@@ -232,13 +232,13 @@ If you choose to use MySQL instead of the shipped Sqlite3 database, your +config
 
 <yaml>
 development:
-adapter: mysql
-encoding: utf8
-database: blog_development
-pool: 5
-username: root
-password:
-socket: /tmp/mysql.sock
+  adapter: mysql
+  encoding: utf8
+  database: blog_development
+  pool: 5
+  username: root
+  password:
+  socket: /tmp/mysql.sock
 </yaml>
 
 If your development computer's MySQL installation includes a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the +development+ section as appropriate.
@@ -249,12 +249,12 @@ Finally if you choose to use PostgreSQL, your +config/database.yml+ will be cust
 
 <yaml>
 development:
-adapter: postgresql
-encoding: unicode
-database: blog_development
-pool: 5
-username: blog
-password:
+  adapter: postgresql
+  encoding: unicode
+  database: blog_development
+  pool: 5
+  username: blog
+  password:
 </yaml>
 
 Change the username and password in the +development+ section as appropriate.

railties/guides/source/i18n.textile

@@ -97,36 +97,33 @@ The *translations load path* (+I18n.load_path+) is just a Ruby Array of paths to
 
 NOTE: The backend will lazy-load these translations when a translation is looked up for the first time. This makes it possible to just swap the backend with something else even after translations have already been announced.
 
-The default +environment.rb+ files has instructions on how to add locales from another directory and how to set a different default locale. Just uncomment and edit the specific lines.
+The default +application.rb+ files has instructions on how to add locales from another directory and how to set a different default locale. Just uncomment and edit the specific lines.
 
 <ruby>
-# The internationalization framework can be changed
-# to have another default locale (standard is :en) or more load paths.
-# All files from config/locales/*.rb,yml are added automatically.
-# config.i18n.load_path << Dir[File.join(RAILS_ROOT, 'my', 'locales', '*.{rb,yml}')]
+# The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
+# config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
 # config.i18n.default_locale = :de
 </ruby>
 
 h4. Optional: Custom I18n Configuration Setup
 
-For the sake of completeness, let's mention that if you do not want to use the +environment.rb+ file for some reason, you can always wire up things manually, too.
+For the sake of completeness, let's mention that if you do not want to use the +application.rb+ file for some reason, you can always wire up things manually, too.
 
 To tell the I18n library where it can find your custom translation files you can specify the load path anywhere in your application - just make sure it gets run before any translations are actually looked up. You might also want to change the default locale. The simplest thing possible is to put the following into an initializer:
 
 <ruby>
 # in config/initializers/locale.rb
 
 # tell the I18n library where to find your translations
-I18n.load_path << Dir[ File.join(RAILS_ROOT, 'lib', 'locale', 
-  '*.{rb,yml}') ]
+I18n.load_path += Dir[Rails.root.join('lib', 'locale', '*.{rb,yml}')]
 
 # set default locale to something other than :en
 I18n.default_locale = :pt
 </ruby>
 
 h4. Setting and Passing the Locale
 
-If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in +environment.rb+ or an initializer as shown above, and it will persist through the requests.
+If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in +application.rb+ or an initializer as shown above, and it will persist through the requests.
 
 However, you would probably like to *provide support for more locales* in your application. In such case, you need to set and pass the locale between requests.
 
@@ -227,21 +224,23 @@ You probably want URLs to look like this: +www.example.com/en/books+ (which load
 
 <ruby>
 # config/routes.rb
-map.resources :books, :path_prefix => '/:locale'
+scope "/:locale" do
+  resources :books
+end
 </ruby>
 
 Now, when you call the +books_path+ method you should get +"/en/books"+ (for the default locale). An URL like +http://localhost:3001/nl/books+ should load the Netherlands locale, then, and following calls to +books_path+ should return +"/nl/books"+ (because the locale changed).
 
-Of course, you need to take special care of the root URL (usually "homepage" or "dashboard") of your application. An URL like +http://localhost:3001/nl+ will not work automatically, because the +map.root :controller => "dashboard"+ declaration in your +routes.rb+ doesn't take locale into account. (And rightly so: there's only one "root" URL.)
+Of course, you need to take special care of the root URL (usually "homepage" or "dashboard") of your application. An URL like +http://localhost:3001/nl+ will not work automatically, because the +root :to => "books#index"+ declaration in your +routes.rb+ doesn't take locale into account. (And rightly so: there's only one "root" URL.)
 
 You would probably need to map URLs like these:
 
 <ruby>
 # config/routes.rb
-map.dashboard '/:locale', :controller => "dashboard"
+match '/:locale' => 'dashboard#index'
 </ruby>
 
-Do take special care about the *order of your routes*, so this route declaration does not "eat" other ones. (You may want to add it directly before the +map.root+ declaration.)
+Do take special care about the *order of your routes*, so this route declaration does not "eat" other ones. (You may want to add it directly before the +root :to+ declaration.)
 
 IMPORTANT: This solution has currently one rather big *downside*. Due to the _default_url_options_ implementation, you have to pass the +:id+ option explicitly, like this: +link_to 'Show', book_url(:id => book)+ and not depend on Rails' magic in code like +link_to 'Show', book+. If this should be a problem, have a look at two plugins which simplify work with routes in this way: Sven Fuchs's "routing_filter":http://github.com/svenfuchs/routing-filter/tree/master and Raul Murciano's "translate_routes":http://github.com/raul/translate_routes/tree/master. See also the page "How to encode the current locale in the URL":http://rails-i18n.org/wiki/wikipages/how-to-encode-the-current-locale-in-the-url in the Rails i18n Wiki.
 
@@ -288,8 +287,8 @@ You most probably have something like this in one of your applications:
 
 <ruby>
 # config/routes.rb
-ActionController::Routing::Routes.draw do |map|
-  map.root :controller => 'home', :action => 'index'
+Yourapp::Application.routes.draw do |map|
+  root :to => "home#index"
 end
 
 # app/controllers/home_controller.rb
@@ -422,8 +421,9 @@ This way, you can separate model and model attribute names from text inside view
 NOTE: The default locale loading mechanism in Rails does not load locale files in nested dictionaries, like we have here. So, for this to work, we must explicitly tell Rails to look further:
 
 <ruby>
-  # config/environment.rb
-  config.i18n.load_path += Dir[File.join(RAILS_ROOT, 'config', 'locales', '**', '*.{rb,yml}')]
+  # config/application.rb
+  config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]
+
 </ruby>
 
 Do check the "Rails i18n Wiki":http://rails-i18n.org/wiki for list of tools available for managing translations.

railties/guides/source/initialization.textile

@@ -844,7 +844,7 @@ The ActiveRecord Railtie takes care of hooking ActiveRecord into Rails. This dep
 
 TODO: Quotify.
 
-<text>
+<plain>
   Active Record connects business objects and database tables to create a persistable domain model where logic and data are presented in one wrapping. It's an implementation of the object-relational mapping (ORM) pattern by the same name as described by Martin Fowler:
 
     "An object that wraps a row in a database table or view, encapsulates 
@@ -854,7 +854,7 @@ TODO: Quotify.
   lack of associations and inheritance. By adding a simple domain language-like set of macros to describe
   the former and integrating the Single Table Inheritance pattern for the latter, Active Record narrows the
   gap of functionality between the data mapper and active record approach.
-</text>
+</plain>
 
 h5. +require "active_record/railtie"+
 
@@ -989,13 +989,13 @@ This Railtie is +require+'d by ActiveRecord's Railtie.
 
 From the ActiveModel readme:
 
-<text>
+<plain>
   Prior to Rails 3.0, if a plugin or gem developer wanted to be able to have an object interact with Action Pack helpers, it was required to either copy chunks of code from Rails, or monkey patch entire helpers to make them handle objects that did not look like Active Record.  This generated code duplication and fragile applications that broke on upgrades. 
 
   Active Model is a solution for this problem.
 
   Active Model provides a known set of interfaces that your objects can implement to then present a common interface to the Action Pack helpers.
-</text>
+</plain>
 
 
 h5. +require "active_model/railtie"+
@@ -1249,9 +1249,9 @@ In _encoding.rb_ it's used to define a constant that's now been deprecated:
 
 Now when you reference +ActiveSupport::JSON::CircularReferenceError+ you'll receive a warning:
 
-<text>
+<plain>
   ActiveSupport::JSON::CircularReferenceError is deprecated! Use Encoding::CircularReferenceError instead.
-</text>
+</plain>
 
 h5. +require "active_support/deprecation"+
 
@@ -2268,6 +2268,12 @@ The first method to be called here is +autorequires_for_groups+:
     end
 </ruby>
 
+The +specs_for+ method here:
+
+<ruby>
+
+</ruby>
+
 
 h3. Firing it up!
 

railties/guides/source/migrations.textile

@@ -568,7 +568,7 @@ In many ways this is exactly what it is. This file is created by inspecting the
 
 There is however a trade-off: +db/schema.rb+ cannot express database specific items such as foreign key constraints, triggers or stored procedures. While in a migration you can execute custom SQL statements, the schema dumper cannot reconstitute those statements from the database. If you are using features like this then you should set the schema format to +:sql+.
 
-Instead of using Active Record's schema dumper the database's structure will be dumped using a tool specific to that database (via the +db:structure:dump+ Rake task) into +db/#{RAILS_ENV}_structure.sql+. For example for PostgreSQL the +pg_dump+ utility is used and for MySQL this file will contain the output of +SHOW CREATE TABLE+ for the various tables. Loading this schema is simply a question of executing the SQL statements contained inside.
+Instead of using Active Record's schema dumper the database's structure will be dumped using a tool specific to that database (via the +db:structure:dump+ Rake task) into +db/#{Rails.env}_structure.sql+. For example for PostgreSQL the +pg_dump+ utility is used and for MySQL this file will contain the output of +SHOW CREATE TABLE+ for the various tables. Loading this schema is simply a question of executing the SQL statements contained inside.
 
 By definition this will be a perfect copy of the database's structure but this will usually prevent loading the schema into a database other than the one used to create it.
 

railties/guides/source/rails_application_templates.textile

@@ -113,7 +113,7 @@ CODE
 
 Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory.
 
-There is even +file()+, which accepts a relative path from +RAILS_ROOT+ and creates all the directories/file needed :
+There is even +file()+, which accepts a relative path from +Rails.root+ and creates all the directories/file needed :
 
 <ruby>
 file 'app/components/foo.rb', <<-CODE

railties/guides/source/rails_on_rack.textile

@@ -49,15 +49,15 @@ Middlewares used in the code above are primarily useful only in the development
 
 |_.Middleware|_.Purpose|
 |+Rails::Rack::LogTailer+|Appends log file output to console|
-|+ActionDispatch::Static+|Serves static files inside +RAILS_ROOT/public+ directory|
+|+ActionDispatch::Static+|Serves static files inside +Rails.root/public+ directory|
 |+Rails::Rack::Debugger+|Starts Debugger|
 
 h4. +rackup+
 
 To use +rackup+ instead of Rails' +rails server+, you can put the following inside +config.ru+ of your Rails application's root directory:
 
 <ruby>
-# RAILS_ROOT/config.ru
+# Rails.root/config.ru
 require "config/environment"
 
 use Rails::Rack::LogTailer
@@ -214,7 +214,7 @@ config.middleware.clear
 </ruby>
 
 <br />
-<strong>Add a +config.ru+ file to +RAILS_ROOT+</strong>
+<strong>Add a +config.ru+ file to +Rails.root+</strong>
 
 <ruby>
 # config.ru

railties/guides/source/testing.textile

@@ -65,7 +65,7 @@ YAML-formatted fixtures are a very human-friendly way to describe your sample da
 Here's a sample YAML fixture file:
 
 <yaml>
-# low & behold!  I am a YAML comment!
+# lo & behold!  I am a YAML comment!
 david:
  name: David Heinemeier Hansson
  birthday: 1979-10-15

railties/lib/rails/application/configuration.rb

@@ -53,7 +53,7 @@ def paths
           paths.vendor.plugins     "vendor/plugins"
 
           if File.exists?("#{root}/test/mocks/#{Rails.env}")
-            ActiveSupport::Deprecation.warn "\"RAILS_ROOT/test/mocks/#{Rails.env}\" won't be added " <<
+            ActiveSupport::Deprecation.warn "\"Rails.root/test/mocks/#{Rails.env}\" won't be added " <<
               "automatically to load paths anymore in future releases"
             paths.mocks_path  "test/mocks", :load_path => true, :glob => Rails.env
           end