First draft of the new nestedset changes. Open for testing and discussion.

draft/nestedset_changes.tree

+Outline of the changes to the NestedSet
+
+Structural changes:
+In addition to the lft and rgt columns there's now a column 'level' that gets automatically added to your model
+when you use the nestedset. As with the lft and rgt values should never modify this value. All changes to this field
+are handled transparently for you when you move nodes around or insert new ones.
+
+
+General API changes:
+Nearly all of the methods of the Node and Tree interfaces now return FALSE if no parent/child/sibling/ancestor(s)/
+descendant(s) were found. In addition there have been some additions to certain methods. i.e. getAncestors() now 
+has a parameter that allows you to retrieve the ancestors up to a certain level.
+
+
+Fetching relations together with nodes:
+This is how you can temporarily set your own query as the base query that is used by the nestedset.
+The nestedset implementation now uses the latest DQL syntax. Therefore it now uses a reserved alias
+'base' that identifies the tree component. Through that alias you can even select which fields you
+need of the nodes themselves, in addition to the fields you need from related components.
+Note that you dont need to specify the special columns 'lft', 'rgt' and 'level' in any of your
+queries. These are always added automatically since they're essential for the tree structure.
+Example:
+
+$query->select("base.name, le.topic, a.name")->from("VForum_Model_ForumNode base")
+        ->leftJoin("base.lastEntry le")
+        ->leftJoin("le.author a")
+        ->setHydrationMode(Doctrine_Query::HYDRATE_ARRAY);
+$tree = $conn->getTable('VForum_Model_Category')->getTree();
+$tree->setBaseQuery($query);
+$tree = $tree->fetchTree();
+$tree->resetBaseQuery();
+
+This example shows that even array fetching is possible. And since the level is now stored
+in the database and is a regular field of every record you can access it like every other field
+($record['level']), regardless of the hydration mode used (objects/arrays).
+
+Note that you can't modify clauses like where or orderby. These will be overridden by the appropriate method
+you're calling. i.e. if you call getDescendants() the WHERE part results from the fact that you
+want the descendants and the ORDER BY part is always used to retrieve the nodes in the order they appear in the tree,
+so that you can easily traverse and display the tree structure.
\ No newline at end of file