[PATCH] Characters allowed in folder names (#2633)

[Henrique de Moraes Holschuh]

On Sun, 08 Aug 2010, Jeroen van Meeuwen (Kolab Systems) wrote:
> Henrique de Moraes Holschuh wrote:
> > On Sun, 08 Aug 2010, Jeroen van Meeuwen (Kolab Systems) wrote:
> > > - "Expert" settings - you're on your own.
> > > 
> > > This setting, I think, is a typical "you're on your own" type of setting. 
> > 
> > So, make it compile-time.
> 
> I think -from the perspective of a distributor- having consumers of such 
> distribution recompile with different options because of a niche situation 
> eliminates an otherwise smooth update path and does deserve some thought 
> beforehand -like what we're doing here.

In this specific case, if it is a safe thing to change, it should just be
made the default alerady.  If it is not something safe to change and which
should be changed only in the most specific and rare cases by people who
REALLY know what they're doing (i.e. know all IMAP/POP/LMTP/NNTP RFCs, and
also the internal details of Cyrus spools and its namespaces), it should be
a compile-time option that distros better not even dream of messing with.

> > > While I think it should be configurable, I dislike throwing it in the man 
> > > page. I would argue this type of thing is way better documented on a 
> > > cyrusimap.org Wiki article.
> > 
> > Bad idea.  VERY bad idea.
> 
> I take it you disagree ;-)

Yes.  Online docs are never around when you need them, and evolve separately
from the software in a distro (which stays frozen for a long while and only
sees security updates).  Wikis are especially bad, as even snapshoting them
into a html/ dir is often quite a pain.

> My point was that (some) advanced settings are more appropriately documented 
> in a "live" document that can be enhanced by many to explain more about the 
> advanced setting. Not unlike the documentation in Cyrus IMAP that Debian 

Well, wikis are easier to keep up-to-date, but they are also much easier to
tamper with, lose focus, get wrong information added by well-intentioned
people who really don't know as much as they thing they do, and often end up
getting lost to the sands of time should archive.org decide not to snapshot
them.  Just like blogs.

> patches to express additional information about the use of virtdomains and 
> authorisation IDs, but not in CVS nor in a specific package from one specific 
> distributor.

Yet one more change we should send upstream, then.

> > label it as an advanced config option.
> > 
> 
> And how do you suggest we do mark it as an advanced config option?

Either add a new section for advanced options, or just write "This is an
advanced option, don't mess with it unless you know what you are doing" in
the text for that option.

> We can ship a text file with the distribution from a wiki article, and put it 
> in /usr/share/doc/cyrus-imapd. We could create man pages from that content, or 

That is acceptable, yes.  But it is suboptimal.

> The OP already has exactly what you want. It was argued we need to be careful 
> throwing all too many configurables at the consumer, for which there is 
> currently only a single mechanism in place. *That's* what I'm trying to work 
> with here.

Our demographics are sysadmins.  IMO, we should just organize the
documentation properly to let them know what options are best left alone,
but document them througoutly.  Cluster all such options (e.g. under a new
"advanced options" manpage section, and people will just skip over them
unless they need them.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh