RE: Overlay Documentation (Was: Overlay Cache Documentation)

["Voglmaier, Reinhard Erich" <rv33100@gsk.com>]

I'd volunteer for the documentation in the admin guide. Reinhard

-----Original Message-----
From: Pierangelo Masarati [mailto:ando@sys-net.it] 
Sent: giovedì 18 marzo 2004 14.10
To: Voglmaier, Reinhard Erich
Cc: openldap-devel@OpenLDAP.org
Subject: Overlay Documentation (Was: Overlay Cache Documentation)



> 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