--- a/doc/book/en/B1010-request.en.txt	Mon Dec 29 15:37:12 2008 -0800
+++ b/doc/book/en/B1010-request.en.txt	Mon Dec 29 17:47:00 2008 -0800
@@ -1,6 +1,6 @@
 .. -*- coding: utf-8 -*-
 
-request
+Request
 =======
 
 [WRITE ME]

--- a/doc/book/en/B1020-define-views.en.txt	Mon Dec 29 15:37:12 2008 -0800
+++ b/doc/book/en/B1020-define-views.en.txt	Mon Dec 29 17:47:00 2008 -0800
@@ -5,19 +5,47 @@
 Views definition
 ================
 
+This chapter aims to describe the concept of a `view` used all along
+the development of a web application and how it has been implemented
+in `CubicWeb`.
+
+We'll start with a description of the interface providing you a basic 
+understanding of the classes and methods available. We'll also
+take time to develop the view selection principle we implemented
+which is very unique to `CubicWeb` and makes it powerfull.
+
 Basic class for views
 ---------------------
 
 Class `View` (`cubicweb.common.view`)
 `````````````````````````````````````
 
+This class is an abstraction of a view class, used as a base for every 
+renderable object such as views, templates, graphic components... web.
+
+A `View` is  instantiated to render a or part of a result set. `View`
+subclasses may be parametrized using the following class attributes:
+
+    * `templatable` indicates if the view may be embeded in a main
+      template or if it has to be rendered standalone (i.e. XML for
+      instance)
+    * if the view is not templatable, it should set the `content_type` class
+      attribute to the correct MIME type (text/xhtml by default)
+    * the `category` attribute may be used in the interface to regroup related
+      objects together
+
+At instantiation time, the standard `req`, `rset`, and `cursor`
+attributes are added and the `w` attribute will be set at rendering
+time to a write function to use.
+
 A view writes in its output exit thanks to its attribute `w` (`UStreamIO`).
 
 The basic interface for views is as follows:
 
 * `dispatch(**context)`, render the view by calling `call` or
   `cell_call` depending on the given parameters
-* `call(**kwargs)`, call the view for a complete result set or null
+* `call(**kwargs)`, call the view for a complete result set or null and call
+  the method `cell_call()` on each cell of the result set
 * `cell_call(row, col, **kwargs)`, call the view for a given cell of a result set
 * `url()`, returns the URL enabling us to get the view with the current
   result set 
@@ -36,12 +64,15 @@
 * `creator(eid)`, returns the eid and the login of the entity creator of the entity
   having the eid given in the parameter 
 
-Other basic classes:
+Other basic views classes
+`````````````````````````
+Here are some of the subclasses of `View` defined in `cubicweb.common.view`
+that are more concrete as they relates to data rendering within the application:
 
 * `EntityView`, view applying to lines or cell containing an entity (e.g. an eid)
 * `StartupView`, start view that does not require a result set to apply to
 * `AnyRsetView`, view applied to any result set 
-
+* `EmptyRsetView`, view applied to an empty result set
 
 The selection view principle
 ----------------------------
@@ -49,9 +80,11 @@
 A view includes :
 
 - an identifier (all objects in `CubicWeb` are entered in a registry
-  and this identifier will be used as a key)
+  and this identifier will be used as a key). This is defined in the class
+  attribute ``id``.
   
-- a filter to select the resulsets it can be applied to
+- a filter to select the resulsets it can be applied to. This is defined in
+  the class attribute ``__selectors__``
 
 
 For a given identifier, multiple views can be defined. `CubicWeb` uses
@@ -61,26 +94,19 @@
 compute scores is in ``cubicweb.vregistry.vreq``.
 
 
-`CubicWeb` provides a lot of standard views, for a complete list, you
-will have to read the code in directory ``cubicweb/web/views/`` (XXX
-improve doc).
-
 `CubicWeb` provides a lot of standard views for the default class
 `EntityType`. You can find them in ``cubicweb/web/views/``.
 
-The basic views defined are : 
-
-*null* 
-  
-
+.. include:: B1021-views-stdlib.en.txt
 
 
+Example of a view customization
+-------------------------------
 
-For example, the view named ``primary`` is the one used to display
-a single entity.
+We'll show you now an example of a ``primary`` view and how to customize it.
 
 If you want to change the way a ``BlogEntry`` is displayed, just
-override the view ``primary`` in ``BlogDemo/views.py`` ::
+override the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py`` ::
 
   01. from ginco.web.views import baseviews
   02.
@@ -159,8 +185,8 @@
 * implementing interfaces, calendar for blog entries
 * show that a calendar view can export data to ical
 
-We will implement the cubicwweb.interfaces.ICalendarable interfaces on
-entities.BloEntry and apply the OneMonthCalendar and iCalendar views
+We will implement the `cubicweb.interfaces.ICalendarable` interfaces on
+entities.BlogEntry and apply the OneMonthCalendar and iCalendar views
 to resultsets like "Any E WHERE E is BlogEntry"
 
 * create view "blogentry table" with title, publish_date, category
@@ -185,7 +211,7 @@
 class `Template` (`cubicweb.common.view`) is derived from the class `View`.
 
 To build a HTML page, a *main template* is used. In general, the template of
-identifier `main` is the one (it is not used in case an error is raised or for
+identifier `main` is the one to use (it is not used in case an error is raised or for
 the login form for example). This template uses other templates in addition
 to the views which depends on the content to generate the HTML page to return.
 
@@ -195,34 +221,7 @@
 2. identifying the view to use to render data if it is not specified
 3. composing the HTML page to return
 
-
-The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`)
-------------------------------------------------------------------------------
-
-The default main template build the page based on the following pattern:
-
-.. image:: images/main_template_layout.png
-
-The rectangle containing `view.dispathc()` represents the area where the content
-view has to be displayed. The others represents sub-templates called to complete
-the page. A default implementation of those is provided in 
-`cubicweb.views.basetemplates`. You can, of course, overload those sub-templates
-to implement your own customization of the HTML page.
-
-We can also control certain aspects of the main template thanks to the following
-forms parameters:
-
-* `__notemplate`, if present (whatever the value assigned), only the content view
-  is returned
-* `__force_display`, if present and its value is not null, no navigation 
-  whatever the number of entities to display
-* `__method`, if the result set to render contains only one entity and this 
-  parameter is set, it refers to a method to call on the entity by passing it
-  the dictionnary of the forms parameters, before going the classic way (through
-  step 1 and 2 described juste above)
-
-.. include:: B1021-views-stdlib.en.txt
-
+You will find out more about templates in :ref:`templates`. 
 
 XML views, binaries...
 ----------------------
@@ -236,7 +235,7 @@
 
 For the views dedicated to binary content creation (an image dynamically generated
 for example), we have to set the attribute `binary` of the class to `True` (which
-implies that `templateable == False`, so that the attribute `w` of the view could be
+implies that `templatable == False`, so that the attribute `w` of the view could be
 replaced by a binary flow instead of unicode).
 
 (X)HTML tricks to apply

--- a/doc/book/en/B1021-views-stdlib.en.txt	Mon Dec 29 15:37:12 2008 -0800
+++ b/doc/book/en/B1021-views-stdlib.en.txt	Mon Dec 29 17:47:00 2008 -0800
@@ -7,59 +7,83 @@
 to one or more entities. Their identifier is what distinguish them from
 each others and the main ones are:
 
-:primary:
-    primary view of an entity, this is the view called by default when a single
-    entity is in the result set and needs to be displayed. This view is supposed
-    to render a maximum of informations about the entity.
-:secondary:
-    secondary view of an entity. By default it renders the two first attributes
-     of the entity as a clickable link redirecting to the primary view.
-:oneline:
-    similar to the `secondary` view, but called when we want the view to stand
-    on a single line, or just get a brief view. By default this view uses the
+*primary*
+    Primary view of an entity, this is the view called by default when a single
+    non final entity is in the result set and needs to be displayed. 
+    This view is supposed to render a maximum of informations about the entity.
+
+*text*
+    This is the simplest text view for an entity. It displays the 
+    title of an entity. It should not contain HTML.
+
+*oneline*
+    This is a hyper linked *text* view. Similar to the `secondary` view, 
+    but called when we want the view to stand on a single line, or just 
+    get a brief view. By default this view uses the
     parameter `MAX_LINE_CHAR` to control the result size.
-:text:
-    similar to the `oneline` view, but should not contain HTML.
-:incontext, outofcontext:
-    similar to the `secondary` view, but called when an entity is considered
+
+*secondary*
+    This is a combinaison of an icon and a *oneline* view.
+    By default it renders the two first attributes of the entity as a 
+    clickable link redirecting to the primary view.
+
+*incontext, outofcontext*
+    Similar to the `secondary` view, but called when an entity is considered
     as in or out of context. By default it respectively returns the result of 
     `textincontext` and `textoutofcontext` wrapped in a link leading to 
     the primary view of the entity.
-:textincontext, textoutofcontext:
-    similar to the `text` view, but called is an entity is considered out or
+
+*textincontext, textoutofcontext*
+    Similar to the `text` view, but called when an entity is considered out or
     in context. By default it returns respectively the result of the 
     methods `.dc_title` and `.dc_long_title` of the entity.
-:list:
-    creates a HTML list (`<ul>`) and call the view `listitem` for each entity
-    of the result set
-:listitem:
-    redirects by default to the `outofcontext` view
-:rss:
-    creates a RSS/XML view and call the view `rssitem` for each entity of
-    the result set
-:rssitem:
-    create a RSS/XML view for each entity based on the results of the dunblin core
+
+*list*
+    This view displays a list of entities by creating a HTML list (`<ul>`) 
+    and call the view `listitem` for each entity of the result set.
+
+*listitem*
+    This view redirects by default to the `outofcontext` view.
+
+*rss*
+    Creates a RSS/XML view and call the view `rssitem` for each entity of
+    the result set.
+
+*rssitem*
+    Create a RSS/XML view for each entity based on the results of the dublin core
     methods of the entity (`dc_*`)
 
+*sidebox*
+  This view displays usually a side box of some related entities 
+  in a primary view.
+
 Start view:
 
-:index:
-    home page
-:schema:
-    display the schema of the application
+*index*
+    This view defines the home page of your application. It does not require
+    a result set to apply to.
+
+*schema*
+    A view dedicated to the display of the schema of the application
 
 Special views:
 
-:noresult:
-    called if the result set is empty
-:finall:
-    display the value of a cell without trasnformation (in case of a non final
+*noresult*
+    This view is the default view used when no result has been found
+    (e.g. empty result set).
+
+*final*
+    Display the value of a cell without trasnformation (in case of a non final
     entity, we see the eid). Applicable on any result set.
-:table:
-    creates a HTML table (`<table>`) and call the view `cell` for each cell of
+
+*table*
+    Creates a HTML table (`<table>`) and call the view `cell` for each cell of
     the result set. Applicable on any result set.
-:cell:
-    by default redirects to the `final` view if this is a final entity or
+
+*cell*
+    By default redirects to the `final` view if this is a final entity or
     `outofcontext` view otherwise
-:null:
-    view always applicable and which does not return anything
+
+*null*
+    This view is the default view used when nothing needs to be rendered.
+    It is always applicable and it does not return anything

--- a/doc/book/en/B1060-templates.en.txt	Mon Dec 29 15:37:12 2008 -0800
+++ b/doc/book/en/B1060-templates.en.txt	Mon Dec 29 17:47:00 2008 -0800
@@ -1,5 +1,7 @@
 .. -*- coding: utf-8 -*-
 
+.. _templates:
+
 Templates
 =========
 
@@ -156,17 +158,36 @@
 ---------------
 .. _TheMainTemplate:
 
+TheMainTemplate is responsible for the general layout of the entire application. 
+It defines the template of ``id = main`` that is used by the application.
+
+The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`)
+builds the page based on the following pattern:
+
+.. image:: images/main_template_layout.png
+
+The rectangle containing `view.dispatch()` represents the area where the content
+view has to be displayed. The others represents sub-templates called to complete
+the page. A default implementation of those is provided in 
+`cubicweb.views.basetemplates`. You can, of course, overload those sub-templates
+to implement your own customization of the HTML page.
+
+We can also control certain aspects of the main template thanks to the following
+forms parameters:
+
+* `__notemplate`, if present (whatever the value assigned), only the content view
+  is returned
+* `__force_display`, if present and its value is not null, no navigation 
+  whatever the number of entities to display
+* `__method`, if the result set to render contains only one entity and this 
+  parameter is set, it refers to a method to call on the entity by passing it
+  the dictionnary of the forms parameters, before going the classic way (through
+  step 1 and 2 described juste above)
+
 The MainTemplate is a bit complex as it tries to accomodate many
 different cases. We are now about to go through it and cutomize entirely
 our application.
 
-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 ``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
 
 CSS changes
 -----------
@@ -180,7 +201,7 @@
 apply a higher priority on the default CSS and you can not change that. 
 Customized CSS will not be read first.
 
-1
+
 [TODO]
 Add login menu in left column