--- a/doc/book/en/development/devweb/views/breadcrumbs.rst	Fri Apr 16 11:40:33 2010 +0200
+++ b/doc/book/en/development/devweb/views/breadcrumbs.rst	Fri Apr 16 13:57:27 2010 +0200
@@ -1,51 +1,54 @@
 Breadcrumbs
 -----------
 
-Breadcrumbs are a navigation component to situate the user in the
-arborescence's site.
-
+Breadcrumbs are a navigation component to help the user locate himself
+along a path of entities.
 
 Display
 ~~~~~~~
 
 Breadcrumbs are displayed by default in the header section (see
-:ref:`the_main_template_sections`).  With the default base template,
-the header section is composed by the logo, the application name,
-breadcrumbs and, at the most right, the login box. Breadcrumbs are
-displayed just next to the application name, thus breadcrumbs begin
-with a separator.
+:ref:`the_main_template_sections chapter`).  With the default main
+template, the header section is composed by the logo, the application
+name, breadcrumbs and, at the most right, the login box. Breadcrumbs
+are displayed just next to the application name, thus breadcrumbs
+begin with a separator.
 
 Here is the header section of the CubicWeb's forge:
 
 .. image:: ../../../images/breadcrumbs_header.png
 
 There are three breadcrumbs components defined in
-``cubicweb/web/views/ibreadcrumbs.py`` file:
+:mod:`cubicweb.web.views.ibreadcrumbs`:
 
-- BreadCrumbEntityVComponent: displayed for a result set with one line
+- `BreadCrumbEntityVComponent`: displayed for a result set with one line
   if the entity implements the ``IBreadCrumbs`` interface.
-- BreadCrumbETypeVComponent: displayed for a result set with more than
+- `BreadCrumbETypeVComponent`: displayed for a result set with more than
   one line, but with all entities of the same type which implement the
   ``IBreadCrumbs`` interface.
-- BreadCrumbAnyRSetVComponent: displayed for any other result set.
+- `BreadCrumbAnyRSetVComponent`: displayed for any other result set.
 
-Implementation
-~~~~~~~~~~~~~~
+Building breadcrumbs
+~~~~~~~~~~~~~~~~~~~~
 
 The ``IBreadCrumbs`` interface is defined in the
-``cubicweb/interfaces.py`` file. It specifies that an entity which
+:mod:`cubicweb.interfaces` module. It specifies that an entity which
 implements this interface must have a ``breadcrumbs`` method.
 
+.. note::
+
+   Redefining the breadcrumbs is the hammer way to do it. Another way
+   is to define the `parent` method on an entity (as defined in the
+   `ITree` interface). If available, it will be used to compute
+   breadcrumbs.
+
 Here is the API of the ``breadcrumbs`` method:
 
 .. automethod:: cubicweb.interfaces.IBreadCrumbs.breadcrumbs
 
-
 If the breadcrumbs method return a list of entities, the
 ``cubicweb.web.views.ibreadcrumbs.BreadCrumbView`` is used to display
-the first elements and the
-``cubicweb.web.views.ibreadcrumbs.BreadCrumbTextView`` is used to
-display the last one.
+the elements.
 
 By default, for any entity, if recurs=True, breadcrumbs method returns
 a list of entities, else a list of a simple string.
@@ -53,8 +56,3 @@
 In order to see a hierarchical breadcrumbs, entities must have a
 ``parent`` method which returns the parent entity. By default this
 method doesn't exist on entity, given that it can not be guessed.
-
-XXX To change the default separator, you have to monkeypatch the
-``BreadCrumbEntityVComponent.separator`` class attribute.
-
-XXX  add_to_breadcrumbs = False on an EntityView

--- a/interfaces.py	Fri Apr 16 11:40:33 2010 +0200
+++ b/interfaces.py	Fri Apr 16 13:57:27 2010 +0200
@@ -1,11 +1,16 @@
-"""Specific views for entities implementing IDownloadable
+# organization: Logilab
+# copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+# contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+# license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+"""
+Standard interfaces.
 
-:organization: Logilab
-:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+.. note::
+
+  The `implements` selector matches not only entity classes but also
+  their interfaces. Writing __select__ = implements('IGeocodable') is
+  a perfectly fine thing to do.
 """
-
 __docformat__ = "restructuredtext en"
 
 from logilab.common.interface import Interface
@@ -159,6 +164,7 @@
 class IBreadCrumbs(Interface):
     """interface for entities which can be "located" on some path"""
 
+    # XXX fix recurs !
     def breadcrumbs(self, view, recurs=False):
         """return a list containing some:
 

--- a/mixins.py	Fri Apr 16 11:40:33 2010 +0200
+++ b/mixins.py	Fri Apr 16 13:57:27 2010 +0200
@@ -1,11 +1,8 @@
-"""mixins of entity/views organized somewhat in a graph or tree structure
-
-
-:organization: Logilab
-:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
-"""
+# organization: Logilab
+# copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+# contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+# license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+"""mixins of entity/views organized somewhat in a graph or tree structure"""
 __docformat__ = "restructuredtext en"
 
 from itertools import chain
@@ -17,7 +14,7 @@
 
 
 class TreeMixIn(object):
-    """base tree-mixin providing the tree interface
+    """base tree-mixin implementing the tree interface
 
     This mixin has to be inherited explicitly and configured using the
     tree_attribute, parent_target and children_target class attribute to
@@ -275,8 +272,7 @@
 
 
 class ProgressMixIn(object):
-    """provide default implementations for IProgress interface methods"""
-    # This is an adapter isn't it ?
+    """provide a default implementations for IProgress interface methods"""
 
     @property
     def cost(self):