# HG changeset patch
# User Sandrine Ribeau <sandrine.ribeau@logilab.fr>
# Date 1230066923 28800
# Node ID 451a74c5652ce5a3f63a3d42a8896d7af309a92e
# Parent  ce29a9498c837abfd3f9162acf230eb8fd703723
[doc] Renaming for data model thematic.

diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B0-data-model.en.txt
--- a/doc/book/en/B0-data-model.en.txt	Tue Dec 23 13:04:24 2008 -0800
+++ b/doc/book/en/B0-data-model.en.txt	Tue Dec 23 13:15:23 2008 -0800
@@ -6,8 +6,8 @@
 .. toctree::
    :maxdepth: 1
 
-   B020-define-schema.en.txt
-   B040-define-workflows.en.txt
-   B050-data-as-objects.en.txt
-   B120-migration.en.txt
+   B010-define-schema.en.txt
+   B020-define-workflows.en.txt
+   B030-data-as-objects.en.txt
+   B040-migration.en.txt
 
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B010-define-schema.en.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B010-define-schema.en.txt	Tue Dec 23 13:15:23 2008 -0800
@@ -0,0 +1,22 @@
+.. -*- coding: utf-8 -*-
+
+Data model definition (*schema*)
+================================
+
+The schema is the core piece of a `CubicWeb` application as it defines
+the data model handled. It is based on entities types already defined
+in the `CubicWeb` standard library and others, more specific, we would 
+expect to find in one or more Python files under the `schema` directory.
+
+At this point, it is important to make clear the difference between
+relation type and relation definition: a relation type is only a relation
+name with potentially other additionnal properties (see XXXX), whereas a 
+relation definition is a complete triplet 
+"<subject entity type> <relation type> <object entity type>". 
+A relation type could have been implied if none is related to a 
+relation definition of the schema.
+
+
+.. include:: B021-schema-stdlib.en.txt
+.. include:: B022-schema-definition.en.txt
+
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B020-define-schema.en.txt
--- a/doc/book/en/B020-define-schema.en.txt	Tue Dec 23 13:04:24 2008 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,22 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-Data model definition (*schema*)
-================================
-
-The schema is the core piece of a `CubicWeb` application as it defines
-the data model handled. It is based on entities types already defined
-in the `CubicWeb` standard library and others, more specific, we would 
-expect to find in one or more Python files under the `schema` directory.
-
-At this point, it is important to make clear the difference between
-relation type and relation definition: a relation type is only a relation
-name with potentially other additionnal properties (see XXXX), whereas a 
-relation definition is a complete triplet 
-"<subject entity type> <relation type> <object entity type>". 
-A relation type could have been implied if none is related to a 
-relation definition of the schema.
-
-
-.. include:: B021-schema-stdlib.en.txt
-.. include:: B022-schema-definition.en.txt
-
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B020-define-workflows.en.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B020-define-workflows.en.txt	Tue Dec 23 13:15:23 2008 -0800
@@ -0,0 +1,161 @@
+.. -*- coding: utf-8 -*-
+
+.. _Workflow:
+
+Workflow definition
+===================
+
+General
+-------
+
+A workflow can be defined in a `CubicWeb` application thanks to the system 
+entities ``State`` and ``Transition``. Those are defined within all 
+`CubicWeb` application and can be set-up through the main administrator interface.
+
+Once your schema is defined, you can start creating the set of states and
+the required transitions for your applications entities.
+
+You first need to define the states and then the transitions between those
+to complete your workflow.
+
+A ``State`` defines the status of an entity. While creating a new state, 
+you will be first given the option to select the entity type the state
+can be applied to. By choosing ``Apply``, a new section will be displayed
+in the editing screen to enable you to add relation to the state you are
+creating.
+
+A ``Transition`` is also based on an entity type it can be applied to.
+By choosing ``Apply``, a new section will be displayed in the editing 
+screen to enable you to add relation to the transition you are
+creating.
+
+At the transition level you will also define the group of user which can
+aplly this transition to an object.
+
+
+Example of a simple workflow
+----------------------------
+
+Please see the tutorial to view and example of a simple workflow.
+
+
+[Create a simple workflow for BlogDemo, to have a moderator approve new blog 
+entry to be published. This implies, specify a dedicated group of blog
+moderator as well as hide the view of a blog entry to the user until
+it reaches the state published]
+
+Set-up a workflow
+-----------------
+
+Before starting, make sure you refresh your mind by reading [link to
+definition_workflow chapter].
+
+We want to create a workflow to control the quality of the BlogEntry 
+submitted on your application. When a BlogEntry is created by a user
+its state should be `submitted`. To be visible to all, it needs to
+be in the state `published`. To move from `submitted` to `published`
+we need a transition that we can name `approve_blogentry`.
+
+We do not want every user to be allowed to change the state of a 
+BlogEntry. We need to define a group of user, `moderators`, and 
+this group will have appropriate permissions to approve BlogEntry
+to be published and visible to all.
+
+There are two ways to create a workflow, form the user interface,
+and also by defining it in ``migration/postcreate.py``. This script
+is executed each time a new ``./bin/laxctl db-init`` is done. 
+If you create the states and transitions through the user interface
+this means that next time you will need to initialize the database
+you will have to re-create all the entities. 
+We strongly recommand you create the workflow in ``migration\postcreate.py``
+and we will now show you how.
+The user interface would only be a reference for you to view the states 
+and transitions but is not the appropriate interface to define your
+application workflow.
+
+Update the schema
+~~~~~~~~~~~~~~~~~
+To enable a BlogEntry to have a State, we have to define a relation
+``in_state`` in the schema of BlogEntry. Please do as follows, add
+the line ``in_state (...)``::
+
+  class BlogEntry(EntityType):
+      title = String(maxsize=100, required=True)
+      publish_date = Date(default='TODAY')
+      text_format = String(meta=True, internationalizable=True, maxsize=50,
+                           default='text/rest', constraints=[format_constraint])
+      text = String(fulltextindexed=True)
+      category = String(vocabulary=('important','business'))
+      entry_of = SubjectRelation('Blog', cardinality='?*')
+      in_state = SubjectRelation('State', cardinality='1*')
+
+As you updated the schema, you will have re-execute ``./bin/laxctl db-init``
+to initialize the database and migrate your existing entities.
+[WRITE ABOUT MIGRATION]
+
+Create states, transitions and group permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the time the ``postcreate.py`` script is executed, several methods
+can be used. They are all defined in the ``class ServerMigrationHelper``.
+We will only discuss the method we use to create a wrokflow here.
+
+To define our workflow for BlogDemo, please add the following lines
+to ``migration/postcreate.py``::
+  
+  _ = unicode
+
+  moderators      = add_entity('EGroup', name=u"moderators")
+
+  submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
+  published = add_state(_('published'), 'BlogEntry')
+
+  add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
+
+  checkpoint()
+
+.. note::
+  Do not forget to add the `_()` in front of all states and transitions names while creating
+  a workflow so that they will be identified by the i18n catalog scripts.
+
+``add_entity`` is used here to define the new group of users that we
+need to define the transitions, `moderators`.
+If this group required by the transition is not defined before the
+transition is created, it will not create the relation `transition 
+require the group moderator`.
+
+``add_state`` expects as the first argument the name of the state you are
+willing to create, then the entity type on which the state can be applied, 
+and an optionnal argument to set if the state is the initial state
+of the entity type or not.
+
+``add_transition`` expects as the first argument the name of the 
+transition, then the entity type on which we can apply the transition,
+then the list of possible initial states from which the transition
+can be applied, the target state of the transition, and the permissions
+(e.g. list of the groups of users who can apply the transition, the user
+needs to belong to at least one of the listed group).
+
+
+We could have also added a RQL condition in addition to a group to 
+which the user should belong to. 
+
+If we use both RQL condition and group, the two must be satisfied 
+for the user to be allowed to apply the transition.
+
+If we use a RQL condition on a transition, we can use the following 
+variables:
+
+* `%(eid)s`, object's eid
+* `%(ueid)s`, user executing the query eid
+* `%(seid)s`, the object's current state eid
+
+
+.. image:: images/lax-book.03-transitions-view.en.png
+
+You can now notice that in the actions box of a BlogEntry, the state
+is now listed as well as the possible transitions from this state
+defined by the workflow. This transition, as defined in the workflow,
+will only being displayed for the users belonging to the group
+moderators of managers.
+
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B030-data-as-objects.en.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B030-data-as-objects.en.txt	Tue Dec 23 13:15:23 2008 -0800
@@ -0,0 +1,144 @@
+.. -*- coding: utf-8 -*-
+
+
+Stored data handling
+====================
+
+Classes `Entity` and `AnyEntity`
+--------------------------------
+
+To provide a specific behavior for each entity, we just need to define
+a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have
+to defined those classes in a module of `entites` package of an application
+so that it will be available on both server and client side.
+
+The class `AnyEntity` is loaded dynamically from the class `Entity` 
+(`cubciweb.common.entity`). We define a sub-class to add methods or to
+specialize the handling of a given entity type
+
+Descriptors are added when classes are registered in order to initialize the class
+according to its schema:
+
+* we can access the defined attributes in the schema thanks the attributes of
+  the same name on instances (typed value)
+
+* we can access the defined relations in the schema thanks to the relations of
+  the same name on instances (entities instances list)
+
+The methods defined for `AnyEntity` or `Entity` are the following ones:
+
+* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the
+  creation process)
+        
+* `check_perm(action)`, checks if the user has the permission to execcute the
+  requested action on the entity
+
+:Formatting and output generation:
+
+  * `view(vid, **kwargs)`, apply the given view to the entity
+
+  * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view
+    of an entity
+    
+  * `rest_path()`, returns a relative REST URL to get the entity
+
+  * `format(attr)`, returns the format (MIME type) of the field given un parameter
+
+  * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 
+    returns a string enabling the display of an attribute value in a given format
+    (the value is automatically recovered if necessarry)
+
+  * `display_name(form='')`, returns a string to display the entity type by 
+    specifying the preferred form (`plural` for a plural form)
+
+:Data handling:
+
+  * `as_rset()`, converts the entity into an equivalent result set simulating the 
+     request `Any X WHERE X eid _eid_`
+
+  * `complete(skip_bytes=True)`, executes a request that recovers in one time
+    all the missing attributes of an entity
+
+  * `get_value(name)`, returns the value associated to the attribute name given
+    in parameter
+
+  * `related(rtype, x='subject', limit=None, entities=False)`, returns a list
+    of entities related to the current entity by the relation given in parameter
+
+  * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set
+    corresponding to the entities not related to the current entity by the
+    relation given in parameter and satisfying its constraints
+
+  * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
+    values given named parameters
+
+  * `copy_relations(ceid)`, copies the relations of the entities having the eid
+    given in the parameters on the current entity
+
+  * `last_modified(view)`, returns the date the object has been modified
+    (used by HTTP cache handling)
+
+  * `delete()` allows to delete the entity
+  
+:Standard meta-data (Dublin Core):
+
+  * `dc_title()`, returns a unicode string corresponding to the meta-data
+    `Title` (used by default the first attribute non-meta of the entity
+    schema)
+
+  * `dc_long_title()`, same as dc_title but can return a more
+    detailled title
+
+  * `dc_description(format='text/plain')`, returns a unicode string 
+    corresponding to the meta-data `Description` (look for a description
+    attribute by default)
+
+  * `dc_authors()`, returns a unicode string corresponding to the meta-data 
+    `Authors` (owners by default)
+
+  * `dc_date(date_format=None)`, returns a unicode string corresponding to 
+    the meta-data `Date` (update date by default)
+            
+:Vocabulary control on relations:
+
+  * `vocabulary(rtype, x='subject', limit=None)`, called by the
+    editing views, it returns a list of couples (label, eid) of entities
+    that could be related to the entity by the relation `rtype`
+  * `subject_relation_vocabulary(rtype, limit=None)`, called internally 
+    by  `vocabulary` in the case of a subject relation
+  * `object_relation_vocabulary(rtype, limit=None)`, called internally 
+    by  `vocabulary` in the case of an object relation
+  * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
+    internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
+
+
+*rtags*
+-------
+
+*rtags* allows to specify certain behaviors of relations relative to a given
+entity type (see later). They are defined on the entity class by the attribute
+`rtags` which is a dictionnary with as its keys the triplet ::
+
+  <relation type>, <target entity type>, <context position ("subject" ou "object")>
+
+and as the values a `set` or a tuple of markers defining the properties that
+apply to this relation.
+
+It is possible to simplify this dictionnary:
+
+* if we want to specifiy a single marker, it is not necessarry to
+  use a tuple as the value, the marker by itself (characters string)
+  is enough
+* if we only care about a single type of relation and not about the target
+  and the context position (or when this one is not ambigous), we can simply
+  use the name of the relation type as the key
+* if we want a marker to apply independently from the target entity type,
+  we have to use the string `*` as the target entity type
+
+
+Please note that this dictionnary is *treated at the time the class is created*.
+It is automatically merged with the parent class(es) (no need to copy the
+dictionnary from the parent class to modify it). Also, modify it after the 
+class is created will not have any effect...
+
+.. include:: B051-define-entities.en.txt
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B040-define-workflows.en.txt
--- a/doc/book/en/B040-define-workflows.en.txt	Tue Dec 23 13:04:24 2008 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,161 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _Workflow:
-
-Workflow definition
-===================
-
-General
--------
-
-A workflow can be defined in a `CubicWeb` application thanks to the system 
-entities ``State`` and ``Transition``. Those are defined within all 
-`CubicWeb` application and can be set-up through the main administrator interface.
-
-Once your schema is defined, you can start creating the set of states and
-the required transitions for your applications entities.
-
-You first need to define the states and then the transitions between those
-to complete your workflow.
-
-A ``State`` defines the status of an entity. While creating a new state, 
-you will be first given the option to select the entity type the state
-can be applied to. By choosing ``Apply``, a new section will be displayed
-in the editing screen to enable you to add relation to the state you are
-creating.
-
-A ``Transition`` is also based on an entity type it can be applied to.
-By choosing ``Apply``, a new section will be displayed in the editing 
-screen to enable you to add relation to the transition you are
-creating.
-
-At the transition level you will also define the group of user which can
-aplly this transition to an object.
-
-
-Example of a simple workflow
-----------------------------
-
-Please see the tutorial to view and example of a simple workflow.
-
-
-[Create a simple workflow for BlogDemo, to have a moderator approve new blog 
-entry to be published. This implies, specify a dedicated group of blog
-moderator as well as hide the view of a blog entry to the user until
-it reaches the state published]
-
-Set-up a workflow
------------------
-
-Before starting, make sure you refresh your mind by reading [link to
-definition_workflow chapter].
-
-We want to create a workflow to control the quality of the BlogEntry 
-submitted on your application. When a BlogEntry is created by a user
-its state should be `submitted`. To be visible to all, it needs to
-be in the state `published`. To move from `submitted` to `published`
-we need a transition that we can name `approve_blogentry`.
-
-We do not want every user to be allowed to change the state of a 
-BlogEntry. We need to define a group of user, `moderators`, and 
-this group will have appropriate permissions to approve BlogEntry
-to be published and visible to all.
-
-There are two ways to create a workflow, form the user interface,
-and also by defining it in ``migration/postcreate.py``. This script
-is executed each time a new ``./bin/laxctl db-init`` is done. 
-If you create the states and transitions through the user interface
-this means that next time you will need to initialize the database
-you will have to re-create all the entities. 
-We strongly recommand you create the workflow in ``migration\postcreate.py``
-and we will now show you how.
-The user interface would only be a reference for you to view the states 
-and transitions but is not the appropriate interface to define your
-application workflow.
-
-Update the schema
-~~~~~~~~~~~~~~~~~
-To enable a BlogEntry to have a State, we have to define a relation
-``in_state`` in the schema of BlogEntry. Please do as follows, add
-the line ``in_state (...)``::
-
-  class BlogEntry(EntityType):
-      title = String(maxsize=100, required=True)
-      publish_date = Date(default='TODAY')
-      text_format = String(meta=True, internationalizable=True, maxsize=50,
-                           default='text/rest', constraints=[format_constraint])
-      text = String(fulltextindexed=True)
-      category = String(vocabulary=('important','business'))
-      entry_of = SubjectRelation('Blog', cardinality='?*')
-      in_state = SubjectRelation('State', cardinality='1*')
-
-As you updated the schema, you will have re-execute ``./bin/laxctl db-init``
-to initialize the database and migrate your existing entities.
-[WRITE ABOUT MIGRATION]
-
-Create states, transitions and group permissions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-At the time the ``postcreate.py`` script is executed, several methods
-can be used. They are all defined in the ``class ServerMigrationHelper``.
-We will only discuss the method we use to create a wrokflow here.
-
-To define our workflow for BlogDemo, please add the following lines
-to ``migration/postcreate.py``::
-  
-  _ = unicode
-
-  moderators      = add_entity('EGroup', name=u"moderators")
-
-  submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
-  published = add_state(_('published'), 'BlogEntry')
-
-  add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
-
-  checkpoint()
-
-.. note::
-  Do not forget to add the `_()` in front of all states and transitions names while creating
-  a workflow so that they will be identified by the i18n catalog scripts.
-
-``add_entity`` is used here to define the new group of users that we
-need to define the transitions, `moderators`.
-If this group required by the transition is not defined before the
-transition is created, it will not create the relation `transition 
-require the group moderator`.
-
-``add_state`` expects as the first argument the name of the state you are
-willing to create, then the entity type on which the state can be applied, 
-and an optionnal argument to set if the state is the initial state
-of the entity type or not.
-
-``add_transition`` expects as the first argument the name of the 
-transition, then the entity type on which we can apply the transition,
-then the list of possible initial states from which the transition
-can be applied, the target state of the transition, and the permissions
-(e.g. list of the groups of users who can apply the transition, the user
-needs to belong to at least one of the listed group).
-
-
-We could have also added a RQL condition in addition to a group to 
-which the user should belong to. 
-
-If we use both RQL condition and group, the two must be satisfied 
-for the user to be allowed to apply the transition.
-
-If we use a RQL condition on a transition, we can use the following 
-variables:
-
-* `%(eid)s`, object's eid
-* `%(ueid)s`, user executing the query eid
-* `%(seid)s`, the object's current state eid
-
-
-.. image:: images/lax-book.03-transitions-view.en.png
-
-You can now notice that in the actions box of a BlogEntry, the state
-is now listed as well as the possible transitions from this state
-defined by the workflow. This transition, as defined in the workflow,
-will only being displayed for the users belonging to the group
-moderators of managers.
-
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B040-migration.en.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/B040-migration.en.txt	Tue Dec 23 13:15:23 2008 -0800
@@ -0,0 +1,211 @@
+.. -*- coding: utf-8 -*-
+
+.. _migration:
+
+Migration
+=========
+
+One of the main concept in `CubicWeb` is to create incremental applications
+and for this purpose multiple actions are provided to facilitate the improvement
+of an application and in particular changes applied to the data model
+without loosing existing data.
+
+The current version of an application model is provided in the file
+`__pkginfo__.py` as a tuple of 3 integers.
+
+Migration scripts management
+----------------------------
+
+Migration scripts needs to be located in the directory `migration` of your
+application and nammed accordingly:
+
+::
+
+  <version n° X.Y.Z>[_<description>]_<mode>.py
+
+in which : 
+
+* X.Y.Z is the model version number to which the script enable to migrate
+
+* *mode* (between the last "_" and the extension ".py") indicates which part
+  of the application (RQL server, web server) the script applies to in case
+  of distributed installation. Its value could be :
+
+  * `common`, applies to the RQL server as well as the web server and updates
+    files on the hard drive (configuration files migration for example).
+
+  * `web`, applies only to the web server and updates files on the hard drive
+
+  * `repository`, applies only to the RQL server and updates files on the
+    hard drive
+
+  * `Any`, applies only to the RQL server and updates data in the database
+    (schema and data migration for example)
+
+Again in the directory `migration`, the file `depends.map` allows to indicate
+that to migrate to a particular model version, you always have to first migrate
+to a particular `CubicWeb` version. This file can contains comments (lines
+starting by `#`) and a dependancy is listed as follows: ::
+  
+  <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z>
+
+For example: ::
+
+  0.12.0: 2.26.0
+  0.13.0: 2.27.0
+  # 0.14 works with 2.27 <= erudi <= 2.28 at least
+  0.15.0: 2.28.0
+
+Base context
+------------
+
+The following identifiers are pre-defined in the migration scripts:
+
+* `config`, instance configuration
+
+* `interactive_mode`, boolean indicating that the script is executed in
+  an intercative mode or not 
+
+* `appltemplversion`, application model version of the instance
+
+* `applerudiversion`, cubicweb instance version
+
+* `templversion`, installed application model version
+
+* `erudiversion`, installed cubicweb version
+
+* `confirm(question)`, function interrogating the user and returning true
+  if the user answers yes, false otherwise (always returns true when in a
+  non-interactive mode)
+
+* `_`, function fonction equivalent to `unicode` allowing to flag the strings
+  to internationalize in the migration scripts
+
+In the `repository` scripts, the following identifiers are also defined:
+
+* `checkpoint`, request confirming and executing a "commit" at checking point
+
+* `repo_schema`, instance persisting schema (e.g. instance schema of the
+  current migration)
+
+* `newschema`, installed schema on the file system (e.g. schema of 
+  the updated model and erudi)
+
+* `sqlcursor`, SQL cursor for very rare cases where it is really
+   necessary or beneficial to go through the sql
+
+* `repo`, repository object
+
+                        
+Schema migration
+----------------
+The following functions for schema migration are available in the `repository`
+scripts:
+
+* `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new
+  attribute to an existing entity type. If the attribute type is not specified, 
+  then it is extracted from the updated schema.
+        
+* `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an
+  existing entity type.
+
+* `rename_attribute(etype, oldname, newname, commit=True)`, rename an attribute
+            
+* `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type.
+  If `auto` is True, all the relations using this entity type and having a known
+  entity type on the other hand will automatically be added.
+
+* `drop_entity_type(etype, commit=True)`, removes an entity type and all the 
+  relations using it.
+
+* `rename_entity_type(oldname, newname, commit=True)`, renames an entity type
+            
+* `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation
+  type. If `addrdef` is True, all the relations definitions of this type will
+  be added.
+
+* `drop_relation_type(rtype, commit=True)`, removes a relation type and all the
+  definitions of this type.
+
+* `rename_relation(oldname, newname, commit=True)`, renames a relation.
+
+* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new
+  relation definition.
+
+* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes
+  a relation definition.
+
+* `synchronize_permissions(ertype, commit=True)`, synchronizes permissions on
+  an entity type or relation type.
+        
+* `synchronize_rschema(rtype, commit=True)`, synchronizes properties and permissions
+  on a relation type.
+                
+* `synchronize_eschema(etype, commit=True)`, synchronizes properties and persmissions
+  on an entity type.
+    
+* `synchronize_schema(commit=True)`, synchronizes the persisting schema with the
+  updated schema (but without adding or removing new entity types, relations types 
+  or even relations definitions).
+        
+* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes
+  properties of a relation definition by using the nammed parameters of the properties
+  to change.
+
+* `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the
+  relation <rtype> of entity type <etype>.
+
+* `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints
+  for the relation <rtype> of entity type <etype>.
+
+Data migration
+--------------
+The following functions for data migration are available in the `repository` scripts:
+
+* `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL
+  query, either to interrogate or update. A result set object is returned.  
+
+* `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given
+  type. The attributes and relations values are specified using the nammed and
+  positionned parameters.
+
+Workflow creation
+-----------------
+
+The following functions for workflow creation are available in the `repository`
+scripts:
+
+* `add_state(name, stateof, initial=False, commit=False, **kwargs)`, adds a new state
+  in the workflow.
+    
+* `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`, 
+  adds a new transition in the workflow.
+
+You can find more details about workflows in the chapter :ref:`Workflow` .
+
+Configuration migration
+-----------------------
+
+The following functions for configuration migration are available in all the
+scripts:
+
+* `option_renamed(oldname, newname)`, indicates that an option has been renammed
+
+* `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not
+  belong anymore to the same group.
+
+* `option_added(oldname, newname)`, indicates that an option has been added.
+
+* `option_removed(oldname, newname)`, indicates that an option has been deleted.
+
+
+Others migration functions
+--------------------------
+Those functions are only used for low level operations that could not be 
+accomplished otherwise or to repair damaged databases during interactive 
+session. They are available in the `repository` scripts:
+
+* `sqlexec(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query
+* `add_entity_type_table(etype, commit=True)`
+* `add_relation_type_table(rtype, commit=True)`
+* `uninline_relation(rtype, commit=True)`
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B050-data-as-objects.en.txt
--- a/doc/book/en/B050-data-as-objects.en.txt	Tue Dec 23 13:04:24 2008 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,144 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-
-Stored data handling
-====================
-
-Classes `Entity` and `AnyEntity`
---------------------------------
-
-To provide a specific behavior for each entity, we just need to define
-a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have
-to defined those classes in a module of `entites` package of an application
-so that it will be available on both server and client side.
-
-The class `AnyEntity` is loaded dynamically from the class `Entity` 
-(`cubciweb.common.entity`). We define a sub-class to add methods or to
-specialize the handling of a given entity type
-
-Descriptors are added when classes are registered in order to initialize the class
-according to its schema:
-
-* we can access the defined attributes in the schema thanks the attributes of
-  the same name on instances (typed value)
-
-* we can access the defined relations in the schema thanks to the relations of
-  the same name on instances (entities instances list)
-
-The methods defined for `AnyEntity` or `Entity` are the following ones:
-
-* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the
-  creation process)
-        
-* `check_perm(action)`, checks if the user has the permission to execcute the
-  requested action on the entity
-
-:Formatting and output generation:
-
-  * `view(vid, **kwargs)`, apply the given view to the entity
-
-  * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view
-    of an entity
-    
-  * `rest_path()`, returns a relative REST URL to get the entity
-
-  * `format(attr)`, returns the format (MIME type) of the field given un parameter
-
-  * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 
-    returns a string enabling the display of an attribute value in a given format
-    (the value is automatically recovered if necessarry)
-
-  * `display_name(form='')`, returns a string to display the entity type by 
-    specifying the preferred form (`plural` for a plural form)
-
-:Data handling:
-
-  * `as_rset()`, converts the entity into an equivalent result set simulating the 
-     request `Any X WHERE X eid _eid_`
-
-  * `complete(skip_bytes=True)`, executes a request that recovers in one time
-    all the missing attributes of an entity
-
-  * `get_value(name)`, returns the value associated to the attribute name given
-    in parameter
-
-  * `related(rtype, x='subject', limit=None, entities=False)`, returns a list
-    of entities related to the current entity by the relation given in parameter
-
-  * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set
-    corresponding to the entities not related to the current entity by the
-    relation given in parameter and satisfying its constraints
-
-  * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
-    values given named parameters
-
-  * `copy_relations(ceid)`, copies the relations of the entities having the eid
-    given in the parameters on the current entity
-
-  * `last_modified(view)`, returns the date the object has been modified
-    (used by HTTP cache handling)
-
-  * `delete()` allows to delete the entity
-  
-:Standard meta-data (Dublin Core):
-
-  * `dc_title()`, returns a unicode string corresponding to the meta-data
-    `Title` (used by default the first attribute non-meta of the entity
-    schema)
-
-  * `dc_long_title()`, same as dc_title but can return a more
-    detailled title
-
-  * `dc_description(format='text/plain')`, returns a unicode string 
-    corresponding to the meta-data `Description` (look for a description
-    attribute by default)
-
-  * `dc_authors()`, returns a unicode string corresponding to the meta-data 
-    `Authors` (owners by default)
-
-  * `dc_date(date_format=None)`, returns a unicode string corresponding to 
-    the meta-data `Date` (update date by default)
-            
-:Vocabulary control on relations:
-
-  * `vocabulary(rtype, x='subject', limit=None)`, called by the
-    editing views, it returns a list of couples (label, eid) of entities
-    that could be related to the entity by the relation `rtype`
-  * `subject_relation_vocabulary(rtype, limit=None)`, called internally 
-    by  `vocabulary` in the case of a subject relation
-  * `object_relation_vocabulary(rtype, limit=None)`, called internally 
-    by  `vocabulary` in the case of an object relation
-  * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
-    internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
-
-
-*rtags*
--------
-
-*rtags* allows to specify certain behaviors of relations relative to a given
-entity type (see later). They are defined on the entity class by the attribute
-`rtags` which is a dictionnary with as its keys the triplet ::
-
-  <relation type>, <target entity type>, <context position ("subject" ou "object")>
-
-and as the values a `set` or a tuple of markers defining the properties that
-apply to this relation.
-
-It is possible to simplify this dictionnary:
-
-* if we want to specifiy a single marker, it is not necessarry to
-  use a tuple as the value, the marker by itself (characters string)
-  is enough
-* if we only care about a single type of relation and not about the target
-  and the context position (or when this one is not ambigous), we can simply
-  use the name of the relation type as the key
-* if we want a marker to apply independently from the target entity type,
-  we have to use the string `*` as the target entity type
-
-
-Please note that this dictionnary is *treated at the time the class is created*.
-It is automatically merged with the parent class(es) (no need to copy the
-dictionnary from the parent class to modify it). Also, modify it after the 
-class is created will not have any effect...
-
-.. include:: B051-define-entities.en.txt
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B120-migration.en.txt
--- a/doc/book/en/B120-migration.en.txt	Tue Dec 23 13:04:24 2008 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,211 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-.. _migration:
-
-Migration
-=========
-
-One of the main concept in `CubicWeb` is to create incremental applications
-and for this purpose multiple actions are provided to facilitate the improvement
-of an application and in particular changes applied to the data model
-without loosing existing data.
-
-The current version of an application model is provided in the file
-`__pkginfo__.py` as a tuple of 3 integers.
-
-Migration scripts management
-----------------------------
-
-Migration scripts needs to be located in the directory `migration` of your
-application and nammed accordingly:
-
-::
-
-  <version n° X.Y.Z>[_<description>]_<mode>.py
-
-in which : 
-
-* X.Y.Z is the model version number to which the script enable to migrate
-
-* *mode* (between the last "_" and the extension ".py") indicates which part
-  of the application (RQL server, web server) the script applies to in case
-  of distributed installation. Its value could be :
-
-  * `common`, applies to the RQL server as well as the web server and updates
-    files on the hard drive (configuration files migration for example).
-
-  * `web`, applies only to the web server and updates files on the hard drive
-
-  * `repository`, applies only to the RQL server and updates files on the
-    hard drive
-
-  * `Any`, applies only to the RQL server and updates data in the database
-    (schema and data migration for example)
-
-Again in the directory `migration`, the file `depends.map` allows to indicate
-that to migrate to a particular model version, you always have to first migrate
-to a particular `CubicWeb` version. This file can contains comments (lines
-starting by `#`) and a dependancy is listed as follows: ::
-  
-  <model version n° X.Y.Z> : <cubicweb version n° X.Y.Z>
-
-For example: ::
-
-  0.12.0: 2.26.0
-  0.13.0: 2.27.0
-  # 0.14 works with 2.27 <= erudi <= 2.28 at least
-  0.15.0: 2.28.0
-
-Base context
-------------
-
-The following identifiers are pre-defined in the migration scripts:
-
-* `config`, instance configuration
-
-* `interactive_mode`, boolean indicating that the script is executed in
-  an intercative mode or not 
-
-* `appltemplversion`, application model version of the instance
-
-* `applerudiversion`, cubicweb instance version
-
-* `templversion`, installed application model version
-
-* `erudiversion`, installed cubicweb version
-
-* `confirm(question)`, function interrogating the user and returning true
-  if the user answers yes, false otherwise (always returns true when in a
-  non-interactive mode)
-
-* `_`, function fonction equivalent to `unicode` allowing to flag the strings
-  to internationalize in the migration scripts
-
-In the `repository` scripts, the following identifiers are also defined:
-
-* `checkpoint`, request confirming and executing a "commit" at checking point
-
-* `repo_schema`, instance persisting schema (e.g. instance schema of the
-  current migration)
-
-* `newschema`, installed schema on the file system (e.g. schema of 
-  the updated model and erudi)
-
-* `sqlcursor`, SQL cursor for very rare cases where it is really
-   necessary or beneficial to go through the sql
-
-* `repo`, repository object
-
-                        
-Schema migration
-----------------
-The following functions for schema migration are available in the `repository`
-scripts:
-
-* `add_attribute(etype, attrname, attrtype=None, commit=True)`, adds a new
-  attribute to an existing entity type. If the attribute type is not specified, 
-  then it is extracted from the updated schema.
-        
-* `drop_attribute(etype, attrname, commit=True)`, removes an attribute from an
-  existing entity type.
-
-* `rename_attribute(etype, oldname, newname, commit=True)`, rename an attribute
-            
-* `add_entity_type(etype, auto=True, commit=True)`, adds a new entity type.
-  If `auto` is True, all the relations using this entity type and having a known
-  entity type on the other hand will automatically be added.
-
-* `drop_entity_type(etype, commit=True)`, removes an entity type and all the 
-  relations using it.
-
-* `rename_entity_type(oldname, newname, commit=True)`, renames an entity type
-            
-* `add_relation_type(rtype, addrdef=True, commit=True)`, adds a new relation
-  type. If `addrdef` is True, all the relations definitions of this type will
-  be added.
-
-* `drop_relation_type(rtype, commit=True)`, removes a relation type and all the
-  definitions of this type.
-
-* `rename_relation(oldname, newname, commit=True)`, renames a relation.
-
-* `add_relation_definition(subjtype, rtype, objtype, commit=True)`, adds a new
-  relation definition.
-
-* `drop_relation_definition(subjtype, rtype, objtype, commit=True)`, removes
-  a relation definition.
-
-* `synchronize_permissions(ertype, commit=True)`, synchronizes permissions on
-  an entity type or relation type.
-        
-* `synchronize_rschema(rtype, commit=True)`, synchronizes properties and permissions
-  on a relation type.
-                
-* `synchronize_eschema(etype, commit=True)`, synchronizes properties and persmissions
-  on an entity type.
-    
-* `synchronize_schema(commit=True)`, synchronizes the persisting schema with the
-  updated schema (but without adding or removing new entity types, relations types 
-  or even relations definitions).
-        
-* `change_relation_props(subjtype, rtype, objtype, commit=True, **kwargs)`, changes
-  properties of a relation definition by using the nammed parameters of the properties
-  to change.
-
-* `set_widget(etype, rtype, widget, commit=True)`, changes the widget used for the
-  relation <rtype> of entity type <etype>.
-
-* `set_size_constraint(etype, rtype, size, commit=True)`, changes the size constraints
-  for the relation <rtype> of entity type <etype>.
-
-Data migration
---------------
-The following functions for data migration are available in the `repository` scripts:
-
-* `rql(rql, kwargs=None, cachekey=None, ask_confirm=True)`, executes an arbitrary RQL
-  query, either to interrogate or update. A result set object is returned.  
-
-* `add_entity(etype, *args, **kwargs)`, adds a nes entity type of the given
-  type. The attributes and relations values are specified using the nammed and
-  positionned parameters.
-
-Workflow creation
------------------
-
-The following functions for workflow creation are available in the `repository`
-scripts:
-
-* `add_state(name, stateof, initial=False, commit=False, **kwargs)`, adds a new state
-  in the workflow.
-    
-* `add_transition(name, transitionof, fromstates, tostate, requiredgroups=(), commit=False, **kwargs)`, 
-  adds a new transition in the workflow.
-
-You can find more details about workflows in the chapter :ref:`Workflow` .
-
-Configuration migration
------------------------
-
-The following functions for configuration migration are available in all the
-scripts:
-
-* `option_renamed(oldname, newname)`, indicates that an option has been renammed
-
-* `option_group_change(option, oldgroup, newgroup)`, indicates that an option does not
-  belong anymore to the same group.
-
-* `option_added(oldname, newname)`, indicates that an option has been added.
-
-* `option_removed(oldname, newname)`, indicates that an option has been deleted.
-
-
-Others migration functions
---------------------------
-Those functions are only used for low level operations that could not be 
-accomplished otherwise or to repair damaged databases during interactive 
-session. They are available in the `repository` scripts:
-
-* `sqlexec(sql, args=None, ask_confirm=True)`, executes an arbitrary SQL query
-* `add_entity_type_table(etype, commit=True)`
-* `add_relation_type_table(rtype, commit=True)`
-* `uninline_relation(rtype, commit=True)`
diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/BXXX-sessions.en.txt
--- a/doc/book/en/BXXX-sessions.en.txt	Tue Dec 23 13:04:24 2008 -0800
+++ b/doc/book/en/BXXX-sessions.en.txt	Tue Dec 23 13:15:23 2008 -0800
@@ -1,6 +1,6 @@
 .. -*- coding: utf-8 -*-
 
-sessions
+Sessions
 ========
 
 [WRITE ME]