Merged pull request teamcapybara#338 from mcmire/revert_readme_changes.

Clear things up in README again re: spec/acceptance vs. spec/requests

README.rdoc

@@ -88,7 +88,7 @@ by adding the following line (typically to your <tt>spec_helper.rb</tt> file):
 
     require 'capybara/rspec'
 
-You can now use it in your examples:
+You can now write your specs like so:
 
     describe "the signup process", :type => :request do
       before :each do
@@ -104,16 +104,21 @@ You can now use it in your examples:
       end
     end
 
-Capybara is only included for examples with <tt>:type => :request</tt> (or
-<tt>:acceptance</tt> for compatibility).
+Capybara is only included in example groups tagged with
+<tt>:type => :request</tt> (or <tt>:acceptance</tt> for compatibility with Steak).
 
-If you use the <tt>rspec-rails</tt> gem, <tt>:type => :request</tt> is
-automatically set on all files under <tt>spec/requests</tt>. Essentially, these
-are Capybara-enhanced Rails request specs, so it's a good idea to place your
-Capybara specs here because within request specs you gain a few additional
-features, such as the ability to refer to named route helpers. If you do not
-need these, then you may simply use <tt>spec/acceptance</tt> and you will still
-get access to Capybara methods.
+If you are testing a Rails app and using the <tt>rspec-rails</tt> gem, these
+<tt>:request</tt> example groups may look familiar to you. That's because they
+are RSpec versions of Rails integration tests. So, in this case essentially what you are getting are Capybara-enhanced request specs. This means that you can
+use the Capybara helpers <i>and</i> you have access to things like named route
+helpers in your tests (so you are able to say, for instance, <tt>visit
+edit_user_path(user)</tt>, instead of <tt>visit "/users/#{user.id}/edit"</tt>,
+if you prefer that sort of thing). A good place to put these specs is
+<tt>spec/requests</tt>, as <tt>rspec-rails</tt> will automatically tag them with
+<tt>:type => :request</tt>. (In fact, <tt>spec/integration</tt> and
+<tt>spec/acceptance</tt> will work just as well.)
+
+<tt>rspec-rails</tt> will also automatically include Capybara in <tt>:controller</tt> and <tt>:mailer</tt> example groups.
 
 RSpec's metadata feature can be used to switch to a different driver. Use
 <tt>:js => true</tt> to switch to the javascript driver, or provide a
@@ -124,7 +129,7 @@ RSpec's metadata feature can be used to switch to a different driver. Use
       it 'will switch to one specific driver', :driver => :celerity
     end
 
-Capybara also comes with a built in DSL for creating descriptive acceptance tests:
+Finally, Capybara also comes with a built in DSL for creating descriptive acceptance tests:
 
     feature "Signing up" do
       background do
@@ -140,11 +145,10 @@ Capybara also comes with a built in DSL for creating descriptive acceptance test
       end
     end
 
-Essentially, this is just a shortcut for making a request spec, where
-<tt>feature</tt> is a shortcut for <tt>describe ..., :type => :request</tt>,
-<tt>background</tt> is an alias for <tt>before :each</tt>, and <tt>scenario</tt>
-is an alias for <tt>it</tt>/<tt>example</tt>. Again, you are encouraged to place
-these within <tt>spec/requests</tt> rather than <tt>spec/acceptance</tt>.
+This is, in fact, just a shortcut for making a request spec, where
+<tt>feature</tt> is an alias for <tt>describe ..., :type => :request</tt>,
+<tt>background</tt> is an alias for <tt>before</tt>, and <tt>scenario</tt>
+is an alias for <tt>it</tt>/<tt>specify</tt>.
 
 Note that Capybara's built in RSpec support only works with RSpec 2.0 or later.
 You'll need to roll your own for earlier versions of RSpec.