Bug#402814: cyrus-imapd-2.2: Inadequate documentation of 'sasl_minimum_layer'

[Henrique de Moraes Holschuh]

On Wed, 13 Dec 2006, Michael Richters wrote:
> FYI: the string "sasl_minimum_layer" appears in the cyrus-imapd-2.2
> source package, but not in the cyrus-sasl2 package:

Strip the sasl_ prefix when grepping SASL code and docs.

That said, there are two possibilities for sasl_minimum_layer:

1. Cyrus imap does its own processing on top of whatever SASL already does.

2. It is in fact implemented by cyrus imap.


If it is (2), we document it. If it is (1), we document it in a case by case
basis.

There is also a (3): if I am wrong and cyrus now knows a set of SASL options
and doesn't pass them blindly to SASL anymore, then we document them all.

I don't have the time to find out which is the case here, though. At least
not right now.  It could be just that cyrus imap tries to change the default
sasl minimum layer, which I find likely.

> I don't think it's reasonable to expect someone to grep through the
> source in order to determine that "sasl_minimum_layer" in one package
> translates to "min_ssf" in another.  Not to mention the fact that this
> information still doesn't lead me to an answer to my original
> question.

It should not translate to min_ssf at all, unless SASL is renaming options,
in which case whomever is doing the translation needs to document it (either
cyrus imap or sasl).

But no, it is not reasonable to have to grep code to find this information.
SASL should document all their options easily, and in a manpage.  Feel free
to file a bug against libsasl2 requesting that.

We are already agreeing that cyrus should also document those that are its
responsability, btw.  I just don't know which ones are at this point, as I
don't have the time to go code-hunting on cyrus right now.

I hope one of the other maintainers can do it soon.

-- 
  "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