--- a/doc/book/en/annexes/rql/intro.rst	Thu Apr 08 17:47:52 2010 +0200
+++ b/doc/book/en/annexes/rql/intro.rst	Thu Apr 08 17:50:37 2010 +0200
@@ -5,10 +5,10 @@
 Goals of RQL
 ~~~~~~~~~~~~
 
-The goal is to have a language emphasizing the way of browsing relations. As
-such, attributes will be regarded as cases of special relations (in terms of
-implementation, the user should see no difference between an attribute and a
-relation).
+The goal is to have a language making relations browsing easy. As
+such, attributes will be regarded as cases of special relations (in
+terms of usage, the user should see no syntactic difference between an
+attribute and a relation).
 
 Comparison with existing languages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -32,10 +32,10 @@
 
 We should look in more detail, but here are already some ideas for the moment
 ... Versa_ is the language most similar to what we wanted to do, but the model
-underlying data being RDF, there is some number of things such as namespaces or
+underlying data being RDF, there are some things such as namespaces or
 handling of the RDF types which does not interest us. On the functionality
 level, Versa_ is very comprehensive including through many functions of
-conversion and basic types manipulation, which may need to be guided at one time
+conversion and basic types manipulation, which we may want to look at one time
 or another.  Finally, the syntax is a little esoteric.
 
 

--- a/doc/book/en/development/devcore/dbapi.rst	Thu Apr 08 17:47:52 2010 +0200
+++ b/doc/book/en/development/devcore/dbapi.rst	Thu Apr 08 17:50:37 2010 +0200
@@ -5,9 +5,10 @@
 
 The Python API developped to interface with RQL is inspired from the standard db-api,
 with a Connection object having the methods cursor, rollback and commit essentially.
-The most important method is the `execute` method of a cursor :
+The most important method is the `execute` method of a cursor.
 
-`execute(rqlstring, args=None, cachekey=None, build_descr=True)`
+.. sourcecode:: python
+  execute(rqlstring, args=None, cachekey=None, build_descr=True)
 
 :rqlstring: the RQL query to execute (unicode)
 :args: if the query contains substitutions, a dictionary containing the values to use
@@ -18,10 +19,11 @@
    through this argument
 
 
-The `Connection` object owns the methods `commit` and `rollback`. You *should
-never need to use them* during the development of the web interface based on
-the *CubicWeb* framework as it determines the end of the transaction depending
-on the query execution success.
+The `Connection` object owns the methods `commit` and `rollback`. You
+*should never need to use them* during the development of the web
+interface based on the *CubicWeb* framework as it determines the end
+of the transaction depending on the query execution success. They are
+however useful in other contexts such as tests.
 
 .. note::
   While executing update queries (SET, INSERT, DELETE), if a query generates
@@ -30,6 +32,7 @@
 
 Executing RQL queries from a view or a hook
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 When you're within code of the web interface, the db-api like connexion is
 handled by the request object. You should not have to access it directly, but
 use the `execute` method directly available on the request, eg:
@@ -50,21 +53,15 @@
 
    self._cw.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
+But it must be written in a syntax that will benefit from the use
 of a cache on the RQL server side:
 
 .. sourcecode:: python
 
-   self._cw.execute('Any T WHERE T in_conf C, C eid %(x)s', {'x': entity.eid}, 'x')
+   self._cw.execute('Any T WHERE T in_conf C, C eid %(x)s', {'x': entity.eid})
 
-Beside proper usage of the `args` argument, notice the latest argument: this is what's called
-the cache key. The cache key should be either a string or a tuple containing the names of keys
-in args which are referencing eids. *YOU MUST SET THIS PROPERLY* if you don't want weird result
-on queries which have ambigous solutions deambiguified by specifing an eid. So the good habit is:
-*always put in the cache key all eid keys*.
-
-The syntax tree is build once for the "generic" RQL and can be re-used
-with a number of different eid.
+The syntax tree is built once for the "generic" RQL and can be re-used
+with a number of different eids.
 
 Alternativelly, some of the common data related to an entity can be obtained from
 the top-level `entity.related()` method (which is used under the hood by the orm

--- a/doc/book/en/intro/concepts.rst	Thu Apr 08 17:47:52 2010 +0200
+++ b/doc/book/en/intro/concepts.rst	Thu Apr 08 17:50:37 2010 +0200
@@ -339,5 +339,5 @@
 .. Note:
    RQL queries executed in hooks and operations are *unsafe* by default, e.g. the
    read and write security is deactivated unless explicitly asked.
-  
+
 .. |cubicweb| replace:: *CubicWeb*