Re-organizing the manpages (was: Re: [PATCH] Characters allowed in folder names (#2633))

[Bron Gondwana]

On Thu, Aug 12, 2010 at 09:29:27AM +0100, Jeroen van Meeuwen (Kolab Systems) wrote:
> Wesley Craig wrote:
> > On 10 Aug 2010, at 10:34, Jeroen van Meeuwen (Kolab Systems) wrote:
> > > How do you propose we do that, given the manpages are generated from
> > > lib/imapoptions by tools/config2man?
> > 
> > I haven't experimented with this myself, but it appears to me that  
> > lib/imapoptions *is* the man page *and* the code.  Take a look at the  
> > trailing block of lib/imapoptions:
> > 
> > /*
> > .SH SEE ALSO
> > .PP
> > \fBimapd(8)\fR, \fBpop3d(8)\fR, \fBnntpd(8)\fR, \fBlmtpd(8)\fR,
> > \fBtimsieved(8)\fR, \fBidled(8)\fR, \fBnotifyd(8)\fR,
> > \fBdeliver(8)\fR, \fBmaster(8)\fR, \fBciphers(1)\fR
> > */
> > 
> > Looks a lot like a man page, eh?  So you could get the desired effect  
> > by reorganizing lib/imapoptions, including adding a new section  
> > header between the "good to change" and "bad to change" options.   
> > Personally, I think a goal of "sane defaults" would be more helpful,  
> > but appropriately organizing the information is a great task for a  
> > volunteer to engage in!
> > 
> 
> I could at least take a stab at it ;-)
> 
> My proposition is to distinguish between the following groups of 
> configurables:
> 
> - Gets the job done (novice)
> - Gets your particular job done (advanced)
> - You're on your own (expert)
> 
> I would also like to split out murder and sync specific settings, and I would 
> probably want them in the Advanced section.
> 
> Is there anything else we can think of maybe?

I want most of the sync specific settings as parameters to sync client rather
than config variables, but that might just be because I want multi-target
replication soon :)

Bron ( but first, I'm going to finish cleaning up fiddly bits with -future )