diff --git a/README.md b/README.md
index 4db4541..52072ff 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,16 @@
 # HTTP::Cookie
 
-HTTP::Cookie is a ruby library to handle HTTP cookies in a way both
+`HTTP::Cookie` is a ruby library to handle HTTP cookies in a way both
 compliant with RFCs and compatible with today's major browsers.
 
-It was originally a part of the Mechanize library, separated as an
-independent library in the hope of serving as a common component that
-is reusable from any HTTP related piece of software.
+It was originally a part of the
+[Mechanize](https://github.com/sparklemotion/mechanize) library,
+separated as an independent library in the hope of serving as a common
+component that is reusable from any HTTP related piece of software.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`:
 
     gem 'http-cookie'
 
@@ -59,65 +60,67 @@ Or install it yourself as:
     set_cookie_header_value = cookies.set_cookie_value(my_url)
 
 
-## Incompatibilities with Mechanize::Cookie and CookieJar
+## Incompatibilities with `Mechanize::Cookie`/`CookieJar`
 
-There are several incompatibilities with Mechanize::Cookie and
-CookieJar.  Below is how to rewrite existing code written for
-Mechanize::Cookie with equivalent using HTTP::Cookie:
+There are several incompatibilities between
+`Mechanize::Cookie`/`CookieJar` and `HTTP::Cookie`/`CookieJar`.  Below
+is how to rewrite existing code written for `Mechanize::Cookie` with
+equivalent using `HTTP::Cookie`:
 
-- Mechanize::Cookie.parse
+- `Mechanize::Cookie.parse`
 
-    # before
-    cookie1 = Mechanize::Cookie.parse(uri, set_cookie1)
-    cookie2 = Mechanize::Cookie.parse(uri, set_cookie2, log)
+        # before
+        cookie1 = Mechanize::Cookie.parse(uri, set_cookie1)
+        cookie2 = Mechanize::Cookie.parse(uri, set_cookie2, log)
 
-    # after
-    cookie1 = HTTP::Cookie.parse(set_cookie1, :origin => uri)
-    cookie2 = HTTP::Cookie.parse(set_cookie2, :origin => uri, :logger => log)
+        # after
+        cookie1 = HTTP::Cookie.parse(set_cookie1, :origin => uri)
+        cookie2 = HTTP::Cookie.parse(set_cookie2, :origin => uri, :logger => log)
 
-- Mechanize::Cookie#set_domain
+- `Mechanize::Cookie#set_domain`
 
-    # before
-    cookie.set_domain(domain)
+        # before
+        cookie.set_domain(domain)
 
-    # after
-    cookie.domain = domain
+        # after
+        cookie.domain = domain
 
-- Mechanize::CookieJar#add, #add!
+- `Mechanize::CookieJar#add`, `#add!`
 
-    # before
-    jar.add!(cookie1)
-    jar.add(uri, cookie2)
+        # before
+        jar.add!(cookie1)
+        jar.add(uri, cookie2)
 
-    # after
-    jar.add(cookie1)
-    cookie2.origin = uri; jar.add(cookie2)  # or specify origin in parse() or new()
+        # after
+        jar.add(cookie1)
+        cookie2.origin = uri; jar.add(cookie2)  # or specify origin in parse() or new()
 
-- Mechanize::CookieJar#clear!
+- `Mechanize::CookieJar#clear!`
 
-    # before
-    jar.clear!
+        # before
+        jar.clear!
 
-    # after
-    jar.clear
+        # after
+        jar.clear
 
-- Mechanize::CookieJar#save_as
+- `Mechanize::CookieJar#save_as`
 
-    # before
-    jar.save_as(file)
+        # before
+        jar.save_as(file)
 
-    # after
-    jar.save(file)
+        # after
+        jar.save(file)
 
-HTTP::Cookie and CookieJar raises runtime errors to help migration, so
-try running your test code once to find out how to fix your code base.
+`HTTP::Cookie` and `CookieJar` raises runtime errors to help
+migration, so try running your test code once to find out how to fix
+your code base.
 
 The YAML serialization format has changed.  Loading YAML files
-generated by Mechanize::CookieJar#save_as will not raise an exception,
-but the content is simply ignored.  Note that there is (obviously) no
-forward compatibillity in the YAML serialization.  Trying to load a
-YAML file saved by HTTP::CookieJar with Mechanize::CookieJar will fail
-in ArgumentError.
+generated by `Mechanize::CookieJar#save_as` will not raise an
+exception, but the content is simply ignored.  Note that there is
+(obviously) no forward compatibillity in the YAML serialization.
+Trying to load a YAML file saved by `HTTP::CookieJar` with
+`Mechanize::CookieJar` will fail in `ArgumentError`.
 
 On the other hand, there has been (and will ever be) no change in the
 cookies.txt format.