More formatting and wording improvements.

README.md

@@ -1,7 +1,7 @@
 # Acts As Indexed
 
 This plugin allows boolean-queried fulltext search to be added to any Rails
-app with no dependencies and minimal setup.
+app with no additional dependencies and minimal setup.
 
 ## Installation
 
@@ -11,7 +11,7 @@ app with no dependencies and minimal setup.
 gem 'acts_as_indexed'
 ```
 
-2. Run bundle install.
+2. Run `bundle install`.
 
 ## Upgrading
 
@@ -38,32 +38,30 @@ the current model.
 
 ```ruby
 class User < ActiveRecord::Base
-  acts_as_indexed fields: [:address, :fullname]
+  acts_as_indexed fields: [:address, :full_name]
 
-  def fullname
-    self.firstname + ' ' + self.lastname
+  def full_name
+    [forename, surname].join(' ')
   end
 
-  ...
+  # ...
 end
 ```
 
-Any of the configuration options in the "Further Configuration" section can be
-added as to the `acts_as_indexed` method call. these will override any defaults
-or global configuration.
+Any of the configuration options in the [Further
+Configuration](#further-configuration) section can be added as to the
+`acts_as_indexed` method call. these will override any defaults or global
+configuration.
 
-you can specify a proc that needs to evaluate to true before the item gets
-indexed. this is useful if you only want items with a certain state to be
-included. the proc is passed the current object's instance so you are able to
-test against that.
+A `proc` can be assigned to the `if` key which determines whether a record is
+added to the index.
 
-for example, if you have a visible column that is false if the post is hidden,
+For example, if you have a `is_visible` column that is false if the post is hidden,
 or true if it is visible, you can filter the index by doing:
 
-class post < activerecord::base
-acts_as_indexed fields: [:title, :body], if: proc.new { |post| post.visible? }
-...
-end
+```ruby
+acts_as_indexed fields: [:title, :body], if: proc.new { |post| post.is_visible? }
+```
 
 ### Searching
 
@@ -76,13 +74,13 @@ of any matching records.
 
 ```ruby
 # returns array of post objects ordered by relevance.
-my_search_results = post.find_with_index('my search query')
+post.find_with_index('my search query')
 
 # pass any of the activerecord find options to the search.
-my_search_results = post.find_with_index('my search query', { limit: 10}) # return the first 10 matches.
+post.find_with_index('my search query', { limit: 10 })
 
 # returns array of ids ordered by relevance.
-my_search_results = post.find_with_index('my search query', {}, { ids_only: true }) # =>  [12,19,33...
+post.find_with_index('my search query', {}, { ids_only: true }) # =>  [12,19,33...
 ```
 
 #### Without Relevance (Scope)
@@ -92,31 +90,31 @@ scope on your model, passing a query as an argument.
 
 ```ruby
 # Returns array of Post objects.
-my_search_results = Post.with_query('my search query')
+Post.with_query('my search query')
 
 # Chain it with any number of ActiveRecord methods and named_scopes.
-my_search_results = Post.public.with_query('my search query').find(:all, limit: 10) # return the first 10 matches which are public.
+Post.public.with_query('my search query').find(:all, limit: 10) # return the first 10 matches which are public.
 ```
 
 ### Query Options
 
 The following query operators are supported:
 
-- AND :: This is the default option. 'cat dog' will find records matching 'cat'
-  AND 'dog'.
-- NOT :: 'cat -dog' will find records matching 'cat' AND NOT 'dog'
-- INCLUDE :: 'cat +me' will find records matching 'cat' and 'me', even if 'me'
-  is smaller than the `min_word_size`
-- "" :: Quoted terms are matched as phrases. '"cat dog"' will find records
-  matching the whole phrase. Quoted terms can be preceded by the NOT operator;
-  'cat -"big dog"' etc. Quoted terms can include words shorter than the
+- This is the default option. `cat dog` will find records matching `cat` AND
+  `dog`.
+- `cat -dog` will find records matching `cat` AND NOT `dog`
+- 'cat +me' will find records matching `cat` and `me`, even if `me` is smaller
+  than the `min_word_size`
+- Quoted terms are matched as phrases. `"cat dog"` will find records matching
+  the whole phrase. Quoted terms can be preceded by the NOT operator; `cat
+-"big dog"` etc. Quoted terms can include words shorter than the
   `min_word_size`.
-- ^ :: Terms that begin with ^ will match records that contain a word starting
-  with the term. '^cat' will find matches containing 'cat', 'catapult',
-  'caterpillar' etc.
-- ^"" :: A quoted term that begins with ^ matches any phrase that begin with
-  this phrase. '^"cat d"' will find records matching the whole phrases "cat
-  dog" and "cat dinner". This type of search is useful for autocomplete inputs.
+- Terms that begin with `^` will match records that contain a word starting
+  with the term. `^cat` will find matches containing `cat`, `catapult`,
+  `caterpillar` etc.
+- A quoted term that begins with `^` matches any phrase that begin with
+  this phrase. `^"cat d"` will find records matching the whole phrases 'cat
+  dog' and `cat dinner`. This type of search is useful for autocomplete inputs.
 
 ### Pagination
 
@@ -126,16 +124,16 @@ Pagination is supported via the `paginate_search` method whose first argument
 is the search query, followed by all the standard will_paginate arguments.
 
 ```ruby
-@images = Image.paginate_search('girl', page: 1, per_page: 5)
+Image.paginate_search('girl', page: 1, per_page: 5)
 ```
 
 #### Without Relevance (Scope)
 
-Since `with_query` is a named scope, WillPaginate can be used in the normal
+Since `with_query` is an ActiveRecord scope, WillPaginate can be used in the normal
 fashion.
 
 ```ruby
-@images = Image.with_query('girl').paginate(page: 1, per_page: 5)
+Image.with_query('girl').paginate(page: 1, per_page: 5)
 ```
 
 ### Further Configuration
@@ -151,15 +149,15 @@ end
 ```
 
 A full rundown of the available configuration options can be found in
-`lib/acts_as_indexed/configuration.rb`
+`lib/acts_as_indexed/configuration.rb`.
 
 ## Caveats
 
 Acts as Indexed is intended to provide a simple solution to full text search
 for modest-sized application setups. As a result it comes with some operational
 caveats:
 
-- Only works with ASCII characters as does not fold/normalise UTF-8 characters.
+- Only works with ASCII characters as does not fold/normali`e UTF-8 characters.
   A workaround for this is [described in this
   Gist](https://gist.github.com/193903bb4e0d6e5debe1)
 - Is not multi-process safe. If two processes write to the index at the same