Merge pull request #386 from billychan/fix-readme

[Doc] README: add parse:true documentation

README.md

@@ -56,27 +56,74 @@ see [UPGRADING](UPGRADING)
 
 ## Usage
 
+Setup
+
 ```ruby
 class User < ActiveRecord::Base
-  # Alias for acts_as_taggable_on :tags
-  acts_as_taggable
+  acts_as_taggable # Alias for acts_as_taggable_on :tags
   acts_as_taggable_on :skills, :interests
 end
 
 @user = User.new(:name => "Bobby")
-@user.tag_list = "awesome, slick, hefty"      # this should be familiar
-@user.skill_list = "joking, clowning, boxing" # but you can do it for any context!
+```
+
+Add and remove a single tag
+
+```ruby
+@user.tag_list.add("awesomer")   # add a single tag. alias for <<
+@user.tag_list.remove("awesome") # remove a single tag
+```
+
+Add and remove multiple tags in an array
+
+```ruby
+@user.tag_list.add("awesomer", "slicker")
+@user.tag_list.remove("awesome", "slick")
+```
+
+You can also add and remove tags in format of String. This would
+be convenient in some cases such as handling tag input param in a String.
+
+Pay attention you need to add `parse: true` as option in this case.
+
+You may also want to take a look at delimiter in the string. The default
+is comma `,` so you don't need to do anything here. However, if you made
+a change on delimiter setting, make sure the string will match. See
+[configuration](#configuration) for more about delimiter.
+
+```ruby
+@user.tag_list.add("awesomer, slicker", parse: true)
+@user.tag_list.remove("awesome, slick", parse: true)
+```
+
+You can also add and remove tags by direct assignment. Note this will
+remove existing tags so use it with attention.
+
+```ruby
+@user.tag_list = "awesome, slick, hefty"
+@user.tags
+# => [<Tag name:"awesome">,<Tag name:"slick">,<Tag name:"hefty">]
+```
+
+With the defined context in model, you have multiple new methods at disposal
+to manage and view the tags in the context. For example, with `:skill` context
+these methods are added to the model: `skill_list`(and `skill_list.add`, `skill_list.remove`
+`skill_list=`), `skills`(plural), skill_counts
+
+
+```ruby
+@user.skill_list = "joking, clowning, boxing"
+
+@user.skills
+# => [<Tag name:"joking">,<Tag name:"clowning">,<Tag name:"boxing">]
 
-@user.tags                                    # => [<Tag name:"awesome">,<Tag name:"slick">,<Tag name:"hefty">]
-@user.skills                                  # => [<Tag name:"joking">,<Tag name:"clowning">,<Tag name:"boxing">]
-@user.skill_list                              # => ["joking","clowning","boxing"] as TagList
+@user.skill_list.add("coding")
 
-@user.tag_list.remove("awesome")              # remove a single tag
-@user.tag_list.remove("awesome, slick")       # works with arrays too
-@user.tag_list.add("awesomer")                # add a single tag. alias for <<
-@user.tag_list.add("awesomer, slicker")       # also works with arrays
+@user.skill_list
+# => ["joking","clowning","boxing", "coding"]
 
-User.skill_counts                             # => [<Tag name="joking" count=2>,<Tag name="clowning" count=1>...]
+User.skill_counts
+# => [<Tag name="joking" count=2>,<Tag name="clowning" count=1>...]
 ```
 
 To preserve the order in which tags are created use `acts_as_ordered_taggable`: