Add more docs on syntax configuration.

Closes #149.

README.md

@@ -163,6 +163,40 @@ actual.should end_with(expected)
 "this string".should end_with("ring")
 ```
 
+## Syntax Options
+
+In addition to the `should` syntax, rspec-expectations supports
+an additional `expect` syntax:
+
+```ruby
+# rather than:
+[1, 2, 3].should include(1)
+
+#...you can use:
+expect([1, 2, 3]).to include(1)
+
+# rather than:
+foo.should_not eq(bar)
+
+#...you can use:
+expect(foo).not_to eq(bar)
+```
+
+If you want your project to only use one of these syntaxes, you can
+configure it:
+
+```ruby
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+    # or
+    c.syntax = :should
+    # or
+    c.syntax = [:should, :expect]
+  end
+end
+```
+
 ## Also see
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)

features/.nav

@@ -3,6 +3,7 @@
 - customized_message.feature
 - diffing.feature
 - implicit_docstrings.feature
+- syntax_configuration.feature
 - built_in_matchers:
   - be.feature
   - be_within.feature

features/syntax_configuration.feature

@@ -0,0 +1,68 @@
+Feature: Syntax Configuration
+
+  In addition to the long-supported `should` syntax, rspec-expectations
+  supports an alternate `expect` syntax. If you want your project to
+  only use one syntax, you can configure the available syntaxes.
+
+  Background:
+    Given a file named "syntaxes_spec.rb" with:
+      """ruby
+      describe "using the should syntax" do
+        specify { 3.should eq(3) }
+        specify { 3.should_not eq(4) }
+        specify { lambda { raise "boom" }.should raise_error("boom") }
+        specify { lambda { }.should_not raise_error }
+      end
+
+      describe "using the expect syntax" do
+        specify { expect(3).to eq(3) }
+        specify { expect(3).not_to eq(4) }
+        specify { expect { raise "boom" }.to raise_error("boom") }
+        specify { expect { }.not_to raise_error }
+      end
+      """
+
+  Scenario: Both syntaxes are available by default
+    When I run `rspec syntaxes_spec.rb`
+    Then the examples should all pass
+
+  Scenario: Disable should syntax
+    Given a file named "disable_should_syntax.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.expect_with :rspec do |c|
+          c.syntax = :expect
+        end
+      end
+      """
+    When I run `rspec disable_should_syntax.rb syntaxes_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures    |
+      | undefined method `should' |
+
+  Scenario: Disable expect syntax
+    Given a file named "disable_expect_syntax.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.expect_with :rspec do |c|
+          c.syntax = :should
+        end
+      end
+      """
+    When I run `rspec disable_expect_syntax.rb syntaxes_spec.rb`
+    Then the output should contain all of these:
+      | 8 examples, 4 failures    |
+      | undefined method `expect' |
+
+  Scenario: Explicitly enable both syntaxes
+    Given a file named "enable_both_syntaxes.rb" with:
+      """ruby
+      RSpec.configure do |config|
+        config.expect_with :rspec do |c|
+          c.syntax = [:should, :expect]
+        end
+      end
+      """
+    When I run `rspec enable_both_syntaxes.rb syntaxes_spec.rb`
+    Then the examples should all pass
+