README.markdown in by_star-2.0.0.beta1 vs README.markdown in by_star-2.1.0.beta2

@@ -1,16 +1,42 @@
 # by_*
 
 
-by_* (by_star) is a plugin that allows you to find ActiveRecord objects given certain date objects. This was originally crafted for only finding objects within a given month, but now has extended out to much more. It now supports finding objects for:
+by_* (by_star) is a plugin that allows you to find ActiveRecord and/or Mongoid objects given certain date objects.
 
+## Installation
+
+Install this gem by adding this to your Gemfile:
+
+```ruby
+gem 'by_star', :git => "git://github.com/radar/by_star"
+```
+
+Then run `bundle install`.
+
+If you are using ActiveRecord, you're done!
+
+Mongoid users, please include the Mongoid::ByStar module for each model you wish to use the functionality. This is the convention among Mongoid plugins.
+
+```ruby
+class MyModel
+  include Mongoid::Document
+  include Mongoid::ByStar
+```
+
+## What it does
+
+This was originally crafted for only finding objects within a given month, but now has extended out to much more. It now supports finding objects for:
+
 * A given year
 * A given month
 * A given fortnight
 * A given week
 * A given weekend
 * A given day
+* A given quarter
+* The weeks of a given month as shown on a calendar
 * The current weekend
 * The current work week
 * The Past
 * The Future
 * Between certain times
@@ -91,10 +117,18 @@
 
      Post.by_month(Time.local(2012, 11, 24))
 
 This will find all the posts in November 2012.
 
+## By Calendar Month (`by_calendar_month`)
+
+Finds records for a given month as shown on a calendar. Includes all the results of `by_month`, plus any results which fall in the same week as the first and last of the month. Useful for working with UI calendars which show rows of weeks.
+
+    Post.by_calendar_month
+
+Parameter behavior is otherwise the same as `by_month`
+
 ## By Fortnight (`by_fortnight`)
 
 Fortnight numbering starts at 0. The beginning of a fortnight is Monday, 12am.
 
 To find records from the current fortnight:
@@ -125,15 +159,15 @@
 
 To find records based on a week, you can pass in a number (representing the week number) or a time object:
 
     Post.by_week(36)
 
-This will return all posts in the 36th week of the current year.
+This will return all posts in the 37th week of the current year (remember week numbering starts at 0).
 
     Post.by_week(36, :year => 2012)
 
-This will return all posts in the 36th week of 2012.
+This will return all posts in the 37th week of 2012.
 
     Post.by_week(Time.local(2012,1,1))
 
 This will return all posts from the first week of 2012.
 
@@ -158,10 +192,32 @@
 
     Post.by_day("next tuesday")
 
 This will return all posts for the given day.
 
+## By Quarter (`by_quarter`)
+
+Finds records by 3-month quarterly period of year. Quarter numbering starts at 1. The four quarters of the year begin on Jan 1, Apr 1, Jul 1, and Oct 1 respectively.
+
+To find records from the current quarter:
+
+    Post.by_quarter
+
+To find records based on a quarter, you can pass in a number (representing the quarter number) or a time object:
+
+    Post.by_quarter(4)
+
+This will return all posts in the 4th quarter of the current year.
+
+    Post.by_quarter(2, :year => 2012)
+
+This will return all posts in the 2nd quarter of 2012.
+
+    Post.by_week(Time.local(2012,1,1))
+
+This will return all posts from the first quarter of 2012.
+
 ## Tomorrow (`tomorrow`)
 
 *This method has been shown to be shifty when passed a `Date` object, it is recommended that you pass it an `ActiveSupport::TimeWithZone` object instead.*
 
 To find all posts from the day after the current date:
@@ -192,50 +248,54 @@
 
 You can also pass a string:
 
     Post.yesterday("next tuesday")
 
-## Past (`past`)
+## Before (`before`)
 
 To find all posts before the current time:
 
-    Post.past
+    Post.before
 
 To find all posts before certain time or date:
 
-    Post.past(Date.today + 2)
-    Post.past(Time.now + 5.days)
+    Post.before(Date.today + 2)
+    Post.before(Time.now + 5.days)
 
 You can also pass a string:
 
-    Post.past("next tuesday")
+    Post.before("next tuesday")
 
-## Future (`future`)
+## After (`after`)
 
 To find all posts after the current time:
 
-    Post.future
+    Post.after
 
 To find all posts after certain time or date:
 
-    Post.future(Date.today + 2)
-    Post.future(Time.now + 5.days)
+    Post.after(Date.today + 2)
+    Post.after(Time.now + 5.days)
 
 You can also pass a string:
 
-    Post.future("next tuesday")
+    Post.after("next tuesday")
 
-## Between (`between`)
+## Between (`between` or `between_times`)
 
 To find records between two times:
 
     Post.between(time1, time2)
 
 Also works with dates:
 
     Post.between(date1, date2)
 
+`between_times` is an alias for `between`:
+
+    Post.between_times(time1, time2)  #=> results identical to above
+
 ## Previous (`previous`)
 
 To find the record prior to this one call `previous` on any model instance:
 
     Post.last.previous
@@ -265,9 +325,13 @@
 Or if you're doing it all the time on your model, then it's best to use `by_star_field` at the top of your model:
 
     class Post < ActiveRecord::Base
       by_star_field :something_else
     end
+
+## Mongoid
+
+Mongoid is only tested/supported on version 3.0+
 
 ## Collaborators
 
 Thanks to Thomas Sinclair for the original bump for implementing it. I would like to thank #rubyonrails for their support and the following people: