use github-flavored-markup in readme

Gemfile-custom.sample

@@ -1,6 +1,6 @@
 group :development do
   gem 'interactive_rspec'
-  gem 'yard'
+  gem 'yard', "~> 0.7.4"
   gem "relish", "~> 0.5.0"
   gem "guard-rspec", "0.5.0"
   gem "growl", "1.0.3"

README.md

@@ -1,5 +1,12 @@
 # rspec-core
 
+```
+gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
+gem install rspec-core # for rspec-core only
+```
+
+# overview
+
 rspec-core provides the structure for writing executable examples of how
 your code should behave.  It uses the words "describe" and "it" so we can
 express concepts like a conversation:
@@ -9,19 +16,21 @@ express concepts like a conversation:
 
 ## basic structure
 
-    describe Order do
-      it "sums the prices of its line items" do
-        order = Order.new
-        order.add_entry(LineItem.new(:item => Item.new(
-          :price => Money.new(1.11, :USD)
-        )
-        order.add_entry(LineItem.new(:item => Item.new(
-          :price => Money.new(2.22, :USD),
-          :quantity => 2
-        )
-        order.total.should eq(Money.new(5.55, :USD))
-      end
-    end
+```ruby
+describe Order do
+  it "sums the prices of its line items" do
+    order = Order.new
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(1.11, :USD)
+    )))
+    order.add_entry(LineItem.new(:item => Item.new(
+      :price => Money.new(2.22, :USD),
+      :quantity => 2
+    )))
+    order.total.should eq(Money.new(5.55, :USD))
+  end
+end
+```
 
 The `describe` method creates an [ExampleGroup](../RSpec/Core/ExampleGroup).  Within the
 block passed to `describe` you can declare examples using the `it` method.
@@ -35,19 +44,21 @@ context of an _instance_ of that class.
 You can also declare nested nested groups using the `describe` or `context`
 methods:
 
-    describe Order to
-      context "with no items" do
-        it "behaves one way" do
-          # ...
-        end
-      end
-
-      context "with one item" do
-        it "behaves another way" do
-          # ...
-        end
-      end
+```ruby
+describe Order do
+  context "with no items" do
+    it "behaves one way" do
+      # ...
+    end
+  end
+
+  context "with one item" do
+    it "behaves another way" do
+      # ...
     end
+  end
+end
+```
 
 ## aliases
 
@@ -62,19 +73,21 @@ You can declare examples within a group using any of `it`, `specify`, or
 Declare a shared example group using `shared_examples`, and then include it
 in any group using `include_examples`.
 
-    shared_examples "collections" do |collection_class|
-      it "is empty when first created" do
-        collection_class.new.should be_empty
-      end
-    end
+```ruby
+shared_examples "collections" do |collection_class|
+  it "is empty when first created" do
+    collection_class.new.should be_empty
+  end
+end
 
-    describe Array do
-      include_examples "collections", Array
-    end
+describe Array do
+  include_examples "collections", Array
+end
 
-    describe Hash do
-      include_examples "collections", Hash
-    end
+describe Hash do
+  include_examples "collections", Hash
+end
+```
 
 Nearly anything that can be declared within an example group can be declared
 within a shared example group. This includes `before`, `after`, and `around`
@@ -96,39 +109,45 @@ and filtering before and after hooks.
 Although you probably won't ever need this unless you are writing an
 extension, you can access it from an example like this:
 
-    it "does something" do
-      example.metadata[:description].should eq("does something")
-    end
+```ruby
+it "does something" do
+  example.metadata[:description].should eq("does something")
+end
+```
 
 ### `described_class`
 
 When a class is passed to `describe`, you can access it from an example
 using the `described_class` method, which is a wrapper for
 `example.metadata[:described_class]`.
 
-    describe Widget do
-      example do
-        described_class.should equal(Widget)
-      end
-    end
+```ruby
+describe Widget do
+  example do
+    described_class.should equal(Widget)
+  end
+end
+```
 
 This is useful in extensions or shared example groups in which the specific
 class is unknown. Taking the shared examples example from above, we can
 clean it up a bit using `described_class`:
 
-    shared_examples "collections" do
-      it "is empty when first created" do
-        described.new.should be_empty
-      end
-    end
+```ruby
+shared_examples "collections" do
+  it "is empty when first created" do
+    described.new.should be_empty
+  end
+end
 
-    describe Array do
-      include_examples "collections"
-    end
+describe Array do
+  include_examples "collections"
+end
 
-    describe Hash do
-      include_examples "collections"
-    end
+describe Hash do
+  include_examples "collections"
+end
+```
 
 ## the `rspec` command
 
@@ -146,52 +165,59 @@ Run `rspec --help` to see the complete list.
 Start with a simple example of behavior you expect from your system. Do
 this before you write any implementation code:
 
-    # in spec/calculator_spec.rb
-    describe Calculator do
-      it "add(x,y) returns the sum of its arguments" do
-        Calculator.new.add(1, 2).should eq(3)
-      end
-    end
+```ruby
+# in spec/calculator_spec.rb
+describe Calculator do
+  it "add(x,y) returns the sum of its arguments" do
+    Calculator.new.add(1, 2).should eq(3)
+  end
+end
+```
 
 Run this with the rspec command, and watch it fail:
 
-    $ rspec spec/calculator_spec.rb
-    ./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
+$ rspec spec/calculator_spec.rb
+./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
 
 Implement the simplest solution:
 
-    # in lib/calculator.rb
-    class Calculator
-      def add(a,b)
-        a + b
-      end
-    end
+```ruby
+# in lib/calculator.rb
+class Calculator
+  def add(a,b)
+    a + b
+  end
+end
+```
 
 Be sure to require the implementation file in the spec:
 
-    # in spec/calculator_spec.rb
-    # - RSpec adds ./lib to the $LOAD_PATH
-    require "calculator"
+```ruby
+# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require "calculator"
+```
 
 Now run the spec again, and watch it pass:
 
-    $ rspec spec/calculator_spec.rb
-    .
+```
+$ rspec spec/calculator_spec.rb
+.
 
-    Finished in 0.000315 seconds
-    1 example, 0 failures
+Finished in 0.000315 seconds
+1 example, 0 failures
+```
 
 Use the `documentation` formatter to see the resulting spec:
 
-    $ rspec spec/calculator_spec.rb --format doc
-    Calculator add
-      returns the sum of its arguments
-
-    Finished in 0.000379 seconds
-    1 example, 0 failures
-
-## install
+```
+$ rspec spec/calculator_spec.rb --format doc
+Calculator add
+  returns the sum of its arguments
 
-    gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
-    gem install rspec-core # for rspec-core only
+Finished in 0.000379 seconds
+1 example, 0 failures
+```