Overlay Documentation (Was: Overlay Cache Documentation)

["Pierangelo Masarati" <ando@sys-net.it>]

> I posted a suggestion about the "proxy cache" chapter in the issue
> tracking system some time ago.
> In the meantime I played around with the overlay cache. I found out that
> documentation is not very aligned with what the sw is actually doing.
> Therefore I would propose to review the chapter in order to align it
> more to the actual release.

Sure.  I think we should consider the opportunity to document the overlay
mechanism from the user's, but also from the developer's perspective, and
find an appropriate place for this documentation in the admin guide, as
the API is freezing.  In this framework the documentation of the currently
available overlays could fit more easily.  The most authoritative sources
of info (apart from the code :) currently are:

slapd.conf(5):    how overlays are staked on a database
slapd-meta(5):    what parameters are given to the proxycache
                  overlay, and what's its behavior
slapd-ppolicy(5): a clean and detailed description of how
                  this overlay works
slapd-relay(5):   a description of how the (yet incomplete)
                  rewrite-remap overlay works within the
                  back-relay to provide DN rewrite and
                  attributeType/objectClass mapping in relaying
                  virtual to real naming contexts.

I think we should:
1) define a place for overlay documentation and a naming
   convention for man pages, to separate them from backend man pages
2) document the other currently available overlays, i.e.
   chain (move it from back-ldap/ into overlays/ ?), denyop,
   and dyngroup
3) define a convention for overlay-specific statements, at least
   for future ones, to avoid potential name clashing with database
   specific names (e.g. "<overlay name>-<statement name>" ?);
   overlays like "chain", which is essentially an invocation of
   the back-ldap backend, could be implemented by intercepting
   the prefix "<overlay name>-" and removing it from argv[0]
   before invoking the ldap_back_db_config() function.
4) provide working examples of all overlays.

I'd volunteer for harmonizing the statement naming and for
separating the chain overlay from back-ldap.  It is questionable
whether we sould preserve compatibility with the current overlay
statement naming, since they have been introduced very recently.
If the overhead is not too much I think we should, with a clear
notice that it will not be preserved after the next major version
(2.3?)

p.

-- 
Pierangelo Masarati
mailto:pierangelo.masarati@sys-net.it