Dear all,
as described in my previous messages, I recently had a hard time relocating
(i.e. moving) mailboxes and the public namespace from 2.4.16 to a new server
running 2.5.10. I would have happily written a Perl script which surely had
solved much of my problems, but I couldn't do that due to the lack of
documentation for the respective Perl modules.
This is best explained by example:
I have found a Perl script on the 'net which looks trustworthy at the first
sight and which contains (among others) the following lines of code:
use Cyrus::IMAP::Admin;
# Connect to Cyrus
$imap = Cyrus::IMAP::Admin->new("my_server") || die "Unable to connect to
my_server";
$imap->authenticate(-user => "foo",
-mechanism => "LOGIN",
-password => "password",
);
I wanted to understand exactly what the script does and thus tried to find
Cyrus::IMAP::Admin's documentation. So I issued
man Cyrus::IMAP::Admin
and found that some methods are documented, but not the authenticate() method
which is needed first and one of the most important ones. However, the man page
states (in the section about the "new()" method):
"Instantiates a cyradm object. This is in fact an Cyrus::IMAP object with a
few additional methods, so all Cyrus::IMAP methods are available if needed.
(In particular, you will always want to use the "authenticate" method.)"
This tricked me into believing that the "authenticate" method would be part of
Cyrus::IMAP and would be explained in that module's documentation, so I issued
man Cyrus::IMAP
Well, this man page "documents" the method by exactly one line (identically in
two places):
$client->authenticate;
It does not explain anything about it; notably, it does not mention any
parameters. But from the example script mentioned above, I knew that there was
more to it. So I read the rest of that man page and found:
"The Cyrus::IMAP module provides an interface to the Cyrus imclient library."
So I installed the development files for Cyrus imapd and issued
man imclient
Now, finally, this is a man page a C programmer probably can live with. But
when looking more thoroughly into it, I saw that there is no "password"
parameter to the authenticate() function although the Perl module's
authenticate() method has one:
int imclient_authenticate (struct imclient *imclient, struct sasl_client
**availmech, const char *service, const char *user, int protallowed);
Plus, I could not find any hints regarding the relationship between the
parameters of the C functions and those of the Perl module methods.
I then headed over to cyrusimap.org and tried to find documentation for the
Perl modules. Surprisingly, I couldn't. Not a single word. They don't seem to
exist. The tools and helper programs are documented, but the Perl modules are
not even mentioned.
The same applies to CPAN: The modules cannot be found there.
To make a long story short:
Where can I find reasonable (in the sense: may be short and bad, but must be
*complete*) documentation for Cyrus::IMAP::Admin and Cyrus::IMAP so that I can
write my own helper scripts in the future? Do I really have to unpack Cyrus
imapd's sources and read the module source code to get some ideas?
Thank you very much in advance,
Binarus
----
Cyrus Home Page: http://www.cyrusimap.org/
List Archives/Info: http://lists.andrew.cmu.edu/pipermail/info-cyrus/
To Unsubscribe:
https://lists.andrew.cmu.edu/mailman/listinfo/info-cyrus
