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

Conflicts:
	actionpack/lib/action_view/helpers/date_helper.rb
	railties/lib/rails/generators/rails/app/templates/config/initializers/wrap_parameters.rb.tt

13 files changed, 116 insertions, 56 deletions

diff --git a/railties/guides/rails_guides/generator.rb b/railties/guides/rails_guides/generator.rb
index 154355cac1..14d671c8f3 100644
--- a/railties/guides/rails_guides/generator.rb
+++ b/railties/guides/rails_guides/generator.rb
@@ -38,9 +38,10 @@
 #     Note that if you are working on a guide generation will by default process
 #     only that one, so ONLY is rarely used nowadays.
 #
-#   LANGUAGE
-#     Use LANGUAGE when you want to generate translated guides in <tt>source/<LANGUAGE></tt>
-#     folder (such as <tt>source/es</tt>). Ignore it when generating English guides.
+#   GUIDES_LANGUAGE
+#     Use GUIDES_LANGUAGE when you want to generate translated guides in
+#     <tt>source/<GUIDES_LANGUAGE></tt> folder (such as <tt>source/es</tt>).
+#     Ignore it when generating English guides.
 #
 #   EDGE
 #     Set to "1" to indicate generated guides should be marked as edge. This
@@ -67,7 +68,7 @@ module RailsGuides
     GUIDES_RE = /\.(?:textile|html\.erb)$/
 
     def initialize(output=nil)
-      @lang = ENV['LANGUAGE']
+      @lang = ENV['GUIDES_LANGUAGE']
       initialize_dirs(output)
       create_output_dir_if_needed
       set_flags_from_environment
diff --git a/railties/guides/source/action_controller_overview.textile b/railties/guides/source/action_controller_overview.textile
index 3a1a4ee66e..891bae3d5e 100644
--- a/railties/guides/source/action_controller_overview.textile
+++ b/railties/guides/source/action_controller_overview.textile
@@ -110,6 +110,32 @@ When this form is submitted, the value of +params[:client]+ will be <tt>{"name"
 
 Note that the +params+ hash is actually an instance of +HashWithIndifferentAccess+ from Active Support, which acts like a hash that lets you use symbols and strings interchangeably as keys.
 
+h4. JSON/XML parameters
+
+If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON or XML format. Rails will automatically convert your parameters into +params+ hash, which you'll be able to access like you would normally do with form data.
+
+So for example, if you are sending this JSON parameter:
+
+<pre>
+{ "company": { "name": "acme", "address": "123 Carrot Street" } }
+</pre>
+
+You'll get <tt>params[:company]</tt> as <tt>{ :name => "acme", "address" => "123 Carrot Street" }</tt>.
+
+Also, if you've turned on +config.wrap_parameters+ in your initializer or calling +wrap_parameters+ in your controller, you can safely omit the root element in the JSON/XML parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as:
+
+<pre>
+{ "name": "acme", "address": "123 Carrot Street" }
+</pre>
+
+And assume that you're sending the data to +CompaniesController+, it would then be wrapped in +:company+ key like this:
+
+<ruby>
+{ :name => "acme", :address => "123 Carrot Street", :company => { :name => "acme", :address => "123 Carrot Street" }}
+</ruby>
+
+You can customize the name of the key or specific parameters you want to wrap by consulting the "API documentation":http://api.rubyonrails.org/classes/ActionController/ParamsWrapper.html
+
 h4. Routing Parameters
 
 The +params+ hash will always contain the +:controller+ and +:action+ keys, but you should use the methods +controller_name+ and +action_name+ instead to access these values. Any other parameters defined by the routing, such as +:id+ will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the +:status+ parameter in a "pretty" URL:
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index d82bdfee43..66869b4eeb 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -1841,6 +1841,8 @@ The method +ordinalize+ returns the ordinal string corresponding to the receiver
 2.ordinalize    # => "2nd"
 53.ordinalize   # => "53rd"
 2009.ordinalize # => "2009th"
+-21.ordinalize  # => "-21st"
+-134.ordinalize # => "-134th"
 </ruby>
 
 NOTE: Defined in +active_support/core_ext/integer/inflections.rb+.
diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile
index 94dce1b97b..458bfefad8 100644
--- a/railties/guides/source/association_basics.textile
+++ b/railties/guides/source/association_basics.textile
@@ -342,9 +342,9 @@ In designing a data model, you will sometimes find a model that should have a re
 
 <ruby>
 class Employee < ActiveRecord::Base
-  has_many :subordinates, :class_name => "Employee",
+  has_many :subordinates, :class_name => "Employee"
+  belongs_to :manager, :class_name => "Employee",
     :foreign_key => "manager_id"
-  belongs_to :manager, :class_name => "Employee"
 end
 </ruby>
 
diff --git a/railties/guides/source/caching_with_rails.textile b/railties/guides/source/caching_with_rails.textile
index 799339e674..91827fd493 100644
--- a/railties/guides/source/caching_with_rails.textile
+++ b/railties/guides/source/caching_with_rails.textile
@@ -98,7 +98,7 @@ You can also use +:if+ (or +:unless+) to pass a Proc that specifies when the act
 
 You can modify the default action cache path by passing a +:cache_path+ option. This will be passed directly to +ActionCachePath.path_for+. This is handy for actions with multiple possible routes that should be cached differently. If a block is given, it is called with the current controller instance.
 
-Finally, if you are using memcached, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store.
+Finally, if you are using memcached or Ehcache, you can also pass +:expires_in+. In fact, all parameters not used by +caches_action+ are sent to the underlying cache store.
 
 INFO: Action caching runs in an after filter. Thus, invalid requests won't generate spurious cache entries as long as you halt them. Typically, a redirection in some before filter that checks request preconditions does the job.
 
@@ -304,6 +304,35 @@ The +write+ and +fetch+ methods on this cache accept two additional options that
 ActionController::Base.cache_store = :mem_cache_store, "cache-1.example.com", "cache-2.example.com"
 </ruby>
 
+h4. ActiveSupport::Cache::EhcacheStore
+
+If you are using JRuby you can use Terracotta's Ehcache as the cache store for your application. Ehcache is an open source Java cache that also offers an enterprise version with increased scalability, management, and commercial support. You must first install the jruby-ehcache-rails3 gem (version 1.1.0 or later) to use this cache store.
+
+<ruby>
+ActionController::Base.cache_store = :ehcache_store
+</ruby>
+
+When initializing the cache, you may use the +:ehcache_config+ option to specify the Ehcache config file to use (where the default is "ehcache.xml" in your Rails config directory), and the :cache_name option to provide a custom name for your cache (the default is rails_cache).
+
+In addition to the standard +:expires_in+ option, the +write+ method on this cache can also accept the additional  +:unless_exist+ option, which will cause the cache store to use Ehcache's +putIfAbsent+ method instead of +put+, and therefore will not overwrite an existing entry. Additionally, the +write+ method supports all of the properties exposed by the "Ehcache Element class":http://ehcache.org/apidocs/net/sf/ehcache/Element.html , including:
+
+|_. Property |_. Argument Type |_. Description |
+| elementEvictionData | ElementEvictionData | Sets this element's eviction data instance. |
+| eternal | boolean | Sets whether the element is eternal. |
+| timeToIdle, tti | int | Sets time to idle |
+| timeToLive, ttl, expires_in | int | Sets time to Live |
+| version | long | Sets the version attribute of the ElementAttributes object. |
+
+These options are passed to the +write+ method as Hash options using either camelCase or underscore notation, as in the following examples:
+
+<ruby>
+Rails.cache.write('key', 'value', :time_to_idle => 60.seconds, :timeToLive => 600.seconds)
+caches_action :index, :expires_in => 60.seconds, :unless_exist => true
+</ruby>
+
+For more information about Ehcache, see "http://ehcache.org/":http://ehcache.org/ .
+For more information about Ehcache for JRuby and Rails, see "http://ehcache.org/documentation/jruby.html":http://ehcache.org/documentation/jruby.html
+
 h4. Custom Cache Stores
 
 You can create your own custom cache store by simply extending +ActiveSupport::Cache::Store+ and implementing the appropriate methods. In this way, you can swap in any number of caching technologies into your Rails application.
diff --git a/railties/guides/source/contributing_to_ruby_on_rails.textile b/railties/guides/source/contributing_to_ruby_on_rails.textile
index cb09b180a2..5eb925d7d2 100644
--- a/railties/guides/source/contributing_to_ruby_on_rails.textile
+++ b/railties/guides/source/contributing_to_ruby_on_rails.textile
@@ -232,11 +232,11 @@ You can also help out by examining pull requests that have been submitted to Rub
 $ git checkout -b testing_branch
 </shell>
 
-Then you can use their remote branch to update your codebase. For example, let's say the GitHub user JohnSmith has forked and pushed to the master branch located at https://github.com/JohnSmith/rails.
+Then you can use their remote branch to update your codebase. For example, let's say the GitHub user JohnSmith has forked and pushed to the topic branch located at https://github.com/JohnSmith/rails.
 
 <shell>
 $ git remote add JohnSmith git://github.com/JohnSmith/rails.git
-$ git pull JohnSmith master
+$ git pull JohnSmith topic
 </shell>
 
 After applying their branch, test it out! Here are some things to think about:
@@ -300,10 +300,16 @@ h4. Follow the Coding Conventions
 
 Rails follows a simple set of coding style conventions.
 
-* Two spaces, no tabs
-* Prefer +&amp;&amp;+/+||+ over +and+/+or+
-* +MyClass.my_method(my_arg)+ not +my_method( my_arg )+ or +my_method my_arg+
-* Follow the conventions you see used in the source already
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Indent after private/protected.
+* Prefer +&amp;&amp;+/+||+ over +and+/+or+.
+* Prefer class << self block over self.method for class methods.
+* +MyClass.my_method(my_arg)+ not +my_method( my_arg )+ or +my_method my_arg+.
+* a = b and not a=b.
+* Follow the conventions you see used in the source already.
+
+These are some guidelines and please use your best judgement in using them.
 
 h4. Sanity Check
 
@@ -344,20 +350,22 @@ Navigate to the Rails "GitHub repository":https://github.com/rails/rails and pre
 Add the new remote to your local repository on your local machine:
 
 <shell>
-$ git remote add mine https://&lt;your user name&gt;@github.com/&lt;your user name&gt;/rails.git
+$ git remote add mine https://<your user name>@github.com/<your user name>/rails.git
 </shell>
 
 Push to your remote:
 
 <shell>
-$ git push mine master
+$ git push mine my_new_branch
 </shell>
 
 h4. Issue a Pull Request
 
-Navigate to the Rails repository you just pushed to (e.g. https://github.com/&lt;your user name&gt;/rails) and press "Pull Request" in the upper right hand corner.
-  
-Ensure the changesets you introduced are included in the "Commits" tab and that the "Files Changed" incorporate all of your changes. 
+Navigate to the Rails repository you just pushed to (e.g. https://github.com/<your user name>/rails) and press "Pull Request" in the upper right hand corner.
+
+Write your branch name in branch field (is filled with master by default) and press "Update Commit Range"
+
+Ensure the changesets you introduced are included in the "Commits" tab and that the "Files Changed" incorporate all of your changes.
 
 Fill in some details about your potential patch including a meaningful title. When finished, press "Send pull request." Rails Core will be notified about your submission.
 
@@ -377,6 +385,7 @@ All contributions, either via master or docrails, get credit in "Rails Contribut
 
 h3. Changelog
 
+* May 12, 2011: Modified to prefer topic branches instead of master branch for users contributions by "Guillermo Iguaran":http://quillarb.org
 * April 29, 2011: Reflect GitHub Issues and Pull Request workflow by "Dan Pickett":http://www.enlightsolutions.com
 * April 14, 2011: Modified Contributing to the Rails Code section to add '[#ticket_number state:commited]' on patches commit messages by "Sebastian Martinez":http://wyeworks.com
 * December 28, 2010: Complete revision by "Xavier Noria":credits.html#fxn
diff --git a/railties/guides/source/generators.textile b/railties/guides/source/generators.textile
index ac709968d9..a3181b9ac5 100644
--- a/railties/guides/source/generators.textile
+++ b/railties/guides/source/generators.textile
@@ -111,7 +111,6 @@ In order to understand what a generator template means, let's create the file +l
 
 <ruby>
 # Add initialization content here
-
 </ruby>
 
 And now let's change the generator to copy this template when invoked:
@@ -286,8 +285,8 @@ end
 Now, when the helper generator is invoked and TestUnit is configured as the test framework, it will try to invoke both +Rails::TestUnitGenerator+ and +TestUnit::MyHelperGenerator+. Since none of those are defined, we can tell our generator to invoke +TestUnit::Generators::HelperGenerator+ instead, which is defined since it's a Rails generator. To do that, we just need to add:
 
 <ruby>
-  # Search for :helper instead of :my_helper
-  hook_for :test_framework, :as => :helper
+# Search for :helper instead of :my_helper
+hook_for :test_framework, :as => :helper
 </ruby>
 
 And now you can re-run scaffold for another resource and see it generating tests as well!
@@ -412,7 +411,7 @@ h4. +plugin+
 +plugin+ will install a plugin into the current application.
 
 <ruby>
-  plugin("dynamic-form", :git => "git://github.com/rails/dynamic-form.git")
+plugin("dynamic-form", :git => "git://github.com/rails/dynamic-form.git")
 </ruby>
 
 Available options are:
@@ -441,13 +440,13 @@ Available options are:
 Any additional options passed to this method are put on the end of the line:
 
 <ruby>
-  gem("devise", :git => "git://github.com/plataformatec/devise", :branch => "master")
+gem("devise", :git => "git://github.com/plataformatec/devise", :branch => "master")
 </ruby>
 
 The above code will put the following line into +Gemfile+:
 
 <ruby>
-  gem "devise", :git => "git://github.com/plataformatec/devise", :branch => "master"
+gem "devise", :git => "git://github.com/plataformatec/devise", :branch => "master"
 </ruby>
 
 
@@ -456,7 +455,7 @@ h4. +add_source+
 Adds a specified source to +Gemfile+:
 
 <ruby>
-  add_source "http://gems.github.com"
+add_source "http://gems.github.com"
 </ruby>
 
 h4. +application+
@@ -464,7 +463,7 @@ h4. +application+
 Adds a line to +config/application.rb+ directly after the application class definition.
 
 <ruby>
-  application "config.asset_host = 'http://example.com'"
+application "config.asset_host = 'http://example.com'"
 </ruby>
 
 This method can also take a block:
@@ -490,10 +489,10 @@ h4. +git+
 Runs the specified git command:
 
 <ruby>
-  git :init
-  git :add => "."
-  git :commit => "-m First commit!"
-  git :add => "onefile.rb", :rm => "badfile.cxx"
+git :init
+git :add => "."
+git :commit => "-m First commit!"
+git :add => "onefile.rb", :rm => "badfile.cxx"
 </ruby>
 
 The values of the hash here being the arguments or options passed to the specific git command. As per the final example shown here, multiple git commands can be specified at a time, but the order of their running is not guaranteed to be the same as the order that they were specified in.
@@ -503,15 +502,15 @@ h4. +vendor+
 Places a file into +vendor+ which contains the specified code.
 
 <ruby>
-  vendor("sekrit.rb", '#top secret stuff')
+vendor("sekrit.rb", '#top secret stuff')
 </ruby>
 
 This method also takes a block:
 
 <ruby>
-  vendor("seeds.rb") do
-    "puts 'in ur app, seeding ur database'"
-  end
+vendor("seeds.rb") do
+  "puts 'in ur app, seeding ur database'"
+end
 </ruby>
 
 h4. +lib+
@@ -519,7 +518,7 @@ h4. +lib+
 Places a file into +lib+ which contains the specified code.
 
 <ruby>
-  lib("special.rb", 'p Rails.root')
+lib("special.rb", 'p Rails.root')
 </ruby>
 
 This method also takes a block:
@@ -535,7 +534,7 @@ h4. +rakefile+
 Creates a Rake file in the +lib/tasks+ directory of the application.
 
 <ruby>
-  rakefile("test.rake", 'hello there')
+rakefile("test.rake", 'hello there')
 </ruby>
 
 This method also takes a block:
@@ -555,7 +554,7 @@ h4. +initializer+
 Creates an initializer in the +config/initializers+ directory of the application:
 
 <ruby>
-  initializer("begin.rb", "puts 'this is the beginning'")
+initializer("begin.rb", "puts 'this is the beginning'")
 </ruby>
 
 This method also takes a block:
@@ -571,7 +570,7 @@ h4. +generate+
 Runs the specified generator where the first argument is the generator name and the remaining arguments are passed directly to the generator.
 
 <ruby>
-  generate("scaffold", "forums title:string description:text")
+generate("scaffold", "forums title:string description:text")
 </ruby>
 
 
@@ -580,7 +579,7 @@ h4. +rake+
 Runs the specified Rake task.
 
 <ruby>
-  rake("db:migrate")
+rake("db:migrate")
 </ruby>
 
 Available options are:
@@ -593,7 +592,7 @@ h4. +capify!+
 Runs the +capify+ command from Capistrano at the root of the application which generates Capistrano configuration.
 
 <ruby>
-  capify!
+capify!
 </ruby>
 
 h4. +route+
@@ -601,7 +600,7 @@ h4. +route+
 Adds text to the +config/routes.rb+ file:
 
 <ruby>
-  route("resources :people")
+route("resources :people")
 </ruby>
 
 h4. +readme+
@@ -609,7 +608,7 @@ h4. +readme+
 Output the contents of a file in the template's +source_path+, usually a README.
 
 <ruby>
-  readme("README")
+readme("README")
 </ruby>
 
 h3. Changelog
diff --git a/railties/guides/source/rails_on_rack.textile b/railties/guides/source/rails_on_rack.textile
index b1db2942dd..aa53aa6db6 100644
--- a/railties/guides/source/rails_on_rack.textile
+++ b/railties/guides/source/rails_on_rack.textile
@@ -117,8 +117,6 @@ You can add a new middleware to the middleware stack using any of the following
 
 * +config.middleware.insert_after(existing_middleware, new_middleware, args)+ - Adds the new middleware after the specified existing middleware in the middleware stack.
 
-<strong>Example:</strong>
-
 <ruby>
 # config/environment.rb
 
@@ -134,8 +132,6 @@ h5. Swapping a Middleware
 
 You can swap an existing middleware in the middleware stack using +config.middleware.swap+.
 
-<strong>Example:</strong>
-
 <ruby>
 # config/environment.rb
 
@@ -173,8 +169,6 @@ h4. Customizing Internal Middleware Stack
 
 It's possible to replace the entire middleware stack with a custom stack using +ActionController::Dispatcher.middleware=+.
 
-<strong>Example:</strong>
-
 Put the following in an initializer:
 
 <ruby>
diff --git a/railties/guides/source/testing.textile b/railties/guides/source/testing.textile
index 38b8d0d521..7a93c3a1e6 100644
--- a/railties/guides/source/testing.textile
+++ b/railties/guides/source/testing.textile
@@ -38,7 +38,7 @@ When you do end up destroying your testing database (and it will happen, trust m
 
 h4. Rails Sets up for Testing from the Word Go
 
-Rails creates a +test+ folder for you as soon as you create a Rails project using +rails _application_name_+. If you list the contents of this folder then you shall see:
+Rails creates a +test+ folder for you as soon as you create a Rails project using +rails new+ _application_name_. If you list the contents of this folder then you shall see:
 
 <shell>
 $ ls -F test/
diff --git a/railties/lib/rails/generators/base.rb b/railties/lib/rails/generators/base.rb
index 8d03cb911b..1f6a7a2f59 100644
--- a/railties/lib/rails/generators/base.rb
+++ b/railties/lib/rails/generators/base.rb
@@ -117,8 +117,8 @@ module Rails
       #
       # ==== Switches
       #
-      # All hooks come with switches for user interface. If the user don't want
-      # to use any test framework, he can do:
+      # All hooks come with switches for user interface. If you do not want
+      # to use any test framework, you can do:
       #
       #   rails generate controller Account --skip-test-framework
       #
diff --git a/railties/lib/rails/generators/rails/app/app_generator.rb b/railties/lib/rails/generators/rails/app/app_generator.rb
index d8447ec694..5f9fb9685c 100644
--- a/railties/lib/rails/generators/rails/app/app_generator.rb
+++ b/railties/lib/rails/generators/rails/app/app_generator.rb
@@ -30,7 +30,7 @@ module Rails
   # generator.
   #
   # This allows you to override entire operations, like the creation of the
-  # Gemfile, README, or javascript files, without needing to know exactly
+  # Gemfile, README, or JavaScript files, without needing to know exactly
   # what those operations do so you can create another template action.
   class AppBuilder
     def rakefile
diff --git a/railties/lib/rails/generators/rails/app/templates/config/environments/production.rb.tt b/railties/lib/rails/generators/rails/app/templates/config/environments/production.rb.tt
index 9553f3bdde..1c3dc1117f 100644
--- a/railties/lib/rails/generators/rails/app/templates/config/environments/production.rb.tt
+++ b/railties/lib/rails/generators/rails/app/templates/config/environments/production.rb.tt
@@ -31,7 +31,7 @@
   # Use a different cache store in production
   # config.cache_store = :mem_cache_store
 
-  # Enable serving of images, stylesheets, and javascripts from an asset server
+  # Enable serving of images, stylesheets, and JavaScripts from an asset server
   # config.action_controller.asset_host = "http://assets.example.com"
 
   # Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)
diff --git a/railties/lib/rails/generators/rails/assets/USAGE b/railties/lib/rails/generators/rails/assets/USAGE
index adebfd7e6f..c5375cdc06 100644
--- a/railties/lib/rails/generators/rails/assets/USAGE
+++ b/railties/lib/rails/generators/rails/assets/USAGE
@@ -1,8 +1,8 @@
 Description:
-    Stubs out a new asset placeholders. Pass the asset name, either CamelCased
+    Stubs out new asset placeholders. Pass the asset name, either CamelCased
     or under_scored.
 
-    To create assets within a folder, specify the assets name as a
+    To create an asset within a folder, specify the asset's name as a
     path like 'parent/name'.
 
     This generates a JavaScript stub in app/assets/javascripts and a stylesheet
@@ -15,6 +15,6 @@ Example:
     `rails generate assets posts`
 
     Posts assets.
-        Javascript:     app/assets/javascripts/posts.js
+        JavaScript:     app/assets/javascripts/posts.js
         Stylesheet:     app/assets/stylesheets/posts.css