README.md in fmrest-0.3.3 vs README.md in fmrest-0.4.0

@@ -445,36 +445,53 @@
 Since Spyke is API-agnostic it only provides a wide-purpose `.where` method for
 passing arbitrary parameters to the REST backend. fmrest-ruby however is well
 aware of its backend API, so it extends Spkye models with a bunch of useful
 querying methods.
 
-```ruby
-class Honeybee < Spyke::Base
-  include FmRest::Spyke
+#### .limit
 
-  attributes name: "Bee Name", age: "Bee Age"
+`.limit` sets the limit for get and find request:
 
-  has_portal :hives, portal_key: "Bee Hives"
-end
+```ruby
+Honeybee.limit(10)
 ```
 
-#### .limit
+NOTE: You can also set a default limit value for a model class, see
+[Other notes on querying](#other-notes-on-querying).
 
-`.limit` sets the limit for get and find request:
+You can also use `.limit` to set limits on portals:
 
 ```ruby
-Honeybee.limit(10)
+Honeybee.limit(hives: 3, flowers: 2)
 ```
 
+To remove the limit on a portal set it to `nil`:
+
+```ruby
+Honeybee.limit(flowers: nil)
+```
+
 #### .offset
 
 `.offset` sets the offset for get and find requests:
 
 ```ruby
 Honeybee.offset(10)
 ```
 
+You can also use `.offset` to set offsets on portals:
+
+```ruby
+Honeybee.offset(hives: 3, flowers: 2)
+```
+
+To remove the offset on a portal set it to `nil`:
+
+```ruby
+Honeybee.offset(flowers: nil)
+```
+
 #### .sort
 
 `.sort` (or `.order`) sets sorting options for get and find requests:
 
 ```ruby
@@ -488,20 +505,48 @@
 ```ruby
 Honeybee.sort(:name, :age!)
 Honeybee.sort(:name, :age__desc)
 ```
 
+NOTE: You can also set default sort values for a model class, see
+[Other notes on querying](#other-notes-on-querying).
+
 #### .portal
 
-`.portal` (or `.includes`) sets the portals to fetch for get and find requests
-(this recognizes portals defined with `has_portal`):
+`.portal` (aliased as `.includes` and `.portals`) sets which portals to fetch
+(if any) for get and find requests (this recognizes portals defined with
+`has_portal`):
 
 ```ruby
-Honeybee.portal(:hives)
+Honeybee.portal(:hives)   # include just the :hives portal
 Honeybee.includes(:hives) # alias method
+Honeybee.portals(:hives, :flowers) # alias for pluralization fundamentalists
 ```
 
+Chaining calls to `.portal` will add portals to the existing included list:
+
+```ruby
+Honeybee.portal(:flowers).portal(:hives) # include both portals
+```
+
+If you want to disable portals for the scope call `.portal(false)`:
+
+```ruby
+Honeybee.portal(false) # disable portals for this scope
+```
+
+If you want to include all portals call `.portal(true)`:
+
+```ruby
+Honeybee.portal(true) # include all portals
+```
+
+For convenience you can also use `.with_all_portals` and `.without_portals`,
+which behave just as calling `.portal(true)` and `portal(false)` respectively.
+
+NOTE: By default all portals are included.
+
 #### .query
 
 `.query` sets query conditions for a find request (and supports attributes as
 defined with `attributes`):
 
@@ -551,12 +596,14 @@
 ```
 
 You can also set default values for limit and sort on the class:
 
 ```ruby
-Honeybee.default_limit = 1000
-Honeybee.default_sort = [:name, :age!]
+class Honeybee < FmRest::Spyke::Base
+  self.default_limit = 1000
+  self.default_sort = [:name, :age!]
+end
 ```
 
 Calling any `Enumerable` method on the resulting scope object will trigger a
 server request, so you can treat the scope as a collection:
 
@@ -670,10 +717,10 @@
 
 - [ ] Support for FM18 features
 - [ ] Better/simpler-to-use core Ruby API
 - [ ] Better API documentation and README
 - [ ] Oauth support
-- [ ] Support for portal limit and offset
+- [x] Support for portal limit and offset
 - [x] More options for token storage
 - [x] Support for container fields
 - [x] Optional logging
 - [x] FmRest::Spyke::Base class for single inheritance (as alternative for mixin)
 - [x] Specs