README.rdoc in capybara-1.0.0.beta1 vs README.rdoc in capybara-1.0.0.rc1

@@ -24,16 +24,16 @@
     sudo port install libffi
 
 == Development:
 
 * Source hosted at {GitHub}[http://github.com/jnicklas/capybara].
-* Please direct questions, discussions at the {mailing list}[http://groups.google.com/group/ruby-capybara].
-* Report issues on {GitHub Issues}[http://github.com/jnicklas/capybara/issues]
+* Please direct questions, discussion or problems to the {mailing list}[http://groups.google.com/group/ruby-capybara].
+* If you found a reproducible bug, open a {GitHub Issue}[http://github.com/jnicklas/capybara/issues] to submit a bug report.
 
-Pull requests are very welcome! Make sure your patches are well tested, Capybara is
-a testing tool after all. Please create a topic branch for every separate change
-you make.
+Pull requests are very welcome (and even better than bug reports)! Make sure
+your patches are well tested, Capybara is a testing tool after all. Please
+create a topic branch for every separate change you make.
 
 Capybara uses bundler in development. To set up a development environment, simply do:
 
     git submodule update --init
     gem install bundler --pre
@@ -86,11 +86,11 @@
 If you prefer RSpec to using Cucumber, you can use the built in RSpec support
 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
         User.make(:email => '[e-mail]', :password => 'caplin')
       end
@@ -102,31 +102,36 @@
         end
         click_link 'Sign in'
       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
 <tt>:driver</tt> option to switch to one specific driver. For example:
 
     describe 'some stuff which requires js', :js => true do
       it 'will use the default js driver'
       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
         User.make(:email => '[e-mail]', :password => 'caplin')
       end
@@ -138,15 +143,14 @@
         end
         click_link 'Sign in'
       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.
 
 == Using Capybara with Test::Unit
@@ -404,9 +408,12 @@
     end
 
     within(:xpath, "//li[@id='employee']") do
       fill_in 'Name', :with => 'Jimmy'
     end
+
+Note that <tt>within</tt> will scope the actions to the _first_ (not _any_)
+element that matches the selector.
 
 There are special methods for restricting the scope to a specific fieldset,
 identified by either an id or the text of the fieldet's legend tag, and to a
 specific table, identified by either id or text of the table's caption tag.