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

5 files changed, 46 insertions, 38 deletions

diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile
index 9346a408e0..781b9001b6 100644
--- a/railties/guides/source/active_record_validations_callbacks.textile
+++ b/railties/guides/source/active_record_validations_callbacks.textile
@@ -1192,13 +1192,11 @@ h4. Creating Observers
 
 For example, imagine a +User+ model where we want to send an email every time a new user is created. Because sending emails is not directly related to our model's purpose, we should create an observer to contain the code implementing this functionality.
 
-Rails can create the initial code of the observers in a simple way. For instance, given a model +User+, the command
-
 <shell>
 $ rails generate observer User
 </shell>
 
-generates file +app/models/user_observer.rb+ containing the observer class +UserObserver+:
+generates +app/models/user_observer.rb+ containing the observer class +UserObserver+:
 
 <ruby>
 class UserObserver < ActiveRecord::Observer
diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile
index b343e8d01d..7795b297f3 100644
--- a/railties/guides/source/asset_pipeline.textile
+++ b/railties/guides/source/asset_pipeline.textile
@@ -152,15 +152,15 @@ Images can also be organized into subdirectories if required, and they can be ac
 
 h5. CSS and ERB
 
-If you add an +erb+ extension to a CSS asset, making it something such as +application.css.erb+, then helpers like +image_path+ are available in your CSS rules:
+If you add an +erb+ extension to a CSS asset, making it something such as +application.css.erb+, then helpers like +asset_path+ are available in your CSS rules:
 
 <plain>
-.class { background-image: url(<%= image_path 'image.png' %>) }
+.class { background-image: url(<%= asset_path 'image.png' %>) }
 </plain>
 
 This writes the path to the particular asset being referenced. In this example, it would make sense to have an image in one of the asset load paths, such as +app/assets/images/image.png+, which would be referenced here. If this image is already available in +public/assets+ as a fingerprinted file, then that path is referenced.
 
-If you want to use a "css data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the +asset_data_uri+ helper.
+If you want to use a "data URI":http://en.wikipedia.org/wiki/Data_URI_scheme -- a method of embedding the image data directly into the CSS file -- you can use the +asset_data_uri+ helper.
 
 <plain>
 #logo { background: url(<%= asset_data_uri 'logo.png' %>) }
@@ -186,27 +186,28 @@ h5. JavaScript/CoffeeScript and ERB
 
 If you add an +erb+ extension to a JavaScript asset, making it something such as +application.js.erb+, then you can use the +asset_path+ helper in your JavaScript code:
 
-<plain>
+<erb>
 $('#logo').attr({
   src: "<%= asset_path('logo.png') %>"
 });
-</plain>
+</erb>
 
 This writes the path to the particular asset being referenced.
 
-Similarly, you can use the +asset_path+ helper in CoffeeScript files with +erb+ extension (eg. application.js.coffee.erb):
+Similarly, you can use the +asset_path+ helper in CoffeeScript files with +erb+ extension (eg. +application.js.coffee.erb+):
 
 <plain>
-$('#logo').attr src: "<% asset_path('logo.png') %>"
+$('#logo').attr src: "<%= asset_path('logo.png') %>"
 </plain>
 
 h4. Manifest Files and Directives
 
-Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is set to +true+). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make.
+Sprockets uses manifest files to determine which assets to include and serve. These manifest files contain _directives_ -- instructions that tell Sprockets which files to require in order to build a single CSS or JavaScript file. With these directives, Sprockets loads the files specified, processes them if necessary, concatenates them into one single file and then compresses them (if +Rails.application.config.assets.compress+ is true). By serving one file rather than many, the load time of pages are greatly reduced as there are fewer requests to make.
 
 For example, in the default Rails application there's a +app/assets/javascripts/application.js+ file which contains the following lines:
 
 <plain>
+// ...
 //= require jquery
 //= require jquery_ujs
 //= require_tree .
@@ -214,9 +215,11 @@ For example, in the default Rails application there's a +app/assets/javascripts/
 
 In JavaScript files, the directives begin with +//=+. In this case, the file is using the +require+ and the +require_tree+ directives. The +require+ directive is used to tell Sprockets the files that you wish to require. Here, you are requiring the files +jquery.js+ and +jquery_ujs.js+ that are available somewhere in the search path for Sprockets. You need not supply the extensions explicitly. Sprockets assumes you are requiring a +.js+ file when done from within a +.js+ file.
 
-NOTE. In Rails 3.1, the +jquery.js+ and +jquery_ujs.js+ files are located inside the +vendor/assets/javascripts+ directory contained within the +jquery-rails+ gem.
+NOTE. In Rails 3.1 the +jquery-rails+ gem provides the +jquery.js+ and +jquery_ujs.js+ files via the asset pipeline. You won't see them in the application tree.
 
-The +require_tree .+ directive tells Sprockets to include _all_ JavaScript files in this directory into the output. Only a path relative to the file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting).
+The +require_tree+ directive tells Sprockets to recursively include _all_ JavaScript files in this directory into the output. Only a path relative to the manifest file can be specified. There is also a +require_directory+ directive which includes all JavaScript files only in the directory specified (no nesting).
+
+Directives are processed top to bottom, but the order in which files are included by +require_tree+ is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other, require it before in the manifest. Note that the family of +require+ directives prevents files from being included twice in the output.
 
 There's also a default +app/assets/stylesheets/application.css+ file which contains these lines:
 
@@ -233,7 +236,7 @@ In this example +require_self+ is used. This puts the CSS contained within the f
 
 You can have as many manifest files as you need. For example the +admin.css+ and +admin.js+ manifest could contain the JS and CSS files that are used for the admin section of an application.
 
-For some assets (like CSS) the compiled order is important. You can specify individual files and they are compiled in the order specified:
+The same remarks about ordering made above apply. In particular, you can specify individual files and they are compiled in the order specified:
 
 <plain>
 /* ...
@@ -246,19 +249,19 @@ For some assets (like CSS) the compiled order is important. You can specify indi
 
 h4. Preprocessing
 
-The file extensions used on an asset determine what preprocessing is applied. When a controller or a scaffold is generated with the default Rails gemset, a CoffeeScript file and a SCSS file are generated in place of a regular JavaScript and CSS file. The example used before was a controller called "projects", which generated an +app/assets/javascripts/projects.js.coffee+ and a +app/assets/stylesheets/projects.css.scss+ file.
+The file extensions used on an asset determine what preprocessing is applied. When a controller or a scaffold is generated with the default Rails gemset, a CoffeeScript file and a SCSS file are generated in place of a regular JavaScript and CSS file. The example used before was a controller called "projects", which generated an +app/assets/javascripts/projects.js.coffee+ and an +app/assets/stylesheets/projects.css.scss+ file.
 
 When these files are requested, they are processed by the processors provided by the +coffee-script+ and +sass-rails+ gems and then sent back to the browser as JavaScript and CSS respectively.
-Additional layers of pre-processing can be requested by adding other extensions, where each extension is processed in a right-to-left manner. These should be used in the order the processing should be applied. For example, a stylesheet called +app/assets/stylesheets/projects.css.scss.erb+ is first processed as ERB, then SCSS and finally served as CSS. The same applies to a JavaScript file -- +app/assets/javascripts/projects.js.coffee.erb+ is processed as ERB, CoffeeScript and served as JavaScript.
 
+Additional layers of preprocessing can be requested by adding other extensions, where each extension is processed in a right-to-left manner. These should be used in the order the processing should be applied. For example, a stylesheet called +app/assets/stylesheets/projects.css.scss.erb+ is first processed as ERB, then SCSS and finally served as CSS. The same applies to a JavaScript file -- +app/assets/javascripts/projects.js.coffee.erb+ is processed as ERB, CoffeeScript, and served as JavaScript.
 
-Keep in mind that the order of these pre-processors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it is processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems.
+Keep in mind that the order of these preprocessors is important. For example, if you called your JavaScript file +app/assets/javascripts/projects.js.erb.coffee+ then it would be processed with the CoffeeScript interpreter first, which wouldn't understand ERB and therefore you would run into problems.
 
 h3. In Development
 
 In development mode assets are served as separate files in the order they are specified in the manifest file.
 
-This manifest +application.js+:
+This manifest +app/assets/javascripts/application.js+:
 
 <plain>
 //= require core
@@ -269,45 +272,42 @@ This manifest +application.js+:
 would generate this HTML:
 
 <html>
-<script src='/assets/core.js?body=1'></script>
-<script src='/assets/projects.js?body=1'></script>
-<script src='/assets/tickets.js?body=1'></script>
+<script src="/assets/core.js?body=1" type="text/javascript"></script>
+<script src="/assets/projects.js?body=1" type="text/javascript"></script>
+<script src="/assets/tickets.js?body=1" type="text/javascript"></script>
 </html>
 
 The +body+ param is required by Sprockets.
 
 h4. Turning Debugging off
 
-You can turn off debug mode by updating +development.rb+ to include:
+You can turn off debug mode by updating +config/environments/development.rb+ to include:
 
-<erb>
+<ruby>
 config.assets.debug = false
-</erb>
+</ruby>
 
-When debug mode is off Sprockets will concatenate and run the necessary preprocessors on all files, generating the following HTML:
+When debug mode is off Sprockets concatenates and runs the necessary preprocessors on all files. With debug mode turned off the manifest above would generate instead:
 
 <html>
-<script src='/assets/application.js'></script>
+<script src="/assets/application.js" type="text/javascript"></script>
 </html>
 
-Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-revalidate+ Cache-Control HTTP header to reduce request overhead on subsequent requests -- on these the browser gets a 304 (not-modified) response.
+Assets are compiled and cached on the first request after the server is started. Sprockets sets a +must-revalidate+ Cache-Control HTTP header to reduce request overhead on subsequent requests -- on these the browser gets a 304 (Not Modified) response.
 
 If any of the files in the manifest have changed between requests, the server responds with a new compiled file.
 
-You can put +?debug_assets=true+ or +?debug_assets=1+ at the end of a URL to enable debug mode on-demand, and this will render individual tags for each file. This is useful for tracking down exact line numbers when debugging.
-
-Debug can also be set in the Rails helper methods:
+Debug mode can also be enabled in the Rails helper methods:
 
 <erb>
 <%= stylesheet_link_tag "application", :debug => true %>
 <%= javascript_include_tag "application", :debug => true %>
 </erb>
 
-The +:debug+ option is ignored if the debug mode is off.
+The +:debug+ option is redundant if debug mode is on.
 
 You could potentially also enable compression in development mode as a sanity check, and disable it on-demand as required for debugging.
 
-
 h3. In Production
 
 In the production environment Rails uses the fingerprinting scheme outlined above. By default it is assumed that assets have been precompiled and will be served as static assets by your web server.
@@ -346,6 +346,15 @@ The rake task is:
 bundle exec rake assets:precompile
 </plain>
 
+For faster asset precompiles, you can partially load your application by setting
++config.assets.initialize_on_precompile+ to false, though in that case templates
+cannot see application objects or methods. *Heroku requires this to be false.*
+
+WARNING: If you set +config.assets.initialize_on_precompile+ to false, be sure to
+test +rake assets:precompile+ locally before deploying. It may expose bugs where
+your assets reference application objects or methods, since those are still
+in scope in development mode regardless of the value of this flag.
+
 Capistrano (v2.8.0 and above) has a recipe to handle this in deployment. Add the following line to +Capfile+:
 
 <erb>
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index 6812b6b9fe..bf6104b96b 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -705,7 +705,7 @@ $ rails console
 
 TIP: The default console will make changes to your database. You can instead
 open a console that will roll back any changes you make by using <tt>rails console
---sandbox</tt> .
+--sandbox</tt>.
 
 After the console loads, you can use it to work with your application's models:
 
@@ -1074,7 +1074,7 @@ In the +update+ action, Rails first uses the +:id+ parameter passed back from
 the edit view to locate the database record that's being edited. The
 +update_attributes+ call then takes the +post+ parameter (a hash) from the request
 and applies it to this record. If all goes well, the user is redirected to the
-post's +show+ action. If there are any problems, it's back to the +edit+ action to
+post's +show+ action. If there are any problems, it redirects back to the +edit+ action to
 correct them.
 
 h4. Destroying a Post
@@ -1115,8 +1115,7 @@ models and controllers. To create the new model, run this command in your
 terminal:
 
 <shell>
-$ rails generate model Comment commenter:string body:text \
-> post:references
+$ rails generate model Comment commenter:string body:text post:references
 </shell>
 
 This command will generate four files:
@@ -1520,7 +1519,7 @@ defined it as an instance variable.
 
 h3. Deleting Comments
 
-Another important feature of a blog is being able to delete SPAM comments. To do
+Another important feature of a blog is being able to delete spam comments. To do
 this, we need to implement a link of some sort in the view and a +DELETE+ action
 in the +CommentsController+.
 
diff --git a/railties/guides/source/migrations.textile b/railties/guides/source/migrations.textile
index a73655d130..9c92d567d3 100644
--- a/railties/guides/source/migrations.textile
+++ b/railties/guides/source/migrations.textile
@@ -658,7 +658,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 the RDBMS of the database (via the +db:structure:dump+ Rake task) into +db/#{Rails.env}_structure.sql+. For example, for the PostgreSQL RDBMS, the +pg_dump+ utility is used. For MySQL, this file will contain the output of +SHOW CREATE TABLE+ for the various tables. Loading these schemas is simply a question of executing the SQL statements they contain. By definition, this will create a perfect copy of the database's structure. Using the +:sql+ schema format will, however, prevent loading the schema into a RDBMS other than the one used to create it.
+Instead of using Active Record's schema dumper, the database's structure will be dumped using a tool specific to the database (via the +db:structure:dump+ Rake task) into +db/#{Rails.env}_structure.sql+. For example, for the PostgreSQL RDBMS, the +pg_dump+ utility is used. For MySQL, this file will contain the output of +SHOW CREATE TABLE+ for the various tables. Loading these schemas is simply a question of executing the SQL statements they contain. By definition, this will create a perfect copy of the database's structure. Using the +:sql+ schema format will, however, prevent loading the schema into a RDBMS other than the one used to create it.
 
 h4. Schema Dumps and Source Control
 
diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile
index 0a9f1e8388..bf18402b60 100644
--- a/railties/guides/source/routing.textile
+++ b/railties/guides/source/routing.textile
@@ -596,6 +596,8 @@ match "/stories/:name" => redirect {|params| "/posts/#{params[:name].pluralize}"
 match "/stories" => redirect {|p, req| "/posts/#{req.subdomain}" }
 </ruby>
 
+Please note that this redirection is a 301 "Moved Permanently" redirect. Keep in mind that some web browser or proxy server will cache this type of redirect, make the old page inaccessible.
+
 In all of these cases, if you don't provide the leading host (+http://www.example.com+), Rails will take those details from the current request.
 
 h4. Routing to Rack Applications