--- a/doc/book/en/admin/ldap.rst	Fri Jan 18 18:31:25 2013 +0100
+++ b/doc/book/en/admin/ldap.rst	Wed Jan 09 14:27:51 2013 +0100
@@ -12,49 +12,55 @@
 
 At cube creation time, one is asked if more sources are wanted. LDAP
 is one possible option at this time. Of course, it is always possible
-to set it up later in the `source` configuration file, which we
-discuss there.
+to set it up later using the `CWSource` entity type, which we discuss
+there.
 
 It is possible to add as many LDAP sources as wanted, which translates
-in as many [ldapxxx] sections in the `source` configuration file.
+in as many `CWSource` entities as needed.
 
 The general principle of the LDAP source is, given a proper
 configuration, to create local users matching the users available in
-the directory, deriving local user attributes from directory users
+the directory and deriving local user attributes from directory users
 attributes. Then a periodic task ensures local user information
 synchronization with the directory.
 
+Users handled by such a source should not be edited directly from
+within the application instance itself. Rather, updates should happen
+at the LDAP server level.
+
 Credential checks are _always_ done against the LDAP server.
 
-The base functionality for this is in
-:file:`cubicweb/server/sources/ldapuser.py`.
+.. Note::
 
-External dependencies
----------------------
-
-You'll need the following packages to make CubicWeb interact with your LDAP /
-Active Directory server:
+  There are currently two ldap source types: the older `ldapuser` and
+  the newer `ldapfeed`. The older will be deprecated anytime soon, as
+  the newer has now gained all the features of the old and does not
+  suffer from some of its illnesses.
 
-* python-ldap
-* ldaputils if using `ldapfeed` source
+  The ldapfeed creates real `CWUser` entities, and then
+  activate/deactivate them depending on their presence/absence in the
+  corresponding LDAP source. Their attribute and state
+  (activated/deactivated) are hence managed by the source mechanism;
+  they should not be altered by other means (as such alterations may
+  be overridden in some subsequent source synchronisation).
 
-Configurations options
-----------------------
 
-Let us enumerate the options (but please keep in mind that the
-authoritative source for these is in the aforementioned python
-module), by categories (LDAP server connection, LDAP schema mapping
-information, LDAP source internal configuration).
+Configurations options of an LDAPfeed source
+--------------------------------------------
+
+Let us enumerate the options by categories (LDAP server connection,
+LDAP schema mapping information).
 
 LDAP server connection options:
 
-* `host`, may contain port information using <host>:<port> notation.
-* `protocol`, choices are ldap, ldaps, ldapi
 * `auth-mode`, (choices are simple, cram_md5, digest_md5, gssapi, support
   for the later being partial as of now)
+
 * `auth-realm`, realm to use when using gssapi/kerberos authentication
+
 * `data-cnx-dn`, user dn to use to open data connection to the ldap (eg
   used to respond to rql queries)
+
 * `data-cnx-password`, password to use to open data connection to the
   ldap (eg used to respond to rql queries)
 
@@ -62,21 +68,29 @@
 leave data-cnx-dn and data-cnx-password empty. This is, however, quite
 unlikely in practice.
 
-LDAP schema mapping:
+LDAP schema mapping options:
 
 * `user-base-dn`, base DN to lookup for users
-* `user-scope`, user search scope
-* `user-classes`, classes of user
-* `user-attrs-map`, map from ldap user attributes to cubicweb attributes
-* `user-login-attr`, attribute used as login on authentication
+
+* `user-scope`, user search scope (valid values: "BASE", "ONELEVEL",
+  "SUBTREE")
 
-LDAP source internal configuration:
+* `user-classes`, classes of user (with Active Directory, you want to
+  say "user" here)
+
+* `user-filter`, additional filters to be set in the ldap query to
+  find valid users
+
+* `user-login-attr`, attribute used as login on authentication (with
+  Active Directory, you want to use "sAMAccountName" here)
 
 * `user-default-group`, name of a group in which ldap users will be by
   default. You can set multiple groups by separating them by a comma
-* `synchronization-interval`, interval between synchronization with the
-  ldap directory in seconds (default to once a day)
-* `cache-life-time`, life time of query cache in minutes (default to two hours).
+
+* `user-attrs-map`, map from ldap user attributes to cubicweb
+  attributes (with Active Directory, you want to use
+  sAMAccountName:login,mail:email,givenName:firstname,sn:surname)
+
 
 Other notes
 -----------
@@ -87,14 +101,13 @@
   authenticated but their status will not change (e.g. they will not
   be deactivated)
 
-* Changing the name of the ldap server in your script is fine, changing the base
-  DN isn't since it's used to identify already known users from others
+* The user-base-dn is a key that helps cubicweb map CWUsers to LDAP
+  users: beware updating it
 
 * When a user is removed from an LDAP source, it is deactivated in the
   CubicWeb instance; when a deactivated user comes back in the LDAP
   source, it (automatically) is activated again
 
-
 * You can use the :class:`CWSourceHostConfig` to have variants for a source
   configuration according to the host the instance is running on. To do so go on
   the source's view from the sources management view.