--- a/doc/book/en/development/datamodel/definition.rst	Wed Feb 03 16:19:12 2010 +0100
+++ b/doc/book/en/development/datamodel/definition.rst	Thu Feb 04 11:30:47 2010 +0100
@@ -1,4 +1,4 @@
-.. -*- coding: utf-8 -*-
+ .. -*- coding: utf-8 -*-
 
 Yams *schema*
 -------------
@@ -172,17 +172,17 @@
 * we associate rights at the enttities/relations schema level
 * for each entity, we distinguish four kind of permissions: read,
   add, update and delete
-* for each relation, we distinguish three king of permissions: read,
+* for each relation, we distinguish three kinds of permissions: read,
   add and delete (we can not modify a relation)
 * the basic groups are: Administrators, Users and Guests
-* by default, users belongs to the group Users
-* there is a virtual group called `Owners users` to which we
+* by default, users belong to the group Users
+* there is a virtual group called `Owners` to which we
   can associate only deletion and update permissions
-* we can not add users to the `Owners users` group, they are
-  implicetely added to it according to the context of the objects
+* we can not add users to the `Owners` group, they are
+  implicitly added to it according to the context of the objects
   they own
-* the permissions of this group are only be checked on update/deletion
-  actions if all the other groups the user belongs does not provide
+* the permissions of this group are only checked on update/deletion
+  actions if all the other groups the user belongs to does not provide
   those permissions
 
 Setting permissions is done with the attribute `permissions` of entities and
@@ -196,8 +196,8 @@
 
 For each access type, a tuple indicates the name of the authorized groups and/or
 one or multiple RQL expressions to satisfy to grant access. The access is
-provided once the user is in the listed groups or one of the RQL condition is
-satisfied.
+provided if the user is in one of the listed groups or one of if the RQL condition
+is satisfied.
 
 The standard user groups
 ````````````````````````
@@ -217,7 +217,7 @@
 
 
 Use of RQL expression for write permissions
-```````````````````````````````````````````
+ ```````````````````````````````````````````
 It is possible to define RQL expression to provide update permission
 (`add`, `delete` and `update`) on relation and entity types.
 
@@ -233,7 +233,7 @@
 
 * it is possible to use, in this expression, a special relation
   "has_<ACTION>_permission" where the subject is the user and the
-  object is a any variable, meaning that the user needs to have
+  object is any variable, meaning that the user needs to have
   permission to execute the action <ACTION> on the entities related
   to this variable
 
@@ -257,13 +257,14 @@
 
 :Note on the use of RQL expression for `add` permission:
 
-  Potentially, the use of an RQL expression to add an entity or a relation
-  can cause problems for the user interface, because if the expression uses
-  the entity or the relation to create, then we are not able to verify the
-  permissions before we actually add the entity (please note that this is
-  not a problem for the RQL server at all, because the permissions checks are
-  done after the creation). In such case, the permission check methods
-  (check_perm, has_perm) can indicate that the user is not allowed to create
+  Potentially, the use of an RQL expression to add an entity or a
+  relation can cause problems for the user interface, because if the
+  expression uses the entity or the relation to create, then we are
+  not able to verify the permissions before we actually add the entity
+  (please note that this is not a problem for the RQL server at all,
+  because the permissions checks are done after the creation). In such
+  case, the permission check methods (CubicWebEntitySchema.check_perm
+  and has_perm) can indicate that the user is not allowed to create
   this entity but can obtain the permission.
   To compensate this problem, it is usually necessary, for such case,
   to use an action that reflects the schema permissions but which enables
@@ -379,13 +380,12 @@
 Definition of permissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In addition to that the entity type `CWPermission` from the standard library
-allow to build very complex and dynamic security architecture. The schema of
+The entity type `CWPermission` from the standard library
+allows to build very complex and dynamic security architectures. The schema of
 this entity type is as follow : ::
 
     class CWPermission(MetaEntityType):
-	"""entity type that may be used to construct some advanced security configuration
-	"""
+	"""entity type that may be used to construct some advanced security configuration"""
 	name = String(required=True, indexed=True, internationalizable=True, maxsize=100)
 	require_group = SubjectRelation('CWGroup', cardinality='+*',
 					description=_('groups to which the permission is granted'))
@@ -419,6 +419,9 @@
     class version_of(RelationType):
 	"""link a version to its project. A version is necessarily linked to one and only one project.
 	"""
+        subject = 'Version'
+        object = 'Project'
+        cardinality = '?*'
 	permissions = {'read':   ('managers', 'users', 'guests',),
 		       'delete': ('managers', ),
 		       'add':    ('managers', 'logilab',