--- a/doc/book/en/A02a-create-cube.en.txt	Tue Dec 23 15:42:01 2008 +0100
+++ b/doc/book/en/A02a-create-cube.en.txt	Tue Dec 23 10:43:51 2008 -0800
@@ -60,6 +60,10 @@
   |
   `-- views.py
 
+.. note::
+  You will find a more detailled description of the `cube` concept in
+  :ref:`cubesConcepts`.
+
 .. _DefineDataModel:
 
 Define your data model
@@ -220,6 +224,12 @@
 Define your entities views
 --------------------------
 
+Each entity defined in a model inherits defaults views allowing
+different rendering of the data. You can redefine each of them
+according to your needs and preferences. If you feel like it then
+you have to know how a view is defined.
+
+
 The views selection principle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -230,6 +240,8 @@
   
   - a filter to select the resulsets it can be applied to
 
+A view has a set of methods complying
+with the `View` class interface (`cubicweb.common.view`).
 
 `CubicWeb` provides a lot of standard views for the type
 `EntityView`, for a complete list, you

--- a/doc/book/en/A02b-components.en.txt	Tue Dec 23 15:42:01 2008 +0100
+++ b/doc/book/en/A02b-components.en.txt	Tue Dec 23 10:43:51 2008 -0800
@@ -5,24 +5,11 @@
 Cubes
 -----
 
-What is a cube ?
-~~~~~~~~~~~~~~~~
-
-A cube is a model grouping one or more entity types and/or views associated
-in order to provide a specific feature or even a complete application using
-others cubes.
-
-You can decide to write your own set of cubes if you wish to re-use the 
-entity types you develop. Lots of cubes are available from the `CubicWeb
-Forge`_ under a free software license.
-
-.. _`CubicWeb Forge`: http://www.cubicweb.org/project/
-
 Standard library
 ~~~~~~~~~~~~~~~~
 
-A library of standard cubes is part of the `CubicWeb` release (look at the
-output of ``cubicweb-ctl list``). Cubes provide entities and views.
+A library of standard cubes are available from `CubicWeb Forge`_
+Cubes provide entities and views.
 
 The available application entities are:
 
@@ -59,9 +46,11 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To import a cube in your application just change the line in the
-``app.conf`` file. For example::
+``__pkginfo__.py`` file and verify that the cube you are planning
+to use is listed by the command ``cubicweb-ctl list``.
+For example::
 
-    included-yams-cubes=comment
+    __use__ = ('comment',)
 
 will make the ``Comment`` entity available in your ``BlogDemo``
 application.
@@ -74,75 +63,19 @@
 
 to the definition of a ``BlogEntry`` will be enough.
 
-Clear the datastore and restart.
-
-Cube structure
-~~~~~~~~~~~~~~
-
-A complex  cube is structured as follows:
-::
+Synchronize the data model
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  mycube/
-  |
-  |-- schema.py
-  |
-  |-- entities/
-  |
-  |-- sobjects/
-  |
-  |-- views/
-  |
-  |-- test/
-  |
-  |-- i18n/
-  |
-  |-- data/
-  |
-  |-- migration/
-  | |- postcreate.py
-  | \- depends.map
-  |
-  |-- debian/
-  |
-  \-- __pkginfo__.py
-
-We can also define simple Python module instead of directories (packages), for example:
+Once you modified your data model, you need to synchronize the
+database with your model. For this purpose, `CubicWeb` provides
+a very usefull command ``cubicweb-ctl shell blogdemo`` which
+launches an interactive migration Python shell. (see 
+:ref:`cubicweb-ctl-shell` for more details))
+As you modified a relation from the `BlogEntry` schema,
+run the following command:
 ::
 
-  mycube/
-  |
-  |-- entities.py
-  |-- hooks.py
-  \-- views.py
-
-
-where:
-
-* ``schema`` contains the definition of the schema (server side only)
-* ``entities`` contains entities definition (server side and web interface)
-* ``sobjects`` contains hooks and/or notification views (server side only)
-* ``views`` contains the web interface components (web interface only)
-* ``test`` contains tests related to the application (not installed)
-* ``i18n`` contains messages catalogs for supported languages (server side and
-  web interface)
-* ``data`` contains data files for static content (images, css, javascripts)
-  ...(web interface only)
-* ``migration`` contains initialization file for new instances (``postcreate.py``)
-  and a file containing dependencies of the component depending on the version
-  (``depends.map``)
-* ``debian`` contains all the files managing debian packaging (you will find
-  the usual files ``control``, ``rules``, ``changelog``... not installed)
-* file ``__pkginfo__.py`` provides component meta-data, especially the distribution
-  and the current version(server side and web interface) or sub-components used by
-  the component.
- 
-At least you should have:
-
-* the file ``__pkginfo__.py``
-* schema definition
-
-[WRITE ME]
-
-* explain the cube architecture
-
-* add comments to the blog by importing the comments cube
+  synchronize_rschema('BlogEntry')
+  
+You can now start your application and add comments to each 
+`BlogEntry`.

--- a/doc/book/en/A02c-maintemplate.en.txt	Tue Dec 23 15:42:01 2008 +0100
+++ b/doc/book/en/A02c-maintemplate.en.txt	Tue Dec 23 10:43:51 2008 -0800
@@ -1,22 +1,37 @@
 .. -*- coding: utf-8 -*-
 
-Views & Templates
------------------
+Templates
+---------
 
-Look at ``lax/skel/ginco/web/views/basetemplates.py`` and you will
+Look at ``cubicweb/web/views/basetemplates.py`` and you will
 find the base templates used to generate HTML for your application.
 
 A page is composed as indicated on the schema below:
 
 .. image:: images/lax-book.06-main-template-layout.en.png
 
-In this section we will go through a couple of the primary templates
-you must be interested in, that is to say, the HTMLPageHeader,
-the HTMLPageFooter and the TheMainTemplate.
+In this section we will demonstrate a change in one of the main
+interesting template from the three you will look for, 
+that is to say, the HTMLPageHeader, the HTMLPageFooter 
+and the TheMainTemplate.
 
 
-HTMLPageHeader
-~~~~~~~~~~~~~~~
+Customize a template
+~~~~~~~~~~~~~~~~~~~~
+
+Based on the diagram below, each template can be overriden
+by your customized template. To do so, we recommand you create
+a Python module ``blog.views.templates`` to keep it organized.
+In this module you will have to import the parent class you are
+interested as follows: ::
+  
+  from cubicweb.web.views.basetemplates import HTMLPageHeader, \
+                                    HTMLPageFooter, TheMainTemplate
+
+and then create your sub-class::
+
+  class MyBlogHTMLPageHeader(HTMLPageHeader):
+      ...  
 
 Customize header
 `````````````````
@@ -24,14 +39,12 @@
 Let's now move the search box in the header and remove the login form
 from the header. We'll show how to move it to the left column of the application.
 
-Let's say we do not want anymore the login menu to be in the header, but we 
-prefer it to be in the left column just below the logo. As the left column is
-rendered by ``TheMainTemplate``, we will show how to do it in TheMainTemplate_. 
+Let's say we do not want anymore the login menu to be in the header
 
 First, to remove the login menu, we just need to comment out the display of the
-login component such as follows: ::
+login graphic component such as follows: ::
 
-  class MyHTMLPageHeader(HTMLPageHeader):
+  class MyBlogHTMLPageHeader(HTMLPageHeader):
     
       def main_header(self, view):
           """build the top menu with authentification info and the rql box"""
@@ -70,66 +83,8 @@
 
 .. image:: images/lax-book.06-header-no-login.en.png
 
-Let's now move the search box in the top-right header area. To do so, we will
-first create a method to get the search box display and insert it in the header
-table.
-
-::
-
- from ginco.web.views.basetemplates import HTMLPageHeader
- class MyHTMLPageHeader(HTMLPageHeader):
-    def main_header(self, view):
-        """build the top menu with authentification info and the rql box"""
-        self.w(u'<table id="header"><tr>\n')
-        self.w(u'<td id="firstcolumn">')
-        self.vreg.select_component('logo', self.req, self.rset).dispatch(w=self.w)
-        self.w(u'</td>\n')
-        # appliname and breadcrumbs
-        self.w(u'<td id="headtext">')
-        comp = self.vreg.select_component('appliname', self.req, self.rset)
-        if comp and comp.propval('visible'):
-            comp.dispatch(w=self.w)
-        comp = self.vreg.select_component('breadcrumbs', self.req, self.rset, view=view)
-        if comp and comp.propval('visible'):
-            comp.dispatch(w=self.w, view=view)
-        self.w(u'</td>')
-        
-        # logged user and help
-        #self.w(u'<td>\n')
-        #comp = self.vreg.select_component('loggeduserlink', self.req, self.rset)
-        #comp.dispatch(w=self.w)
-        #self.w(u'</td><td>')
-        
-        # search box
-        self.w(u'<td>')
-        self.get_searchbox(view, 'left')
-        self.w(u'</td>')
-
-        self.w(u'<td>')
-        helpcomp = self.vreg.select_component('help', self.req, self.rset)
-        if helpcomp: # may not be available if Card is not defined in the schema
-            helpcomp.dispatch(w=self.w)
-        self.w(u'</td>')
-        # lastcolumn
-        self.w(u'<td id="lastcolumn">')
-        self.w(u'</td>\n')
-        self.w(u'</tr></table>\n')
-        self.template('logform', rset=self.rset, id='popupLoginBox', klass='hidden',
-                      title=False, message=False)
-
-    def get_searchbox(self, view, context):
-        boxes = list(self.vreg.possible_vobjects('boxes', self.req, self.rset,
-                                                 view=view, context=context))
-        if boxes:
-            for box in boxes:
-                if box.id == 'search_box':
-                    box.dispatch(w=self.w, view=view)
-
- 
-
-
-HTMLPageFooter
-~~~~~~~~~~~~~~
+Customize footer
+````````````````
 
 If you want to change the footer for example, look
 for HTMLPageFooter and override it in your views file as in: 
@@ -147,7 +102,7 @@
 
 
 TheMainTemplate
-~~~~~~~~~~~~~~~
+```````````````
 
 .. _TheMainTemplate:
 
@@ -157,34 +112,32 @@
 
 TheMainTemplate is responsible for the general layout of the entire application. 
 It defines the template of ``id = main`` that is used by the application. Is 
-also defined in ``ginco/web/views/basetemplates.py`` another template that can
+also defined in ``cubicweb/web/views/basetemplates.py`` another template that can
 be used based on TheMainTemplate called SimpleMainTemplate which does not have 
 a top section.
 
 .. image:: images/lax-book.06-simple-main-template.en.png
 
+XXX
+[WRITE ME]
+
+* customize MainTemplate and show that everything in the user
+  interface can be changed
+* Add login menu in left column ?
+
 CSS changes
 ~~~~~~~~~~~
 
 We cannot modify the order in which the application is reading the CSS. In
 the case we want to create new CSS style, the best is to define it a in a new
-CSS located under ``myapp/data/``.
+CSS located under ``myapp/data/`` and use those new styles while writing
+customized views and templates.
 
 If you want to modify an existing CSS styling property, you will have to use
 ``!important`` declaration to override the existing property. The application
 apply a higher priority on the default CSS and you can not change that. 
 Customized CSS will not be read first.
 
-[TODO]
-Add login menu in left column
 
 
-[WRITE ME]
 
-* customize MainTemplate and show that everything in the user
-  interface can be changed
-
-[TODO]
-Rajouter une section pour definir la terminologie utilisee.
-Dans ginco-doc rajouter une section pour cubicweb-ctl shell ou
-on liste les commandes dispos.

--- a/doc/book/en/A03a-concepts.en.txt	Tue Dec 23 15:42:01 2008 +0100
+++ b/doc/book/en/A03a-concepts.en.txt	Tue Dec 23 10:43:51 2008 -0800
@@ -341,9 +341,28 @@
           def f(self, arg1):
               super(Truc, self).f(arg1)
 
+.. _cubesConcepts:
+
+Cubes
+~~~~~
+
+What is a cube ?
+````````````````
+
+A cube is a model grouping one or more entity types and/or views associated
+in order to provide a specific feature or even a complete application using
+others cubes.
+
+You can decide to write your own set of cubes if you wish to re-use the 
+entity types you develop. Lots of cubes are available from the `CubicWeb
+Forge`_ under a free software license.
+
+.. _`CubicWeb Forge`: http://www.cubicweb.org/project/
+
+
 
 Standard structure for a cube
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`````````````````````````````
 
 A complex cube is structured as follows:
 
@@ -389,25 +408,63 @@
 * ``schema`` contains the schema definition (server side only)
 * ``entities`` contains the entities definition (server side and web interface)
 * ``sobjects`` contains hooks and/or views notifications (server side only)
-* ``views`` contains the different components of the web interface (web interface only)
-* ``test`` contains tests specifics to the application (not installed)
-* ``i18n`` contains the messages catalog for supported languages (server side and 
-  web interface) 
-* ``data`` contains arbitrary data files served statically
-  (images, css, javascripts files)... (web interface only)
-* ``migration`` contains the initialization file for new instances
-  (``postcreate.py``) and in general a file containing the `CubicWeb` dependancies 
-  of the cube depending on its version (``depends.map``)
-* ``debian`` contains all the files that manages the debian packaging
-  (you would find there the classical structure with ``control``, ``rules``, 
-  ``changelog``... (not installed)
-* the file ``__pkginfo__.py`` provides meta-data on the cube, especially the 
-  distribution name and the current version (server side and web interface) or
-  also the sub-cubes used by this cube
-
-The only required files are:
+* ``views`` contains the web interface components (web interface only)
+* ``test`` contains tests related to the application (not installed)
+* ``i18n`` contains messages catalogs for supported languages (server side and
+  web interface)
+* ``data`` contains data files for static content (images, css, javascripts)
+  ...(web interface only)
+* ``migration`` contains initialization file for new instances (``postcreate.py``)
+  and a file containing dependencies of the component depending on the version
+  (``depends.map``)
+* ``debian`` contains all the files managing debian packaging (you will find
+  the usual files ``control``, ``rules``, ``changelog``... not installed)
+* file ``__pkginfo__.py`` provides component meta-data, especially the distribution
+  and the current version (server side and web interface) or sub-cubes used by
+  the cube.
+ 
+ 
+At least you should have:
 
 * the file ``__pkginfo__.py``
 * the schema definition
   XXX false, we may want to have cubes which are only adding a service, no persistent data (eg embeding for instance)
 
+
+Standard library
+````````````````
+
+A library of standard cubes are available from `CubicWeb Forge`_
+Cubes provide entities and views.
+
+The available application entities are:
+
+* addressbook: PhoneNumber and PostalAddress
+
+* basket: Basket (like a shopping cart)
+
+* blog: Blog (a *very* basic blog)
+
+* classfolder: Folder (to organize things but grouping them in folders)
+
+* classtags: Tag (to tag anything)
+
+* file: File (to allow users to upload and store binary or text files)
+
+* link: Link (to collect links to web resources)
+
+* mailinglist: MailingList (to reference a mailing-list and the URLs
+  for its archives and its admin interface)
+
+* person: Person (easily mixed with addressbook)
+
+* task: Task (something to be done between start and stop date)
+
+* zone: Zone (to define places within larger places, for example a
+  city in a state in a country)
+
+The available system entities are:
+
+* comment: Comment (to attach comment threads to entities)
+
+

--- a/doc/book/en/C013-cubicweb-ctl.en.txt	Tue Dec 23 15:42:01 2008 +0100
+++ b/doc/book/en/C013-cubicweb-ctl.en.txt	Tue Dec 23 10:43:51 2008 -0800
@@ -65,6 +65,7 @@
 * ``upgrade``, launches the existing instances migration when a new version
   of `CubicWeb` or the cubes installed is available
 * ``shell``, opens a migration shell for manual maintenance of the instance
+  (see :ref:`cubicweb-ctl-shell` for more details)
 * ``db-dump``, creates a dump of the system database
 * ``db-restore``, restores a dump of the system database
 * ``db-check``, checks data integrity of an instance. If the automatic correction
@@ -87,6 +88,16 @@
   and instances.
 * ``delete``, deletes an instance (configuration files and database)
 
+
+.. _cubicweb-ctl-shell:
+
+``cubicweb-ctl shell`` addon
+----------------------------
+
+XXX
+[FIXME]
+Add list of commands available in cubicweb-ctl shell.
+
 Examples
 --------