doc bug? IMAP info misleading

doc bug? IMAP info misleading

[Kai Großjohann]

Simon (& all others),

I think the Gnus info file is misleading wrt IMAP setup, but I'm not
sure what to do about it.  Excerpt from Info file:

/----
| `nnimap-stream'
| [...]
| 
|         * "ssl:" Connect through SSL. Require OpenSSL (the program
|           `openssl') or SSLeay (`s_client').
\----

Users might think that (nnimap-stream "ssl:") is the right thing to
put into their .gnus file.  But they should be using (nnimap-stream
ssl) instead!

How can the documentation be reformulated to make this clearer?

Also, the port number is often given as (nnimap-server-port "993")
where it should probably be (nnimap-server-port 993).

kai
-- 
I like BOTH kinds of music.

Re: doc bug? IMAP info misleading

[Simon Josefsson]

Kai.Grossjohann@CS.Uni-Dortmund.DE (Kai Großjohann) writes:

> I think the Gnus info file is misleading wrt IMAP setup, but I'm not
> sure what to do about it.

I agree.  Examples rules.  Is this better?  I've commited it.

IMAP
----

   IMAP is a network protocol for reading mail (or news, or ...), think
of it as a modernized NNTP.  Connecting to a IMAP server is much
similar to connecting to a news server, you just specify the network
address of the server.

   The following variables can be used to create a virtual `nnimap'
server:

...

`nnimap-server-port'
     Port on server to contact.  Defaults to port 143, or 993 for SSL.

     Note that this should be a integer, example server specification:

          (nnimap "mail.server.com"
                  (nnimap-server-port 4711))

...

`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).

     Example server specification:

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

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

        * "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').
...

Re: doc bug? IMAP info misleading

[Simon Josefsson]

Simon Josefsson <simon@josefsson.org> writes:

> > I think the Gnus info file is misleading wrt IMAP setup, but I'm not
> > sure what to do about it.
> 
> I agree.  Examples rules.

If select method specification was customized, I think this would be a
minor problem instead of a major one.

Re: doc bug? IMAP info misleading

[Kai Großjohann]

On 20 Sep 2000, Simon Josefsson wrote:

> Kai.Grossjohann@CS.Uni-Dortmund.DE (Kai Großjohann) writes:
> 
>> I think the Gnus info file is misleading wrt IMAP setup, but I'm
>> not sure what to do about it.
> 
> I agree.  Examples rules.  Is this better?  I've commited it.
> [...]
>      Note that this should be a integer, example server
>      specification:
> 
>           (nnimap "mail.server.com"
>                   (nnimap-server-port 4711))

Looks good.  Now the only thing that's missing is to explain to people
what to do with the server specs.  Ie, they can either type `e' in the
Server buffer, or they add it to gnus-secondary-select-methods, like
so:

(add-to-list 'gnus-secondary-select-methods '(nnimap ...))

But of course this is not specific to IMAP.

I wonder: should we tell people to set gnus-secondary-select-methods
to a list of server names, then edit the server parameters in the
server buffer?  Or should we tell them to put the whole select method
(rather than just the name) into gnus-secondary-select-methods?

kai
-- 
I like BOTH kinds of music.