Viewing Documentation/5915
Full headers

Major security issue: yes  no

Notes:

Notification:

Date: Thu, 29 Jan 2009 23:33:23 GMT
From: ghenry@OpenLDAP.org
To: openldap-its@openldap.org
Subject: Some man pages still only talk about slapd.conf

Full_Name: Gavin Henry
Version: 
OS: 
URL: ftp://ftp.openldap.org/incoming/
Submission from: (NULL) (92.41.236.102)
Submitted by: ghenry


Some discussion will be needed on the best way to talk about config. We don't
want to list everything twice for both formats...lots of slapd.conf written
throughout most (5/8) man pages.

Thanks.

Followup 1

Date: Thu, 29 Jan 2009 15:39:58 -0800
From: Howard Chu <hyc@symas.com>
To: ghenry@OpenLDAP.org
CC: openldap-its@OpenLDAP.org
Subject: Re: (ITS#5915) Some man pages still only talk about slapd.conf

ghenry@OpenLDAP.org wrote:
> Full_Name: Gavin Henry
> Version:
> OS:
> URL: ftp://ftp.openldap.org/incoming/
> Submission from: (NULL) (92.41.236.102)
> Submitted by: ghenry
>
>
> Some discussion will be needed on the best way to talk about config. We
don't
> want to list everything twice for both formats...lots of slapd.conf written
> throughout most (5/8) man pages.

I guess for this release (and probably for 2.5) we're just going to have to 
document both, as cumbersome as that will be. When we get to to 2.6/3.0 and 
drop support for slapd.conf we'll have to come back thru again and delete the 
slapd.conf references from all the docs. Unless anyone has a better idea...

-- 
   -- Howard Chu
   CTO, Symas Corp.           http://www.symas.com
   Director, Highland Sun     http://highlandsun.com/hyc/
   Chief Architect, OpenLDAP  http://www.openldap.org/project/

Followup 2

From: Hallvard B Furuseth <h.b.furuseth@usit.uio.no>
Date: Fri, 30 Jan 2009 12:42:26 +0100
To: hyc@symas.com
Cc: openldap-its@openldap.org
Subject: Re: (ITS#5915) Some man pages still only talk about slapd.conf

hyc@symas.com writes:
> I guess for this release (and probably for 2.5) we're just going to
> have to document both, as cumbersome as that will be. When we get to
> to 2.6/3.0 and drop support for slapd.conf we'll have to come back
> thru again and delete the slapd.conf references from all the
> docs. Unless anyone has a better idea...

I'm not sure I see the problem, except that Someone(TM) must do the
work...

For each configuration keyword, use two headers in the manpages: Both
the slapd.conf syntax and the cn=config syntax.  Explain at the
beginning of slapd.conf.5 or slapd-config.5.  We'll be deleting most of
the other one, since they are mostly duplicates.  Other manpages need
just one-line reminder for explanation.

There'll be exceptions that spell things out too differently, or use
slightly different parameters in slapd.conf and cn=config.  Keep them in
just slapd.conf-syntax, and add a separate cn=config attribute
description below.  Likely that'll only need to explain the difference.
Don't go trough literary contortions to fit them both into the same
description.  Some of these will likely be things that could use some
cleanup in the code anyway, bringing the two config formats in sync.

Take a random sample of the slapd.conf-syntax example sections and
replace with their cn=config equivalent.  Ensure all example sections
say either "slapd.conf example" or "cn=config example".

slapd.conf.5 and slapd-config.5 themselves will need sections about how
they work as interfaces to configuration, separate from the
configuration keywords/attributes themselves.  Since we are moving
towards cn=config, I suppose it's that one which should keep the actual
keyword/attribute descriptions.  Or they could move to a third file.

-- 
Hallvard