--- a/appobject.py	Fri Apr 16 11:13:46 2010 +0200
+++ b/appobject.py	Fri Apr 16 12:32:52 2010 +0200
@@ -3,6 +3,8 @@
 # :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
 # :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
 """
+.. _appobject:
+
 The `AppObject` class
 ---------------------
 

--- a/cwvreg.py	Fri Apr 16 11:13:46 2010 +0200
+++ b/cwvreg.py	Fri Apr 16 12:32:52 2010 +0200
@@ -7,18 +7,19 @@
 The `VRegistry`
 ---------------
 
-The `VRegistry` can be seen as a two level dictionary. It contains all objects
-loaded dynamically to build a |cubicweb| application. Basically:
+The `VRegistry` can be seen as a two levels dictionary. It contains
+all dynamically loaded objects (subclasses of :ref:`appobject`) to
+build a |cubicweb| application. Basically:
 
-* first level key return a *registry*. This key corresponds to the `__registry__`
-  attribute of application object classes
+* the first level key returns a *registry*. This key corresponds to the
+  `__registry__` attribute of application object classes
 
-* second level key return a list of application objects which share the same
-  identifier. This key corresponds to the `__regid__` attribute of application
-  object classes.
+* the second level key returns a list of application objects which
+  share the same identifier. This key corresponds to the `__regid__`
+  attribute of application object classes.
 
-A *registry* hold a specific kind of application objects. You've for instance
-a registry for entity classes, another for views, etc...
+A *registry* holds a specific kind of application objects. There is
+for instance a registry for entity classes, another for views, etc...
 
 The `VRegistry` has two main responsibilities:
 
@@ -27,7 +28,6 @@
 - handling the registration process at startup time, and during automatic
   reloading in debug mode.
 
-
 .. _AppObjectRecording:
 
 Details of the recording process
@@ -36,21 +36,22 @@
 .. index::
    vregistry: registration_callback
 
-On startup, |cubicweb| have to load application objects defined in its library
-and in cubes used by the instance. Application objects from the library are
-loaded first, then those provided by cubes are loaded in an ordered way (e.g. if
-your cube depends on an other, objects from the dependancy will be loaded
-first). Cube's modules or packages where appobject are looked at is explained in
-:ref:`cubelayout`.
+On startup |cubicweb| loads application objects defined in its library
+and in cubes used by the instance. Application objects from the
+library are loaded first, then those provided by cubes are loaded in
+dependency order (e.g. if your cube depends on an other, objects from
+the dependency will be loaded first). Cube's modules or packages where
+appobject are looked for is explained in :ref:`cubelayout`.
 
 For each module:
 
 * by default all objects are registered automatically
 
-* if some objects have to replace other objects, or be included only if some
-  condition is true, you'll have to define a `registration_callback(vreg)`
-  function in your module and explicitly register **all objects** in this module,
-  using the api defined below.
+* if some objects have to replace other objects, or have to be
+  included only if some condition is met, you'll have to define a
+  `registration_callback(vreg)` function in your module and explicitly
+  register **all objects** in this module, using the api defined
+  below.
 
 .. Note::
     Once the function `registration_callback(vreg)` is implemented in a module,
@@ -71,7 +72,6 @@
 .. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_if_interface_found
 .. automethod:: cubicweb.cwvreg.CubicWebVRegistry.unregister
 
-
 Examples:
 
 .. sourcecode:: python
@@ -115,13 +115,15 @@
 Runtime objects selection
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that we've all application objects loaded, the question is : when I want some
-specific object, for instance the primary view for a given entity, how do I get
-the proper object ? This is what we call the **selection mechanism**.
+Now that we have all application objects loaded, the question is : when
+I want some specific object, for instance the primary view for a given
+entity, how do I get the proper object ? This is what we call the
+**selection mechanism**.
 
 As explained in the :ref:`Concepts` section:
 
-* each application object has a **selector**, defined by its `__select__` class attribute
+* each application object has a **selector**, defined by its
+  `__select__` class attribute
 
 * this selector is responsible to return a **score** for a given context
 
@@ -141,9 +143,9 @@
   In such cases you would need to review your design and make sure your selectors
   or appobjects are properly defined.
 
-For instance, if you are selecting the primary (eg `__regid__ = 'primary'`) view (eg
-`__registry__ = 'views'`) for a result set containing a `Card` entity, 2 objects
-will probably be selectable:
+For instance, if you are selecting the primary (eg `__regid__ =
+'primary'`) view (eg `__registry__ = 'views'`) for a result set
+containing a `Card` entity, two objects will probably be selectable:
 
 * the default primary view (`__select__ = implements('Any')`), meaning
   that the object is selectable for any kind of entity type

--- a/doc/book/en/admin/create-instance.rst	Fri Apr 16 11:13:46 2010 +0200
+++ b/doc/book/en/admin/create-instance.rst	Fri Apr 16 12:32:52 2010 +0200
@@ -20,7 +20,7 @@
 sufficient. You can anyway modify the configuration later on by editing
 configuration files. When a user/psswd is requested to access the database
 please use the login you create at the time you configured the database
-(:ref:`ConfigurationPostgresql`).
+(:ref:`PostgresqlConfiguration`).
 
 It is important to distinguish here the user used to access the database and the
 user used to login to the cubicweb instance. When an instance starts, it uses

--- a/doc/book/en/admin/instance-config.rst	Fri Apr 16 11:13:46 2010 +0200
+++ b/doc/book/en/admin/instance-config.rst	Fri Apr 16 12:32:52 2010 +0200
@@ -157,7 +157,7 @@
 
 :`ui.encoding`:
     Character encoding to use for the web
-:`navigation.short-line-size`: # XXX should be in ui
+:`navigation.short-line-size`:
     number of characters for "short" display
 :`navigation.page-size`:
     maximum number of entities to show per results page

--- a/doc/book/en/development/vreg.rst	Fri Apr 16 11:13:46 2010 +0200
+++ b/doc/book/en/development/vreg.rst	Fri Apr 16 12:32:52 2010 +0200
@@ -1,16 +1,16 @@
 The VRegistry, selectors and application objects
 ================================================
 
-This chapter talk about core concepts of the |cubicweb| framework, that make it
-different from other framework (and probably not easy to grasp at a first
-glance). You won't be able to do advanced development with |cubicweb| without
-a good understanding of what's explain below.
+This chapter talks about core concepts of the |cubicweb| framework,
+that make it different from other frameworks (and maybe not easy to
+grasp at a first glance). To be able to do advanced development with
+|cubicweb| you need a good understanding of what is explained below.
 
-This chapter goes deep into details. You don't have to remember them all but keep
-it in mind so you can go back there later...
+This chapter goes deep into details. You don't have to remember them
+all but keep it in mind so you can go back there later.
 
-.. toctree::
-   :maxdepth: 1
+An overview of AppObjects, the VRegistry and Selectors is given in the
+:ref:`VRegistryIntro` chapter.
 
 .. autodocstring:: cubicweb.cwvreg
 .. autodocstring:: cubicweb.selectors
@@ -105,6 +105,3 @@
 
 You'll also find some other (very) specific selectors hidden in other modules
 than :mod:`cubicweb.selectors`.
-
-
-.. |cubicweb| replace:: *CubicWeb*

--- a/doc/book/en/intro/concepts.rst	Fri Apr 16 11:13:46 2010 +0200
+++ b/doc/book/en/intro/concepts.rst	Fri Apr 16 12:32:52 2010 +0200
@@ -181,8 +181,8 @@
 
   object's `__registry__` : object's `__regid__` : [list of app objects]
 
-E.g. The `vregistry` contains several registries which hold a list of
-appobjects associated to an identifier.
+E.g. the `vregistry` contains several (sub-)registries which hold a
+list of appobjects associated to an identifier.
 
 The base class of appobjects is :class:`cubicweb.appobject.AppObject`.
 
@@ -214,7 +214,6 @@
 - `entities`
 - `views`
 - `sobjects`
-- `hooks`
 
 
 Once initialized, there are three common ways to retrieve some application object
@@ -238,7 +237,8 @@
 The RQL query language
 ----------------------
 
-**No need for a complicated ORM when you have a powerful query language**
+**No need for a complicated ORM when you have a powerful data
+  manipulation language**
 
 All the persistent data in a |cubicweb| instance is retrieved and modified by
 using the Relation Query Language.
@@ -247,7 +247,7 @@
 emphasize browsing relations.
 
 
-db-api
+DB-API
 ~~~~~~
 
 The repository exposes a `db-api`_ like api but using the RQL instead of SQL.

--- a/doc/book/en/intro/history.rst	Fri Apr 16 11:13:46 2010 +0200
+++ b/doc/book/en/intro/history.rst	Fri Apr 16 12:32:52 2010 +0200
@@ -7,8 +7,11 @@
 developing in 2001 as an offspring of its Narval_ research project. *CubicWeb*
 is written in Python and includes a data server and a web engine.
 
-Its data server publishes data federated from different sources like SQL
-databases, LDAP directories or even from other CubicWeb data servers.
+Its data server publishes data federated from different sources like
+SQL databases, LDAP directories, `VCS`_ repositories or even from other
+CubicWeb data servers.
+
+.. _`VCS`: http://en.wikipedia.org/wiki/Revision_control
 
 Its web engine was designed to let the final user control what content to select
 and how to display it. It allows one to browse the federated data sources and

--- a/doc/book/en/tutorials/base/create-cube.rst	Fri Apr 16 11:13:46 2010 +0200
+++ b/doc/book/en/tutorials/base/create-cube.rst	Fri Apr 16 12:32:52 2010 +0200
@@ -302,7 +302,7 @@
 
 Excepted side boxes, we can see all of them already in action in the
 blog entry view. This is all described in more details in
-:ref:`primary`.
+:ref:`primary_view`.
 
 We can for example add in front of the publication date a prefix
 specifying that the date we see is the publication date.

--- a/selectors.py	Fri Apr 16 11:13:46 2010 +0200
+++ b/selectors.py	Fri Apr 16 12:32:52 2010 +0200
@@ -12,37 +12,33 @@
 
 You can combine selectors using the `&`, `|` and `~` operators.
 
-When two selectors are combined using the `&` operator (formerly `chainall`), it
-means that both should return a positive score. On success, the sum of scores is returned.
+When two selectors are combined using the `&` operator, it means that
+both should return a positive score. On success, the sum of scores is
+returned.
 
-When two selectors are combined using the `|` operator (former `chainfirst`), it
-means that one of them should return a positive score. On success, the first
+When two selectors are combined using the `|` operator, it means that
+one of them should return a positive score. On success, the first
 positive score is returned.
 
 You can also "negate" a selector by precedeing it by the `~` unary operator.
 
-Of course you can use parens to balance expressions.
-
-.. Note:
-  When one chains selectors, the final score is the sum of the score of each
-  individual selector (unless one of them returns 0, in which case the object is
-  non selectable)
-
+Of course you can use parenthesis to balance expressions.
 
 Example
 ~~~~~~~
 
-The goal: when on a Blog, one wants the RSS link to refer to blog entries, not to
+The goal: when on a blog, one wants the RSS link to refer to blog entries, not to
 the blog entity itself.
 
-To do that, one defines a method on entity classes that returns the RSS stream
-url for a given entity. The default implementation on
-:class:`~cubicweb.entities.AnyEntity` (the generic entity class used as base for
-all others) and a specific implementation on Blog will do what we want.
+To do that, one defines a method on entity classes that returns the
+RSS stream url for a given entity. The default implementation on
+:class:`~cubicweb.entities.AnyEntity` (the generic entity class used
+as base for all others) and a specific implementation on `Blog` will
+do what we want.
 
-But when we have a result set containing several Blog entities (or different
-entities), we don't know on which entity to call the aforementioned method. In
-this case, we keep the generic behaviour.
+But when we have a result set containing several `Blog` entities (or
+different entities), we don't know on which entity to call the
+aforementioned method. In this case, we keep the generic behaviour.
 
 Hence we have two cases here, one for a single-entity rsets, the other for
 multi-entities rsets.
@@ -52,7 +48,7 @@
 .. sourcecode:: python
 
   class RSSIconBox(ExtResourcesBoxTemplate):
-    '''just display the RSS icon on uniform result set'''
+    ''' just display the RSS icon on uniform result set '''
     __select__ = ExtResourcesBoxTemplate.__select__ & non_final_entity()
 
 It takes into account:
@@ -116,8 +112,9 @@
 
 The proper way to implement this with |cubicweb| is two have two different
 classes sharing the same identifier but with different selectors so you'll get
-the correct one according to the context:
+the correct one according to the context.
 
+.. sourcecode:: python
 
     class UserLink(component.Component):
 	'''display a link to the connected user object with a loggout link'''
@@ -137,8 +134,9 @@
 	    # display login link
             ...
 
-The big advantage, aside readibily once you're familiar with the system, is that
-your cube becomes much more easily customizable by improving componentization.
+The big advantage, aside readability once you're familiar with the
+system, is that your cube becomes much more easily customizable by
+improving componentization.
 
 
 .. _CustomSelectors:
@@ -148,7 +146,7 @@
 
 .. autodocstring:: cubicweb.appobject::objectify_selector
 
-In other case, you can take a look at the following abstract base classes:
+In other cases, you can take a look at the following abstract base classes:
 
 .. autoclass:: cubicweb.selectors.ExpectedValueSelector
 .. autoclass:: cubicweb.selectors.EClassSelector
@@ -160,7 +158,7 @@
 
 .. autofunction:: cubicweb.selectors.lltrace
 
-.. Note::
+.. note::
   Selectors __call__ should *always* return a positive integer, and shall never
   return `None`.
 
@@ -254,11 +252,14 @@
 
     .. sourcecode:: python
 
-        >>> with traced_selection( ('oid1', 'oid2') ):
+        >>> with traced_selection( ('regid1', 'regid2') ):
         ...     # some code in which you want to debug selectors
-        ...     # for objects with id 'oid1' and 'oid2'
+        ...     # for objects with __regid__ 'regid1' and 'regid2'
 
+    A potentially usefull point to set up such a tracing function is
+    the `cubicweb.vregistry.Registry.select` method body.
     """
+
     def __init__(self, traced='all'):
         self.traced = traced