--- a/doc/book/en/B0020-define-workflows.en.txt	Wed Apr 01 17:31:20 2009 +0200
+++ b/doc/book/en/B0020-define-workflows.en.txt	Wed Apr 01 19:39:11 2009 +0200
@@ -5,43 +5,22 @@
 Workflow definition
 ===================
 
+[TODO :  All this is too obscure and often not very understandable...]
+
 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.
-
+[XXX define what a "Workflow" is: states, transitions, transition graph ]
 
 Example of a simple workflow
 ----------------------------
 
-Please see the tutorial to view and example of a simple workflow.
+Please see the tutorial to view an 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
+entry to be published. This implies specifying a dedicated group of blog
+moderator as well as hiding the view of a blog entry to the user until
 it reaches the state published]
 
 Set-up a workflow
@@ -49,31 +28,24 @@
 
 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.
+its state should be `submitted`. To be visible to all, it has to
+be in the state `published`. To move it from `submitted` to `published`,
+we need a transition that we can call `approve_blogentry`.
 
-There are two ways to create a workflow, form the user interface,
-and also by defining it in ``migration/postcreate.py``. 
+A BlogEntry state should not be modifiable by every user.
+So we have to define a group of users, `moderators`, and 
+this group will have appropriate permissions to publish a BlogEntry.
+
+There are two ways to create a workflow: from the user interface,
+or by defining it in ``migration/postcreate.py``. 
 This script is executed each time a new ``cubicweb-ctl 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.
+We strongly recommand to create the workflow in ``migration/postcreate.py``
+and we will now show you how. Read `Under the hood`_ to understand why.
 
 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
+If we want a State for our BlogEntry, we have to define a relation
+``in_state`` in the schema of BlogEntry. So we add
 the line ``in_state (...)``::
 
   class BlogEntry(EntityType):
@@ -86,59 +58,64 @@
       entry_of = SubjectRelation('Blog', cardinality='?*')
       in_state = SubjectRelation('State', cardinality='1*')
 
-As you updated the schema, you will have re-execute ``cubicweb-ctl db-init``
+As you updated the schema, you have to re-execute ``cubicweb-ctl 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.
+The ``postcreate.py`` script is executed in a special environment, adding
+several `CubicWeb` primitives that can be used.
+They are all defined in the ``class ServerMigrationHelper``.
+We will only discuss the methods we use to create a workflow in this example.
 
 To define our workflow for BlogDemo, please add the following lines
 to ``migration/postcreate.py``::
   
   _ = unicode
 
-  moderators      = add_entity('EGroup', name=u"moderators")
+  moderators = add_entity('EGroup', name=u"moderators")
+
+This adds the `moderators` user group.
+
+::
 
   submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
   published = add_state(_('published'), 'BlogEntry')
 
+``add_state`` expects as first argument the name of the state you want
+to create, then the entity type on which the state can be applied,
+and an optional argument to say if it is supposed to be the initial state
+of the entity type.
+
+::
+
   add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
 
+
+``add_transition`` expects 
+
+  * as the first argument the name of the
+    transition, then the entity type on which the transition can be applied,
+  * then the list of states on which the transition can be trigged,
+  * the target state of the transition, 
+  * and the permissions
+    (e.g. a list of user groups who can apply the transition; the user
+    has to belong to at least one of the listed group to perform the action).
+
+::
+
   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.
+In addition to the user group condition, we could have added a RQL condition. 
+In this case, the user can only perform the action if 
+the two conditions are satisfied. 
 
 If we use a RQL condition on a transition, we can use the following 
 variables:
@@ -150,8 +127,40 @@
 
 .. 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.
+You can notice that in the action box of a BlogEntry, the state
+is now listed as well as the possible transitions defined by the workflow.
+The transitions will only be displayed for users having the right permissions.
+In our example, the transition `approve_blogentry` will only be displayed 
+for the users belonging to the group `moderators` or `managers`.
+
+
+Under the hood
+~~~~~~~~~~~~~~
+
+A workflow is a collection of entities of type ``State`` and of type ``Transition``
+which are standard `CubicWeb` entity types.
+For instance, the following lines::
+
+  submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
+  published = add_state(_('published'), 'BlogEntry')
+
+will create two entities of type ``State``, one with name 'submitted', and the other
+with name 'published'. Whereas::
+
+  add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
+ 
+will create an entity of type ``Transition`` with name 'approve_blogentry' which will
+be linked to the ``State`` entities created before.
+As a consequence, we could use the administration interface to do these operations.
+But it is not recommanded because it will be uselessly complicated
+and will be only local to your instance.
+
+
+Indeed, if you create the states and transitions through the user interface,
+next time you initialize the database
+you will have to re-create all the entities. 
+The user interface should only be a reference for you to view the states 
+and transitions, but is not the appropriate interface to define your
+application workflow.
+
+