--- a/doc/book/en/annexes/rql/intro.rst	Thu Jul 08 20:19:20 2010 +0200
+++ b/doc/book/en/annexes/rql/intro.rst	Fri Jul 09 12:48:03 2010 +0200
@@ -45,6 +45,13 @@
 conversion and basic types manipulation, which we may want to look at one time
 or another.  Finally, the syntax is a little esoteric.
 
+Datalog
+```````
+
+Datalog_ is a prolog derived query langage which applies to relational
+databases. It is more expressive than RQL in that it accepts either
+extensional_ and intensional_ predicates (or relations). As of now,
+RQL only deals with intensional relations.
 
 The different types of queries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -64,78 +71,91 @@
    Remove entities or relations existing in the database.
 
 
-Concepts
-~~~~~~~~
-
-Entity type
-```````````
+RQL relation expressions
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-RQL manipulates variables that are instances of entities.
-Each entity has its own type which are used in backend to improve the query
-execution plan.
+RQL expressions apply to a live database defined by a
+:ref:`datamodel_definition`. Apart from the main type, or head, of the
+expression (search, insert, etc.) the most common constituent of an
+RQL expression is a (set of) relation expression(s).
 
-Restrictions
-````````````
+An RQL relation expression contains three components:
 
-They are conditions used to limit the perimeter of the result set.
-
-Relations
-`````````
-A relation is a `3-expression` defined as follows:
+* the subject, which is an entity type
+* the predicate, which is a relation definition (an arc of the schema)
+* the object, which is either an attribute or a relation to another entity
 
 .. image:: Graph-ex.gif
     :alt: <subject> <predicate> <object>
     :align: center
 
-A RQL relation contains three components:
+.. warning::
 
-* the subject, which is an entity type
-* the predicate, which is an oriented graph
-* the object, which is either an attribute or a relation to another entity
+ A relation is always expressed in the order: ``subject``,
+ ``predicate``, ``object``.
 
-In cubicweb, the term `relation` is often found without ambiguity instead of `predicate`.
-This predicate is also known as the `property` of the triple in `RDF concepts`_
-
-A relation is always expressed in the order: subject, predicate, object.
+ It is important to determine if the entity type is subject or object
+ to construct a valid expression. Inverting the subject/object is an
+ error since the relation cannot be found in the schema.
 
-It's important to determine if entity type is subject or object to construct a
-valid expression. An inversion subject/object is equivalent to an RQL error
-since the supposed relation cannot be found in schema. If you don't have access
-to the code, you could find the order by looking at the schema image in manager
-views (the subject is located at the beginning of the arrow).
+ If one does not have access to the code, one can find the order by
+ looking at the schema image in manager views (the subject is located
+ at the beginning of the arrow).
+
+An example of two related relation expressions::
 
-.. _SQL: http://www.firstsql.com/tutor5.htm
-.. _RDF concepts: http://www.w3.org/TR/rdf-concepts/
+  P works_for C, P name N
 
-Cardinality
-```````````
-XXX
+RQL variables represent typed entities. The type of entities is
+either automatically inferred (by looking at the possible relation
+definitions, see :ref:`RelationDefinition`) or explicitely constrained
+using the ``is`` meta relation.
 
-Cardinality is an important concept to model your business rules.
-They determine nu./tutorials/advanced/index.rst
-
-Please refer to the `datamodel definitions`_ for a deep understanding.
+In the example above, we barely need to look at the schema. If
+variable names (in the RQL expression) and relation type names (in the
+schema) are expresssively designed, the human reader can infer as much
+as the |cubicweb| querier.
 
-`Relations`_ are always expressed by cardinality rules (`**` by default)
+The ``P`` variable is used twice but it always represent the same set
+of entities. Hence ``P works_for C`` and ``P name N`` must be
+compatible in the sense that all the Ps (which *can* refer to
+different entity types) must accept the ``works_for`` and ``name``
+relation types. This does restrict the set of possible values of P.
 
-.. _datamodel definitions: ./devrepo/datamodel/definition.rst
-
-Transaction
-```````````
+Adding another relation expression::
 
-RQL supports notion of **transactions**; i.e. sequences of RQL statements
-without invoking security hooks of the instance's schema.
-
-When you're ready to make persistent the changes, you have to *commit* the
-modification in calling `commit()`.
+  P works_for C, P name N, C name "logilab"
 
-If an error is found (typically in raising a ValidationError), you have the
-possibility to roll back the transaction in invoking `rollback()` function; i.e
-to come back to the initial state of the transaction.
+This further restricts the possible values of P through an indirect
+constraint on the possible values of ``C``. The RQL-level unification_
+happening there is translated to one (or several) joins_ at the
+database level.
 
-Please, refer to the :ref:`Migration` chapter if you want more details.
+.. note::
+
+ In |cubicweb|, the term `relation` is often found without ambiguity
+ instead of `predicate`.  This predicate is also known as the
+ `property` of the triple in `RDF concepts`_
 
 
+RQL Operators
+~~~~~~~~~~~~~
 
+An RQL expression's head can be completed using various operators such
+as ``ORDERBY``, ``GROUPBY``, ``HAVING``, ``LIMIT`` etc.
+
+RQL relation expressions can be grouped with ``UNION`` or
+``WITH``. Predicate oriented keywords such as ``EXISTS``, ``OR``,
+``NOT`` are available.
+
+The complete zoo of RQL operators is described extensively in the
+following chapter (:ref:`RQL`).
+
+.. _RDF concepts: http://www.w3.org/TR/rdf-concepts/
 .. _Versa: http://wiki.xml3k.org/Versa
 .. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/
+.. _unification: http://en.wikipedia.org/wiki/Unification_(computing)
+.. _joins: http://en.wikipedia.org/wiki/Join_(SQL)
+.. _Datalog: http://en.wikipedia.org/wiki/Datalog
+.. _intensional: http://en.wikipedia.org/wiki/Intensional_definition
+.. _extensional: http://en.wikipedia.org/wiki/Extension_(predicate_logic)

--- a/doc/book/en/devrepo/datamodel/definition.rst	Thu Jul 08 20:19:20 2010 +0200
+++ b/doc/book/en/devrepo/datamodel/definition.rst	Fri Jul 09 12:48:03 2010 +0200
@@ -1,5 +1,7 @@
  .. -*- coding: utf-8 -*-
 
+.. _datamodel_definition:
+
 Yams *schema*
 -------------
 
@@ -11,6 +13,8 @@
 
 .. _`Yams`: http://www.logilab.org/project/yams
 
+.. _datamodel_overview:
+
 Overview
 ~~~~~~~~
 
@@ -408,7 +412,7 @@
 * special relations "has_<ACTION>_permission" can not be used
 
 
-
+.. _yams_example:
 
 Defining your schema using yams
 -------------------------------
@@ -494,15 +498,15 @@
 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
+.. Inheritance
+.. ```````````
+.. XXX feed me
 
 
 Definition of relations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-XXX add note about defining relation type / definition
+.. XXX add note about defining relation type / definition
 
 A relation is defined by a Python class heriting `RelationType`. The name
 of the class corresponds to the name of the type. The class then contains
@@ -546,7 +550,7 @@
 :Historical note:
 
    It has been historically possible to use `ObjectRelation` which
-   defines a relation in the opposite direction. This feature is soon to be
+   defines a relation in the opposite direction. This feature is
    deprecated and therefore should not be used in newly written code.
 
 :Future deprecation note:

--- a/doc/book/en/tutorials/base/maintemplate.rst	Thu Jul 08 20:19:20 2010 +0200
+++ b/doc/book/en/tutorials/base/maintemplate.rst	Fri Jul 09 12:48:03 2010 +0200
@@ -123,8 +123,8 @@
 
 .. image:: ../../images/lax-book_06-simple-main-template_en.png
 
-XXX
-[WRITE ME]
+.. XXX
+.. [WRITE ME]
 
 * customize MainTemplate and show that everything in the user
   interface can be changed