--- a/doc/book/en/development/datamodel/definition.rst	Tue Feb 02 21:14:01 2010 +0100
+++ b/doc/book/en/development/datamodel/definition.rst	Wed Feb 03 09:18:47 2010 +0100
@@ -397,6 +397,10 @@
 * it is possible to use the attribute `meta` to flag an entity type as a `meta`
   (e.g. used to describe/categorize other entities)
 
+*Note* : if you end up with an `if` in the definition of your entity, this probably
+means that you need two separate entities that implement the `ITree` interface and
+get the result from `.children()` which ever entity is concerned.
+
 Inheritance
 ```````````
 XXX feed me

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/gettingdata.rst	Wed Feb 03 09:18:47 2010 +0100
@@ -0,0 +1,46 @@
+
+.. _Getting Data:
+
+Getting Data
+------------
+
+You might have spotted this in the explanations about the views, to
+get data, when not using a toplevel method, you will execute an RQL
+query over the request. For more details about RQL, head out to the
+`RQL chapter`
+
+Basic cases
+```````````
+In a similiar way that you might be used to in SQL, to obtain data
+from the RQL backend, you will execute an RQL command and obtain a
+resultset ::
+
+   rset = self.req.execute(rql_command)
+
+Then, you can use the data from the rset.
+
+XXX complete section with examples
+
+Use of the cache for RQL execution
+``````````````````````````````````
+Let's say you want to get T which is in configuration C, this translates to ::
+
+         self.req.execute('Any T WHERE T in_conf C, C eid "%s"' % entity.eid)
+
+But it can also be written in a syntax that will benefit from the use
+of a cache on the RQL server side. ::
+
+          self.req.execute('Any T WHERE T in_conf C, C eid %(x)s', {'x': entity.eid}, 'x')
+
+The syntax tree is build once for the "generic" RQL and can be re-used
+with a number of different eid. Alternativelly, some of the common
+data related to an entity can be obtained from the top-level
+`entity.related()` method. The above would then be translated to ::
+
+    entity.related('in_conf', 'object')
+
+The `related()` method makes extensive use of the cache mechanisms so
+you don't have to worry about them. Additionnaly this use will get you
+commonly used attributes that you will be able to use in your view
+generation without having to ask the data backend.
+

--- a/doc/book/en/development/devweb/index.rst	Tue Feb 02 21:14:01 2010 +0100
+++ b/doc/book/en/development/devweb/index.rst	Wed Feb 03 09:18:47 2010 +0100
@@ -12,6 +12,7 @@
    property
    rtags
    views
+   gettingdata
    form
    facets
    httpcaching

--- a/doc/book/en/development/webstdlib/primary.rst	Tue Feb 02 21:14:01 2010 +0100
+++ b/doc/book/en/development/webstdlib/primary.rst	Wed Feb 03 09:18:47 2010 +0100
@@ -6,6 +6,13 @@
 
 This view is supposed to render a maximum of informations about the entity.
 
+Beware when overriding this top level `cell_call` in a primary because
+you will loose a bunch of functionnality that automatically comes with
+it : `in-context` boxes, related boxes, some navigation, some
+displaying of the metadata, etc. It might be interresting to
+understand the implementation fo the `cell_call` to override specifics
+bits of it.
+
 Rendering methods and attributes for ``PrimaryView``
 ----------------------------------------------------