Update readme

README.md

@@ -2,7 +2,7 @@
 
 GlobalPhone parses, validates, and formats local and international phone numbers according to the [E.164 standard](http://en.wikipedia.org/wiki/E.164).
 
-**Store and display phone numbers in your app.** Accept phone number input in national or international format. Convert phone numbers to international format (`+13125551212`) for storage and retrieval. Present numbers in national format (`(312) 555-1212`) in your UI.
+**Store and display phone numbers in your app.** Accept phone number input in national or international format. Convert phone numbers to international strings (`+13125551212`) for storage and retrieval. Present numbers in national format (`(312) 555-1212`) in your UI.
 
 **Designed with the future in mind.** GlobalPhone uses format specifications from Google's open-source [libphonenumber](http://code.google.com/p/libphonenumber/) database. No need to upgrade the library when a new phone format is introduced—just generate a new copy of the database and check it into your app.
 
@@ -22,87 +22,109 @@ GlobalPhone parses, validates, and formats local and international phone numbers
 
 3. Tell GlobalPhone where to find the database. For example, in a Rails app, create an initializer in `config/initializers/global_phone.rb`:
 
-        require 'global_phone'
-        GlobalPhone.db_path = Rails.root.join('db/global_phone.json')
+    ```ruby
+    require 'global_phone'
+    GlobalPhone.db_path = Rails.root.join('db/global_phone.json')
+    ```
 
 ## Examples
 
 Parse an international number string into a `GlobalPhone::Number` object:
 
-    >> number = GlobalPhone.parse('+1-312-555-1212')
-    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=1 name=US> national_string="3125551212">
+```ruby
+number = GlobalPhone.parse('+1-312-555-1212')
+# => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=1 name=US> national_string="3125551212">
+```
 
 Query the country code and likely territory name of the number:
 
-    >> number.country_code
-    => "1"
+```ruby
+number.country_code
+# => "1"
 
-    >> number.territory.name
-    => "US"
+number.territory.name
+# => "US"
+```
 
 Present the number in national and international formats:
 
-    >> number.national_format
-    => "(312) 555-1212"
+```ruby
+number.national_format
+# => "(312) 555-1212"
 
-    >> number.international_format
-    => "+1 312-555-1212"
+number.international_format
+# => "+1 312-555-1212"
+```
 
 Is the number valid? (Note: this is not definitive. For example, the number here is "valid" by format, but there are no US numbers that start with 555. The `valid?` method may return false positives, but *should not* return false negatives unless the database is out of date.)
 
-    >> number.valid?
-    true
+```ruby
+number.valid?
+# => true
+```
 
 Get the number's normalized E.164 international string:
 
-    >> number.international_string
-    => "+13125551212"
+```ruby
+number.international_string
+# => "+13125551212"
+```
 
 Parse a number in national format for a given territory:
 
-    >> number = GlobalPhone.parse("(0) 20-7031-3000", :gb)
-    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=44 name=GB> national_string="2070313000">
+```ruby
+number = GlobalPhone.parse("(0) 20-7031-3000", :gb)
+# => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=44 name=GB> national_string="2070313000">
+```
 
 Parse an international number using a territory's international dialing prefix:
 
-    >> number = GlobalPhone.parse("00 1 3125551212", :gb)
-    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=1 name=US> national_string="3125551212">
+```ruby
+number = GlobalPhone.parse("00 1 3125551212", :gb)
+# => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=1 name=US> national_string="3125551212">
+```
 
 Set the default territory to Great Britain (territory names are [ISO 3166-1 Alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes):
 
-    >> GlobalPhone.default_territory_name = :gb
-    => :gb
+```ruby
+GlobalPhone.default_territory_name = :gb
+# => :gb
 
-    >> GlobalPhone.parse("(0) 20-7031-3000")
-    => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=44 name=GB> national_string="2070313000">
+GlobalPhone.parse("(0) 20-7031-3000")
+# => #<GlobalPhone::Number territory=#<GlobalPhone::Territory country_code=44 name=GB> national_string="2070313000">
+```
 
 Shortcuts for validating a phone number:
 
-    >> GlobalPhone.validate("+1 312-555-1212")
-    => true
+```ruby
+GlobalPhone.validate("+1 312-555-1212")
+# => true
 
-    >> GlobalPhone.validate("+442070313000")
-    => true
+GlobalPhone.validate("+442070313000")
+# => true
 
-    >> GlobalPhone.validate("(0) 20-7031-3000")
-    => false
+GlobalPhone.validate("(0) 20-7031-3000")
+# => false
 
-    >> GlobalPhone.validate("(0) 20-7031-3000", :gb)
-    => true
+GlobalPhone.validate("(0) 20-7031-3000", :gb)
+# => true
+```
 
 Shortcuts for normalizing a phone number in E.164 format:
 
-    >> GlobalPhone.normalize("(312) 555-1212")
-    => "+13125551212"
+```ruby
+GlobalPhone.normalize("(312) 555-1212")
+# => "+13125551212"
 
-    >> GlobalPhone.normalize("+442070313000")
-    => "+442070313000"
+GlobalPhone.normalize("+442070313000")
+# => "+442070313000"
 
-    >> GlobalPhone.normalize("(0) 20-7031-3000")
-    => nil
+GlobalPhone.normalize("(0) 20-7031-3000")
+# => nil
 
-    >> GlobalPhone.normalize("(0) 20-7031-3000", :gb)
-    => "+442070313000"
+GlobalPhone.normalize("(0) 20-7031-3000", :gb)
+# => "+442070313000"
+```
 
 ## Caveats