README.md in ohm-3.0.3 vs README.md in ohm-3.1.0

@@ -19,10 +19,11 @@
 Related projects
 ----------------
 
 These are libraries in other languages that were inspired by Ohm.
 
+* [Ohm](https://github.com/soveran/ohm-crystal) for Crystal, created by soveran
 * [JOhm](https://github.com/xetorthio/johm) for Java, created by xetorthio
 * [Lohm](https://github.com/slact/lua-ohm) for Lua, created by slact
 * [ohm.lua](https://github.com/amakawa/ohm.lua) for Lua, created by amakawa
 * [Nohm](https://github.com/maritz/nohm) for Node.js, created by maritz
 * [Redisco](https://github.com/iamteem/redisco) for Python, created by iamteem
@@ -172,19 +173,19 @@
 Attribute types
 ---------------
 
 Ohm::Model provides 4 attribute types:
 
-* {Ohm::Model.attribute attribute},
-* {Ohm::Model.set set}
-* {Ohm::Model.list list}
-* {Ohm::Model.counter counter}
+* `Ohm::Model.attribute`,
+* `Ohm::Model.set`
+* `Ohm::Model.list`
+* `Ohm::Model.counter`
 
 and 2 meta types:
 
-* {Ohm::Model.reference reference}
-* {Ohm::Model.collection collection}.
+* `Ohm::Model.reference`
+* `Ohm::Model.collection`.
 
 ### attribute
 
 An `attribute` is just any value that can be stored as a string. In the
 example above, we used this field to store the event's `name`. You can
@@ -302,13 +303,13 @@
 end
 ```
 
 ## Sorting
 
-Since `attendees` is a {Ohm::Model::Set Set}, it exposes two sorting
-methods: {Ohm::Model::Collection#sort sort} returns the elements
-ordered by `id`, and {Ohm::Model::Collection#sort_by sort_by} receives
+Since `attendees` is a `Ohm::Model::Set`, it exposes two sorting
+methods: `Ohm::Model::Collection#sort` returns the elements
+ordered by `id`, and `Ohm::Model::Collection#sort_by` receives
 a parameter with an attribute name, which will determine the sorting
 order. Both methods receive an options hash which is explained below:
 
 ### :order
 
@@ -335,12 +336,12 @@
 `limit: [0, 10]` will get the first 10 entries starting from offset 0.
 
 ### :by
 
 Key or Hash key with which to sort by. An important distinction with
-using {Ohm::Model::Collection#sort sort} and
-{Ohm::Model::Collection#sort_by sort_by} is that `sort_by` automatically
+using `Ohm::Model::Collection#sort` and
+`Ohm::Model::Collection#sort_by` is that `sort_by` automatically
 converts the passed argument with the assumption that it is a hash key
 and it's within the current model you are sorting.
 
 ```ruby
 Post.all.sort_by(:title)     # SORT Post:all BY Post:*->title
@@ -352,12 +353,12 @@
 otherwise.
 
 ### :get
 
 A key pattern to return, e.g. `Post:*->title`. As is the case with
-the `:by` option, using {Ohm::Model::Collection#sort sort} and
-{Ohm::Model::Collection#sort_by sort_by} has distinct differences in
+the `:by` option, using `Ohm::Model::Collection#sort` and
+`Ohm::Model::Collection#sort_by` has distinct differences in
 that `sort_by` does much of the hand-coding for you.
 
 ```ruby
 Post.all.sort_by(:title, get: :title)
 # SORT Post:all BY Post:*->title GET Post:*->title
@@ -389,11 +390,11 @@
 about instances of the model `Comment`. If you want to get a list of IDs
 you can use `post.comments.ids`.
 
 ### References explained
 
-Doing a {Ohm::Model.reference reference} is actually just a shortcut for
+Doing a `Ohm::Model.reference` is actually just a shortcut for
 the following:
 
 ```ruby
 # Redefining our model above
 class Comment < Ohm::Model
@@ -421,14 +422,14 @@
 Comment.find(post_id: 1)
 ```
 
 ### Collections explained
 
-The reason a {Ohm::Model.reference reference} and a
-{Ohm::Model.collection collection} go hand in hand, is that a collection is
+The reason a `Ohm::Model.reference` and a
+`Ohm::Model.collection` go hand in hand, is that a collection is
 just a macro that defines a finder for you, and we know that to find a model
-by a field requires an {Ohm::Model.index index} to be defined for the field
+by a field requires an `Ohm::Model.index` to be defined for the field
 you want to search.
 
 ```ruby
 # Redefining our post above
 class Post < Ohm::Model
@@ -458,21 +459,39 @@
 # exploring `to_reference` reveals a very interesting and simple concept:
 Post.to_reference == :post
 # => true
 ```
 
+Modules
+-------
+
+If your models are defined inside a module, you will have to define
+the references and collections as in the following example:
+
+```ruby
+module SomeNamespace
+  class Foo < Ohm::Model
+    attribute :name
+  end
+  
+  class Bar < Ohm::Model
+    reference :foo, 'SomeNamespace::Foo'
+  end
+end
+```
+
 Indices
 -------
 
-An {Ohm::Model.index index} is a set that's handled automatically by Ohm. For
+An `Ohm::Model.index` is a set that's handled automatically by Ohm. For
 any index declared, Ohm maintains different sets of objects IDs for quick
 lookups.
 
 In the `Event` example, the index on the name attribute will
 allow for searches like `Event.find(name: "some value")`.
 
-Note that the methods {Ohm::Model::Set#find find} and
-{Ohm::Model::Set#except except} need a corresponding index in order to work.
+Note that the methods `Ohm::Model::Set#find` and
+`Ohm::Model::Set#except` need a corresponding index in order to work.
 
 ### Finding records
 
 You can find a collection of records with the `find` method: