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

3 files changed, 83 insertions, 18 deletions

diff --git a/railties/guides/source/3_1_release_notes.textile b/railties/guides/source/3_1_release_notes.textile
index bfe6db4651..f88d8624ba 100644
--- a/railties/guides/source/3_1_release_notes.textile
+++ b/railties/guides/source/3_1_release_notes.textile
@@ -46,13 +46,20 @@ gem 'jquery-rails'
 
 h5. config/application.rb
 
-The asset pipeline requires the following additions:
+* The asset pipeline requires the following additions:
 
 <ruby>
 config.assets.enabled = true
 config.assets.version = '1.0'
 </ruby>
 
+* If your application is using the "/assets" route for a resource you may want change the prefix used for assets to avoid conflicts:
+
+<ruby>
+# Defaults to '/assets'
+config.assets.prefix = '/asset-files'
+</ruby>
+
 h5. config/environments/development.rb
 
 * Remove the RJS setting <tt>config.action_view.debug_rjs = true</tt>.
diff --git a/railties/guides/source/asset_pipeline.textile b/railties/guides/source/asset_pipeline.textile
index da7d46ef71..ff2bd08602 100644
--- a/railties/guides/source/asset_pipeline.textile
+++ b/railties/guides/source/asset_pipeline.textile
@@ -109,22 +109,74 @@ NOTE: You must have an "ExecJS":https://github.com/sstephenson/execjs#readme sup
 
 h4. Asset Organization
 
-Assets that must be precompiled can be placed inside an application in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+.
+Pipeline assets can be placed inside an application in one of three locations: +app/assets+, +lib/assets+ or +vendor/assets+.
 
 +app/assets+ is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets.
 
 +lib/assets+ is for your own libraries' code that doesn't really fit into the scope of the application or those libraries which are shared across applications.
 
-+vendor/assets+ is for assets that are owned by outside entities, such as code for JavaScript plugins.
++vendor/assets+ is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks.
 
-All subdirectories that exist within these three locations are added to the search path for Sprockets. You can see this search path by inspecting +Rails.application.config.assets.paths+ in the Rails console. When a client requests an asset, these paths are traversed (in the order that they occur in the search path) to see if they contain an asset matching the name specified. If an asset is found, it's processed by Sprockets and served.
+h5. Search paths
 
-You can add additional (fully qualified) paths to the pipeline in +config/application.rb+. For example:
+When a file is referenced from a manifest or a helper, Sprockets searches the three default asset locations for it.
+
+The default locations are: +app/assets/images+ and the subdirectories +javascripts+ and +stylesheets+ in all three asset locations.
+
+For example, these files:
+
+<plain>
+app/assets/javascripts/home.js
+lib/assets/javascripts/moovinator.js
+vendor/assets/javascript/slider.js
+</plain>
+
+would be referenced in a manifest like this:
+
+<plain>
+//= require home
+//= require moovinator
+//= require slider
+</plain>
+
+Assets inside subdirectories can also be accessed.
+
+<plain>
+app/assets/javascripts/sub/something.js
+</plain>
+
+is referenced as:
+
+<plain>
+//= require sub/something
+</plain>
+
+You can view the search path by inspecting +Rails.application.config.assets.paths+ in the Rails console.
+
+Additional (fully qualified) paths can be added to the pipeline in +config/application.rb+. For example:
 
 <ruby>
 config.assets.paths << Rails.root.join("app", "assets", "flash")
 </ruby>
 
+Paths are traversed in the order that they occur in the search path.
+
+It is important to note that files you want to reference outside a manifest must be added to the precompile array or they will not be available in the production environment.
+
+h5. Using index files
+
+Sprockets uses files named +index+ (with the relevant extensions) for a special purpose.
+
+For example, if you have a jQuery library with many modules, which is stored in +lib/assets/library_name+, the file +lib/assets/library_name/index.js+ serves as the manifest for all files in this library. This file could include a list of all the required files in order, or a simple <tt>require_tree</tt> directive.
+
+The library as a whole can be accessed in the site's application manifest like so:
+
+<plain>
+//= require library_name
+</plain>
+
+This simplifies maintenance and keeps things clean by allowing related code to be grouped before inclusion elsewhere.
+
 h4. Coding Links to Assets
 
 Sprockets does not add any new methods to access your assets - you still use the familiar +javascript_include_tag+ and +stylesheet_link_tag+.
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile
index a36f84e9fd..c77bc93cfb 100644
--- a/railties/guides/source/getting_started.textile
+++ b/railties/guides/source/getting_started.textile
@@ -447,7 +447,13 @@ start a web server on your development machine. You can do this by running:
 $ rails server
 </shell>
 
-TIP: Compiling CoffeeScript to JavaScript requires a JavaScript runtime and the absence of a runtime will give you an +execjs+ error. Usually Mac OS X and Windows come with a JavaScript runtime installed. +therubyracer+ and +therubyrhino+ are the commonly used runtimes for Ruby and JRuby respectively. You can also investigate a list of runtimes at "ExecJS":https://github.com/sstephenson/execjs.
+TIP: Compiling CoffeeScript to JavaScript requires a JavaScript runtime and
+the absence of a runtime will give you an +execjs+ error. Usually Mac OS X
+and Windows come with a JavaScript runtime installed. Rails adds the +therubyracer+ gem
+to Gemfile in a commented line for new apps and you can uncomment if you need it.
++therubyrhino+ is the recommended runtime for JRuby users and is added by default
+to Gemfile in apps generated under JRuby. You can investigate about all the
+supported runtimes at "ExecJS":https://github.com/sstephenson/execjs#readme.
 
 This will fire up an instance of the WEBrick web server by default (Rails can
 also use several other web servers). To see your application in action, open a
@@ -838,7 +844,7 @@ below:
   <%= javascript_include_tag "application" %>
   <%= csrf_meta_tags %>
 </head>
-<body style="background: #EEEEEE;">
+<body style="background-color: #EEEEEE;">
 
 <%= yield %>
 
@@ -1008,7 +1014,7 @@ by its id value. After finding the record, Rails displays it by using
 +app/views/posts/show.html.erb+:
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>
@@ -1275,7 +1281,7 @@ So first, we'll wire up the Post show template
 (+/app/views/posts/show.html.erb+) to let us make a new comment:
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>
@@ -1341,7 +1347,7 @@ template. This is where we want the comment to show, so let's add that to the
 +app/views/posts/show.html.erb+.
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>
@@ -1423,7 +1429,7 @@ Then you can change +app/views/posts/show.html.erb+ to look like the
 following:
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>
@@ -1494,7 +1500,7 @@ create a file +app/views/comments/_form.html.erb+ containing:
 Then you make the +app/views/posts/show.html.erb+ look like the following:
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>
@@ -1689,10 +1695,10 @@ class Post < ActiveRecord::Base
 end
 </ruby>
 
-The +:allow_destroy+ option on the nested attribute declaration tells Rails to
-display a "remove" checkbox on the view that you'll build shortly. The
-+:reject_if+ option prevents saving new tags that do not have any attributes
-filled in.
+The +:allow_destroy+ option tells Rails to enable destroying tags through the
+nested attributes (you'll handle that by displaying a "remove" checkbox on the
+view that you'll build shortly). The +:reject_if+ option prevents saving new
+tags that do not have any attributes filled in.
 
 We will modify +views/posts/_form.html.erb+ to render a partial to make a tag:
 
@@ -1765,7 +1771,7 @@ Finally, we will edit the <tt>app/views/posts/show.html.erb</tt> template to
 show our tags.
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>
@@ -1825,7 +1831,7 @@ Now you can edit the view in <tt>app/views/posts/show.html.erb</tt> to look like
 this:
 
 <erb>
-<p class="notice"><%= notice %></p>
+<p id="notice"><%= notice %></p>
 
 <p>
   <b>Name:</b>