Update README.markdown

Author: lazychaser

README.markdown

@@ -2,6 +2,9 @@ This is Laravel 4 package that simplifies creating, managing and retrieving tree
 in database. Using [Nested Set](http://en.wikipedia.org/wiki/Nested_set_model) 
 technique high performance descendants retrieval and path-to-node queries can be done.
 
+__IMPORTANT!__ To keep realization of Nested Set Model simple, it's made to work
+within single HTTP requests. Don't build trees in your code. [But, it's possible](#multiple-node-insertion).
+
 ## Installation
 
 The package can be installed as Composer package, just include it into 
@@ -133,6 +136,16 @@ Query can be filtered out from the root node using scope `withoutRoot`:
 $nodes = Category::withoutRoot()->get();
 ```
 
+Deleting nodes as simple as before:
+
+```php
+$node->delete();
+```
+
+### Relations
+
+There are two relations provided by `Node`: _children_ and _parent_.
+
 ### Insertion, re-insertion and deletion of nodes
 
 Operations such as insertion and deletion of nodes imply several independent queries
@@ -145,6 +158,55 @@ performance when tree gets update.
 
 ## Advanced usage
 
+### Custom collection
+
+This package also provides custom collection, which has two additional functions:
+`toDictionary` and `toTree`. The latter builds a tree from the list of nodes just like
+if you would query only root node with all of the children, and children of that
+children, etc. This function restores parent-child relations, so the resulting collection
+will contain only top-level nodes and each of this node will have `children` relation
+filled. The interesting thing is that when some node is rejected by a query constraint,
+whole subtree will be rejected during building the tree.
+
+Consider the tree of categories:
+
+```
+Catalog
+- Mobile
+-- Apple
+-- Samsung
+- Notebooks
+-- Netbooks
+--- Apple
+--- Samsung
+-- Ultrabooks
+```
+
+Let's see what we have in PHP:
+
+```php
+$tree = Category::where('title', '<>', 'Netbooks')->withoutRoot()->get()->toTree();
+echo $tree;
+```
+
+This is what we are going to get:
+
+```js
+[{
+    "title": "Mobile",
+    "children": [{ "title": "Apple", "children": [] }, { "title": "Samsung", "children": [] }]
+},
+
+{
+    "title": "Notebooks",
+    "children": [{ "title": "Ultrabooks", "children": [] }]
+}];
+```
+
+Even though the query returned all nodes but _Netbooks_, the resulting tree does not contain any
+child from that node. This is very helpful when nodes are soft deleted. Active children of soft 
+deleted nodes will inevitably show up in query results, which is not desired in most situations.
+
 ### Multiple node insertion
 
 _DO NOT MAKE MULTIPLE INSERTIONS DURING SINGLE HTTP REQUEST_
@@ -179,3 +241,55 @@ work just fine.
 
 _THIS IS THE ONLY CASE WHEN MULTIPLE NODES CAN BE INSERTED AND/OR RE-INSERTED 
 DURING SINGLE HTTP REQUEST WITHOUT REFRESHING DATA_
+
+#### If you still need this
+
+If you are up to create your tree structure in your code, make shure that target node 
+is always updated. Here is the description of what nodes are target when using insertion
+functions:
+
+```php
+/**
+ * @var Category $node The node being inserted
+ * @var Category $target The target node
+ */
+ 
+$node->appendTo($target);
+$node->prependTo($target);
+$node->before($target);
+$node->after($target);
+$target->append($node);
+$target->prepend($node);
+```
+
+When doing multiple insertions, just call `$target->refresh()` each time before calling 
+any of the above functions.
+
+```php
+DB::transaction(function () {
+    $node = new Category(...);
+    $root = Category::root();
+    
+    // The root here is updated automatically
+    $node->appendTo($root)->save();
+    
+    $nodeSubNode = new Category(...);
+    // No need to update $node since it is just saved
+    // Also, $node gets update since it is new parent for $nodeSubNode
+    $nodeSubNode->appendTo($node)->save();
+    
+    $nodeSibling = new Category(...);
+    // We refresh $root because it is not updated since last operation
+    $nodeSibling->appendTo($root->refresh())->save();
+});
+```
+
+### Deleting nodes
+
+To delete a node, you just call `$node->delete()` as usual. If node is soft deleted, 
+nothing happens. But if node is hard deleted, tree updates. But what if this node has
+children?
+
+When you create your table's schema and use `NestedSet::columns`, it creates foreign
+key for you, since nodes are connected by `parent_id` attribute. When you hard delete
+the node, all of descendants are cascaded.