Re: Setting up Gnus with IMAP

[Sebastian Kaps <seb-dated-1058361745.7f8e08@toyland.sauerland.de>]

// Simon Josefsson writes:

> Sebastian Kaps <seb-dated-1058345066.f5d54a@toyland.sauerland.de> writes:
>> // Kai Großjohann writes:
>> 
>>> IMHO it doesn't make sense to specify so many values which are the
>>> default anyhow.  For example, should the port be "143" or 143?
>>> Should the authenticator be "login" or login?  Etc pp.
>> 
>> Yes, you're right. But shouldn't the documentation be more clearly about
>> this issue?

> The documentation says the following.  How can we improve it?

My version of the documentation seems a bit outdated. For nnimap-stream
it says:
,----
| `nnimap-stream'
|      The type of stream used to connect to your server.  By default,
|      nnimap will detect and automatically use all of the below, with
|      the exception of SSL. (SSL is being replaced by STARTTLS, which
|      can be automatically detected, but it's not widely deployed yet).
| 
|         * "gssapi:" Connect with GSSAPI (usually kerberos 5). Require
|           the `imtest' program.
| 
|         * "kerberos4:" Connect with kerberos 4. Require the `imtest'
|           program.
| 
|         * "starttls:" Connect via the STARTTLS extension (similar to
|           SSL). Require the external library `starttls.el' and program
|           `starttls'.
| 
|         * "ssl:" Connect through SSL. Require OpenSSL (the program
|           `openssl') or SSLeay (`s_client').
| 
|         * "network:" Plain, TCP/IP network connection.
| 
|      The `imtest' program is shipped with Cyrus IMAPD, nnimap support
|      both `imtest' version 1.5.x and version 1.6.x.
| 
|      For SSL connections, the OpenSSL program is available from
|      `http://www.openssl.org/'. OpenSSL was formerly known as SSLeay,
|      and nnimap support it too - altough the most recent versions of
|      SSLeay, 0.9.x, are known to have serious bugs making it useless.
|      Earlier versions, especially 0.8.x, of SSLeay are known to work.
`----

Note that the possible values are quoted (and even contain colons). This
might be confusing.


> `nnimap-stream'
>      The type of stream used to connect to your server.  By default,
>      nnimap will detect and automatically use all of the below, with
>      the exception of TLS/SSL.  (IMAP over TLS/SSL is being replaced by
>      STARTTLS, which can be automatically detected, but it's not widely
>      deployed yet.)

>      Example server specification:

>           (nnimap "mail.server.com"
>                   (nnimap-stream ssl))

>      Please note that the value of `nnimap-stream' is a symbol!
> ...

This is much better. I think the example wipes out any possible doubt.
However - as an end user who is not very familar with lisp - the "...is
a symbol!" part doesn't help much. I'd have to look up the meaning of
'symbol' in the lisp documentation, which wouldn't be a problem but I
think it's unnecessary.

-- 
Ciao, Sebastian