comparison man/gnus.texi @ 49600:23a1cea22d13

Trailing whitespace deleted.

49599:5ade352e8d1c

* NNTP::               Reading news from an @sc{nntp} server.
* News Spool::         Reading news from the local spool.

Getting Mail

* Mail in a Newsreader::         Important introductory notes.  
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail::               How to create mail groups.
* Mail Sources::                 How to tell Gnus where to get mail from.
* Mail Back End Variables::      Variables for customizing mail handling.
* Fancy Mail Splitting::         Gnus can do hairy splitting of incoming mail.

@vindex gnus-subscribe-killed
Kill all new groups.

@item gnus-subscribe-topics
@vindex gnus-subscribe-topics
Put the groups into the topic that has a matching @code{subscribe} topic 
parameter (@pxref{Topic Parameters}).  For instance, a @code{subscribe}
topic parameter that looks like

@example
"nnslashdot"
@end example

will mean that all groups that match that regex will be subscribed under 
that topic.

If no topics match the groups, the groups will be subscribed in the
top-level topic.

read all the replies in one swoop.  This will normally result in better
performance, but if the server does not support the aforementioned
@code{LIST ACTIVE group} command, this isn't very nice to the server.

If you think that starting up Gnus takes too long, try all the three
different values for this variable and see what works best for you. 

In any case, if you use @code{some} or @code{nil}, you should definitely
kill all groups that you aren't interested in to speed things up.

Note that this variable also affects active file retrieval from

Elements that look like @code{(ignored-charsets x-known iso-8859-1)}
will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the
default charset will be used for decoding articles.

See also @code{gnus-group-ignored-charsets-alist}.
 
@item posting-style
You can store additional posting style information for this group only
here (@pxref{Posting Styles}).  The format is that of an entry in the
@code{gnus-posting-styles} alist, except that there's no regexp matching
the group name (of course).  Style elements in this group parameter will

convention (@pxref{Process/Prefix}).

@item T j
@kindex T j (Topic)
@findex gnus-topic-jump-to-topic
Go to a topic (@code{gnus-topic-jump-to-topic}).  

@item T c
@kindex T c (Topic)
@findex gnus-topic-copy-group
Copy the current group to some other topic

In addition, the following parameters are only valid as topic
parameters:

@table @code
@item subscribe
When subscribing new groups by topic (@pxref{Subscription Methods}), the 
@code{subscribe} topic parameter says what groups go in what topic.  Its 
value should be a regexp to match the groups that should go in that
topic. 

@end table

Group parameters (of course) override topic parameters, and topic
parameters in sub-topics override topic parameters in super-topics.  You

    '(((nntp "news.com.cn") . cn-gb-2312)))
@end lisp

@item gnus-group-name-charset-group-alist
@vindex gnus-group-name-charset-group-alist
An alist of regexp of group name and the charset for group names. 
It is used to show non-ASCII group names.

For example:
@lisp
(setq gnus-group-name-charset-group-alist

If given a numerical prefix, you can do semi-manual charset stuff.
@kbd{C-u 0 g cn-gb-2312 @key{RET}} will decode the message as if it were
encoded in the @code{cn-gb-2312} charset.  If you have

@lisp
(setq gnus-summary-show-article-charset-alist 
      '((1 . cn-gb-2312) 
        (2 . big5)))
@end lisp

then you can say @kbd{C-u 1 g} to get the same effect.

@item S o p
@kindex S o p @r{(Summary)}
@findex gnus-summary-post-forward
Forward the current article to a newsgroup
(@code{gnus-summary-post-forward}).  
 If no prefix is given, the message is forwarded according to the value
of (@code{message-forward-as-mime}) and
(@code{message-forward-show-mml}); if the prefix is 1, decode the
message and forward directly inline; if the prefix is 2, forward message
as an rfc822 MIME section; if the prefix is 3, decode message and

If you'd like to save articles in a hierarchy that looks something like
a spool, you could

@lisp
(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
(setq gnus-default-article-saver 
      'gnus-summary-save-in-file) ; no encoding
@end lisp

Then just save with @kbd{o}.  You'd then read this hierarchy with
ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and

You can give the command a numerical prefix to specify the width to use
when filling.

@item W Q
@kindex W Q @r{(Summary)}
@findex gnus-article-fill-long-lines 
Fill long lines (@code{gnus-article-fill-long-lines}).

@item W C
@kindex W C @r{(Summary)}
@findex gnus-article-capitalize-sentences

makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}.

@item W h
@kindex W h @r{(Summary)}
@findex gnus-article-wash-html
Treat HTML (@code{gnus-article-wash-html}).  
Note that the this is usually done automatically by Gnus if the message
in question has a @code{Content-Type} header that says that this type
has been done.

@item W f

@table @kbd
@item A t
@kindex A t @r{(Summary)}
@findex gnus-article-babel
Translate the article from one language to another
(@code{gnus-article-babel}). 

@end table


@node MIME Commands

@cindex move mail
@findex gnus-summary-move-article
@vindex gnus-preserve-marks
Move the article from one mail group to another
(@code{gnus-summary-move-article}).  Marks will be preserved if
@var{gnus-preserve-marks} is non-@code{nil} (which is the default). 

@item B c
@kindex B c @r{(Summary)}
@cindex copy mail
@findex gnus-summary-copy-article

(@code{gnus-mime-copy-part}).

@findex gnus-mime-view-part-as-type
@item t @r{(Article)}
View the @sc{mime} object as if it were a different @sc{mime} media type
(@code{gnus-mime-view-part-as-type}). 

@findex gnus-mime-pipe-part
@item | @r{(Article)}
Output the @sc{mime} object to a process (@code{gnus-mime-pipe-part}).

@vindex gnus-part-display-hook
You can, of course, write your own functions to be called from
@code{gnus-part-display-hook}.  The functions are called narrowed to the
part, and you can do anything you like, pretty much.  There is no
information that you have to keep in the buffer---you can change
everything.  


@node Article Keymap
@section Article Keymap

@enumerate
@item
The file contains one or more line, each of which define one server.

@item
Each line may contain an arbitrary number of token/value pairs.  

The valid tokens include @samp{machine}, @samp{login}, @samp{password},
@samp{default}.  In addition Gnus introduces two new tokens, not present
in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and
@samp{force}.  (This is the only way the @file{.authinfo} file format

The default value is

@lisp
'(("nntpd 1\\.5\\.11t"
   (remove-hook 'nntp-server-opened-hook 
                'nntp-send-mode-reader)))
@end lisp

This ensures that Gnus doesn't send the @code{MODE READER} command to
nntpd 1.5.11t, since that command chokes that server, I've been told.

define a server as follows:

@lisp
;; Type `C-c C-c' after you've finished editing.
;;
;; "snews" is port 563 and is predefined 
;; in our /etc/services
;;
(nntp "snews.bar.com"
      (nntp-open-connection-function 
        nntp-open-ssl-stream)
      (nntp-port-number "snews")
      (nntp-address "snews.bar.com"))
@end lisp

Reading mail with a newsreader---isn't that just plain WeIrD? But of
course.

@menu
* Mail in a Newsreader::         Important introductory notes.  
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail::               How to create mail groups.
* Mail Sources::                 How to tell Gnus where to get mail from.
* Mail Back End Variables::      Variables for customizing mail handling.
* Fancy Mail Splitting::         Gnus can do hairy splitting of incoming mail.

@node Mail in a Newsreader
@subsection Mail in a Newsreader

If you are used to traditional mail readers, but have decided to switch 
to reading mail with Gnus, you may find yourself experiencing something
of a culture shock.

Gnus does not behave like traditional mail readers.  If you want to make 
it behave that way, you can, but it's an uphill battle.

Gnus, by default, handles all its groups using the same approach.  This
approach is very newsreaderly---you enter a group, see the new/unread
messages, and when you read the messages, they get marked as read, and

Does this mean that all the messages that have been marked as read are
deleted?  How awful!

But, no, it means that old messages are @dfn{expired} according to some
scheme or other.  For news messages, the expire process is controlled by 
the news administrator; for mail, the expire process is controlled by
you.  The expire process for mail is covered in depth in @pxref{Expiring
Mail}.

What many Gnus users find, after using it a while for both news and

@kindex nnmail-split-history
If you wish to see where the previous mail split put the messages, you
can use the @kbd{M-x nnmail-split-history} command.  If you wish to see
where re-spooling messages would put the messages, you can use
@code{gnus-summary-respool-trace} and related commands (@pxref{Mail
Group Commands}). 

Gnus gives you all the opportunity you could possibly want for shooting
yourself in the foot.  Let's say you create a group that will contain
all the mail you get from your boss.  And then you accidentally
unsubscribe from the group.  Gnus will still put all the mail from your

@lisp
(file)
@end lisp

If the mail spool file is not located on the local machine, it's best to 
use POP or @sc{imap} or the like to fetch the mail.  You can not use ange-ftp 
file names here---it has no way to lock the mail spool while moving the
mail.

If it's impossible to set up a proper server, you can use ssh instead.

@end table

Two example maildir mail sources:

@lisp
(maildir :path "/home/user-name/Maildir/" 
         :subdirs ("cur" "new"))
@end lisp

@lisp
(maildir :path "/user@@remotehost.org:~/Maildir/" 
         :subdirs ("new"))
@end lisp

@item imap
Get mail from a @sc{imap} server.  If you don't want to use @sc{imap}

@end table

An example @sc{imap} mail source:

@lisp
(imap :server "mail.mycorp.com" 
      :stream kerberos4 
      :fetchflag "\\Seen")
@end lisp

@item webmail
Get mail from a webmail server, such as www.hotmail.com,

@end table

An example webmail source:

@lisp
(webmail :subtype 'hotmail 
         :user "user-name" 
         :password "secret")
@end lisp
@end table

@table @dfn

If non-nil, fetch the mail even when Gnus is unplugged.  If you use
directory source to get mail, you can specify it as in this example:

@lisp
(setq mail-sources
      '((directory :path "/home/pavel/.Spool/" 
                   :suffix ""
                   :plugged t)))
@end lisp

Gnus will then fetch your mail even when you are unplugged.  This is

         ("subject" "ding" "ding.misc"))
      ;; Other mailing lists...
      (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
      (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
      ;; Both lists below have the same suffix, so prevent
      ;; cross-posting to mkpkg.list of messages posted only to 
      ;; the bugs- list, but allow cross-posting when the
      ;; message was really cross-posted.
      (any "bugs-mypackage@@somewhere" "mypkg.bugs")
      (any "mypackage@@somewhere\" - "bugs-mypackage" "mypkg.list")
      ;; People...

method described above) on a per-group basis.  That is, @code{nnmbox}
itself puts *all* one's mail in one file; @code{nnfolder} provides a
little bit of optimization to this so that each of one's mail groups has
a Unix mail box file.  It's faster than @code{nnmbox} because each group
can be parsed separately, and still provides the simple Unix mail box
format requiring minimal effort in moving the mail around.  In addition, 
it maintains an ``active'' file making it much faster for Gnus to figure 
out how many messages there are in each separate group.

If you have groups that are expected to have a massive amount of
messages, @code{nnfolder} is not the best choice, but if you receive
only a moderate amount of mail, @code{nnfolder} is probably the most

is easy to understand---they are friendly to new users; you just point
and click, and there's the discussion.  With mailing lists, you have to
go through a cumbersome subscription procedure, and most people don't
even know what a news group is.

The problem with this scenario is that web browsers are not very good at 
being newsreaders.  They do not keep track of what articles you've read; 
they do not allow you to score on subjects you're interested in; they do 
not allow off-line browsing; they require you to click around and drive
you mad in the end.

So---if web browsers suck at reading discussion forums, why not use Gnus 
to do it instead?

Gnus has been getting a bit of a collection of back ends for providing
interfaces to these sources.

@end menu

All the web sources require Emacs/w3 and the url library to work.

The main caveat with all these web sources is that they probably won't
work for a very long time.  Gleaning information from the @sc{html} data 
is guesswork at best, and when the layout is altered, the Gnus back end
will fail.  If you have reasonably new versions of these back ends,
though, you should be ok.

One thing all these Web methods have in common is that the Web sources

probably the most popular Web bulletin board system used.  It has a
quite regular and nice interface, and it's possible to get the
information Gnus needs to keep groups updated.

The easiest way to get started with @code{nnultimate} is to say
something like the following in the group buffer:  @kbd{B nnultimate @key{RET} 
http://www.tcj.com/messboard/ubbcgi/ @key{RET}}.  (Substitute the @sc{url}
(not including @samp{Ultimate.cgi} or the like at the end) for a forum
you're interested in; there's quite a list of them on the Ultimate web
site.)  Then subscribe to the groups you're interested in from the
server buffer, and read them from the group buffer.

@cindex w3
@cindex html
@cindex url
@cindex Netscape

Gnus uses the url library to fetch web pages and Emacs/w3 to display web 
pages.  Emacs/w3 is documented in its own manual, but there are some
things that may be more relevant for Gnus users.

For instance, a common question is how to make Emacs/w3 follow links
using the @code{browse-url} functions (which will call some external web 
browser like Netscape).  Here's one way:

@lisp
(eval-after-load "w3"
  '(progn

Here's an example:

@lisp
(setq gnus-post-method
      '(nngateway 
        "mail2news@@replay.com"
        (nngateway-header-transformation
         nngateway-mail2news-header-transformation)))
@end lisp

A server configuration in @code{~/.gnus} with a few @sc{imap} servers
might look something like this:

@lisp
(setq gnus-secondary-select-methods 
      '((nnimap "simpleserver") ; no special configuration
        ; perhaps a ssh port forwarded server:
        (nnimap "dolk"
                (nnimap-address "localhost")
                (nnimap-server-port 1430))

Example server specification:

@lisp
(nnimap "mail.server.com"
        (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" 
                               ("~friend/Mail/" . "list/*"))))
@end lisp

@item nnimap-stream
@vindex nnimap-stream

matching the regexp in the second element in the sublist.  Got that?
Neither did I, we need examples.

@lisp
(setq nnimap-split-rule
      '(("INBOX.nnimap"  
         "^Sender: owner-nnimap@@vic20.globalcom.se")
        ("INBOX.junk"    "^Subject:.*MAKE MONEY")
        ("INBOX.private" "")))
@end lisp

returned is the local score file.  Phu.

For example, to do hierarchical scoring but use a non-server-specific
overall score file, you could use the value
@example
(list (lambda (group) ("all.SCORE")) 
      'gnus-score-find-hierarchical)
@end example

@item gnus-score-expiry-days
@vindex gnus-score-expiry-days

@item Multiple crossposts
If you want to lower the score of articles that have been crossposted to
more than, say, 3 groups:
@lisp
("xref" 
  ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+"
   -1000 nil r))
@end lisp

@item Matching on the body

One common desire for a multiple frame split is to have a separate frame
for composing mail and news while leaving the original frame intact.  To
accomplish that, something like the following can be done:

@lisp
(message 
  (frame 1.0
         (if (not (buffer-live-p gnus-summary-buffer))
             (car (cdr (assoc 'group gnus-buffer-configuration)))
           (car (cdr (assoc 'summary gnus-buffer-configuration))))
         (vertical ((user-position . t) (top . 1) (left . 1)

windows resized.

@subsection Example Window Configurations

@itemize @bullet
@item 
Narrow left hand side occupied by group buffer.  Right hand side split
between summary buffer (top one-sixth) and article buffer (bottom).

@ifinfo
@example

@findex gnus-undo-mode
@vindex gnus-use-undo
@findex gnus-undo
The undoability is provided by the @code{gnus-undo-mode} minor mode.  It
is used if @code{gnus-use-undo} is non-@code{nil}, which is the
default.  The @kbd{C-M-_} key performs the @code{gnus-undo} 
command, which should feel kinda like the normal Emacs @code{undo}
command.


@node Moderation

On September 13th 1997, Quassia Gnus was started and lasted 37 releases.
If was released as ``Gnus 5.6'' on March 8th 1998 (46 releases).

Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as
``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd
1999. 

If you happen upon a version of Gnus that has a prefixed name --
``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' --
don't panic.  Don't let it know that you're frightened.  Back away.
Slowly.  Whatever you do, don't run.  Walk away, calmly, until you're

(setq nnmail-spool-file 'procmail)
(setq nnmail-procmail-directory "~/mail/incoming/")
(setq nnmail-procmail-suffix "\\.in")
@end lisp

this now has changed to 

@lisp
(setq mail-sources
      '((directory :path "~/mail/incoming/"
		   :suffix ".in")))

of variables starting with @code{gnus-treat-} have been added.

@item The Gnus posting styles have been redone again and now works in a
subtly different manner.

@item New web-based back ends have been added: @code{nnslashdot}, 
@code{nnwarchive} and @code{nnultimate}.  nnweb has been revamped,
again, to keep up with ever-changing layouts.

@item Gnus can now read IMAP mail via @code{nnimap}.

I guess most manuals are written after-the-fact; documenting a program
that's already there.  This is not how this manual is written.  When
implementing something, I write the manual entry for that something
straight away.  I then see that it's difficult to explain the
functionality, so I write how it's supposed to be, and then I change the 
implementation.  Writing the documentation and writing the code goes
hand in hand.

This, of course, means that this manual has no, or little, flow.  It
documents absolutely everything in Gnus, but often not where you're
looking for it.  It is a reference manual, and not a guide to how to get 
started with Gnus.

That would be a totally different book, that should be written using the 
reference manual as source material.  It would look quite differently.


@page
@node Terminology

(defvoo nndir-nov-is-evil nil
  "*Non-nil means that nndir will never retrieve NOV headers."
  nnml-nov-is-evil)

(defvoo nndir-current-group "" 
  nil 
  nnml-current-group nnmh-current-group)
(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)

(defvoo nndir-status-string "" nil nnmh-status-string)

        (or (cadr (assq 'nndir-directory defs))
            server))
  (unless (assq 'nndir-directory defs)
    (push `(nndir-directory ,server) defs))
  (push `(nndir-current-group
          ,(file-name-nondirectory 
            (directory-file-name nndir-directory)))
        defs)
  (push `(nndir-top-directory
          ,(file-name-directory (directory-file-name nndir-directory)))
        defs)

49600:23a1cea22d13

* NNTP::               Reading news from an @sc{nntp} server.
* News Spool::         Reading news from the local spool.

Getting Mail

* Mail in a Newsreader::         Important introductory notes.
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail::               How to create mail groups.
* Mail Sources::                 How to tell Gnus where to get mail from.
* Mail Back End Variables::      Variables for customizing mail handling.
* Fancy Mail Splitting::         Gnus can do hairy splitting of incoming mail.

@vindex gnus-subscribe-killed
Kill all new groups.

@item gnus-subscribe-topics
@vindex gnus-subscribe-topics
Put the groups into the topic that has a matching @code{subscribe} topic
parameter (@pxref{Topic Parameters}).  For instance, a @code{subscribe}
topic parameter that looks like

@example
"nnslashdot"
@end example

will mean that all groups that match that regex will be subscribed under
that topic.

If no topics match the groups, the groups will be subscribed in the
top-level topic.

read all the replies in one swoop.  This will normally result in better
performance, but if the server does not support the aforementioned
@code{LIST ACTIVE group} command, this isn't very nice to the server.

If you think that starting up Gnus takes too long, try all the three
different values for this variable and see what works best for you.

In any case, if you use @code{some} or @code{nil}, you should definitely
kill all groups that you aren't interested in to speed things up.

Note that this variable also affects active file retrieval from

Elements that look like @code{(ignored-charsets x-known iso-8859-1)}
will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the
default charset will be used for decoding articles.

See also @code{gnus-group-ignored-charsets-alist}.

@item posting-style
You can store additional posting style information for this group only
here (@pxref{Posting Styles}).  The format is that of an entry in the
@code{gnus-posting-styles} alist, except that there's no regexp matching
the group name (of course).  Style elements in this group parameter will

convention (@pxref{Process/Prefix}).

@item T j
@kindex T j (Topic)
@findex gnus-topic-jump-to-topic
Go to a topic (@code{gnus-topic-jump-to-topic}).

@item T c
@kindex T c (Topic)
@findex gnus-topic-copy-group
Copy the current group to some other topic

In addition, the following parameters are only valid as topic
parameters:

@table @code
@item subscribe
When subscribing new groups by topic (@pxref{Subscription Methods}), the
@code{subscribe} topic parameter says what groups go in what topic.  Its
value should be a regexp to match the groups that should go in that
topic.

@end table

Group parameters (of course) override topic parameters, and topic
parameters in sub-topics override topic parameters in super-topics.  You

    '(((nntp "news.com.cn") . cn-gb-2312)))
@end lisp

@item gnus-group-name-charset-group-alist
@vindex gnus-group-name-charset-group-alist
An alist of regexp of group name and the charset for group names.
It is used to show non-ASCII group names.

For example:
@lisp
(setq gnus-group-name-charset-group-alist

If given a numerical prefix, you can do semi-manual charset stuff.
@kbd{C-u 0 g cn-gb-2312 @key{RET}} will decode the message as if it were
encoded in the @code{cn-gb-2312} charset.  If you have

@lisp
(setq gnus-summary-show-article-charset-alist
      '((1 . cn-gb-2312)
        (2 . big5)))
@end lisp

then you can say @kbd{C-u 1 g} to get the same effect.

@item S o p
@kindex S o p @r{(Summary)}
@findex gnus-summary-post-forward
Forward the current article to a newsgroup
(@code{gnus-summary-post-forward}).
 If no prefix is given, the message is forwarded according to the value
of (@code{message-forward-as-mime}) and
(@code{message-forward-show-mml}); if the prefix is 1, decode the
message and forward directly inline; if the prefix is 2, forward message
as an rfc822 MIME section; if the prefix is 3, decode message and

If you'd like to save articles in a hierarchy that looks something like
a spool, you could

@lisp
(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
(setq gnus-default-article-saver
      'gnus-summary-save-in-file) ; no encoding
@end lisp

Then just save with @kbd{o}.  You'd then read this hierarchy with
ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and

You can give the command a numerical prefix to specify the width to use
when filling.

@item W Q
@kindex W Q @r{(Summary)}
@findex gnus-article-fill-long-lines
Fill long lines (@code{gnus-article-fill-long-lines}).

@item W C
@kindex W C @r{(Summary)}
@findex gnus-article-capitalize-sentences

makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}.

@item W h
@kindex W h @r{(Summary)}
@findex gnus-article-wash-html
Treat HTML (@code{gnus-article-wash-html}).
Note that the this is usually done automatically by Gnus if the message
in question has a @code{Content-Type} header that says that this type
has been done.

@item W f

@table @kbd
@item A t
@kindex A t @r{(Summary)}
@findex gnus-article-babel
Translate the article from one language to another
(@code{gnus-article-babel}).

@end table


@node MIME Commands

@cindex move mail
@findex gnus-summary-move-article
@vindex gnus-preserve-marks
Move the article from one mail group to another
(@code{gnus-summary-move-article}).  Marks will be preserved if
@var{gnus-preserve-marks} is non-@code{nil} (which is the default).

@item B c
@kindex B c @r{(Summary)}
@cindex copy mail
@findex gnus-summary-copy-article

(@code{gnus-mime-copy-part}).

@findex gnus-mime-view-part-as-type
@item t @r{(Article)}
View the @sc{mime} object as if it were a different @sc{mime} media type
(@code{gnus-mime-view-part-as-type}).

@findex gnus-mime-pipe-part
@item | @r{(Article)}
Output the @sc{mime} object to a process (@code{gnus-mime-pipe-part}).

@vindex gnus-part-display-hook
You can, of course, write your own functions to be called from
@code{gnus-part-display-hook}.  The functions are called narrowed to the
part, and you can do anything you like, pretty much.  There is no
information that you have to keep in the buffer---you can change
everything.


@node Article Keymap
@section Article Keymap

@enumerate
@item
The file contains one or more line, each of which define one server.

@item
Each line may contain an arbitrary number of token/value pairs.

The valid tokens include @samp{machine}, @samp{login}, @samp{password},
@samp{default}.  In addition Gnus introduces two new tokens, not present
in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and
@samp{force}.  (This is the only way the @file{.authinfo} file format

The default value is

@lisp
'(("nntpd 1\\.5\\.11t"
   (remove-hook 'nntp-server-opened-hook
                'nntp-send-mode-reader)))
@end lisp

This ensures that Gnus doesn't send the @code{MODE READER} command to
nntpd 1.5.11t, since that command chokes that server, I've been told.

define a server as follows:

@lisp
;; Type `C-c C-c' after you've finished editing.
;;
;; "snews" is port 563 and is predefined
;; in our /etc/services
;;
(nntp "snews.bar.com"
      (nntp-open-connection-function
        nntp-open-ssl-stream)
      (nntp-port-number "snews")
      (nntp-address "snews.bar.com"))
@end lisp

Reading mail with a newsreader---isn't that just plain WeIrD? But of
course.

@menu
* Mail in a Newsreader::         Important introductory notes.
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail::               How to create mail groups.
* Mail Sources::                 How to tell Gnus where to get mail from.
* Mail Back End Variables::      Variables for customizing mail handling.
* Fancy Mail Splitting::         Gnus can do hairy splitting of incoming mail.

@node Mail in a Newsreader
@subsection Mail in a Newsreader

If you are used to traditional mail readers, but have decided to switch
to reading mail with Gnus, you may find yourself experiencing something
of a culture shock.

Gnus does not behave like traditional mail readers.  If you want to make
it behave that way, you can, but it's an uphill battle.

Gnus, by default, handles all its groups using the same approach.  This
approach is very newsreaderly---you enter a group, see the new/unread
messages, and when you read the messages, they get marked as read, and

Does this mean that all the messages that have been marked as read are
deleted?  How awful!

But, no, it means that old messages are @dfn{expired} according to some
scheme or other.  For news messages, the expire process is controlled by
the news administrator; for mail, the expire process is controlled by
you.  The expire process for mail is covered in depth in @pxref{Expiring
Mail}.

What many Gnus users find, after using it a while for both news and

@kindex nnmail-split-history
If you wish to see where the previous mail split put the messages, you
can use the @kbd{M-x nnmail-split-history} command.  If you wish to see
where re-spooling messages would put the messages, you can use
@code{gnus-summary-respool-trace} and related commands (@pxref{Mail
Group Commands}).

Gnus gives you all the opportunity you could possibly want for shooting
yourself in the foot.  Let's say you create a group that will contain
all the mail you get from your boss.  And then you accidentally
unsubscribe from the group.  Gnus will still put all the mail from your

@lisp
(file)
@end lisp

If the mail spool file is not located on the local machine, it's best to
use POP or @sc{imap} or the like to fetch the mail.  You can not use ange-ftp
file names here---it has no way to lock the mail spool while moving the
mail.

If it's impossible to set up a proper server, you can use ssh instead.

@end table

Two example maildir mail sources:

@lisp
(maildir :path "/home/user-name/Maildir/"
         :subdirs ("cur" "new"))
@end lisp

@lisp
(maildir :path "/user@@remotehost.org:~/Maildir/"
         :subdirs ("new"))
@end lisp

@item imap
Get mail from a @sc{imap} server.  If you don't want to use @sc{imap}

@end table

An example @sc{imap} mail source:

@lisp
(imap :server "mail.mycorp.com"
      :stream kerberos4
      :fetchflag "\\Seen")
@end lisp

@item webmail
Get mail from a webmail server, such as www.hotmail.com,

@end table

An example webmail source:

@lisp
(webmail :subtype 'hotmail
         :user "user-name"
         :password "secret")
@end lisp
@end table

@table @dfn

If non-nil, fetch the mail even when Gnus is unplugged.  If you use
directory source to get mail, you can specify it as in this example:

@lisp
(setq mail-sources
      '((directory :path "/home/pavel/.Spool/"
                   :suffix ""
                   :plugged t)))
@end lisp

Gnus will then fetch your mail even when you are unplugged.  This is

         ("subject" "ding" "ding.misc"))
      ;; Other mailing lists...
      (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list")
      (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list")
      ;; Both lists below have the same suffix, so prevent
      ;; cross-posting to mkpkg.list of messages posted only to
      ;; the bugs- list, but allow cross-posting when the
      ;; message was really cross-posted.
      (any "bugs-mypackage@@somewhere" "mypkg.bugs")
      (any "mypackage@@somewhere\" - "bugs-mypackage" "mypkg.list")
      ;; People...

method described above) on a per-group basis.  That is, @code{nnmbox}
itself puts *all* one's mail in one file; @code{nnfolder} provides a
little bit of optimization to this so that each of one's mail groups has
a Unix mail box file.  It's faster than @code{nnmbox} because each group
can be parsed separately, and still provides the simple Unix mail box
format requiring minimal effort in moving the mail around.  In addition,
it maintains an ``active'' file making it much faster for Gnus to figure
out how many messages there are in each separate group.

If you have groups that are expected to have a massive amount of
messages, @code{nnfolder} is not the best choice, but if you receive
only a moderate amount of mail, @code{nnfolder} is probably the most

is easy to understand---they are friendly to new users; you just point
and click, and there's the discussion.  With mailing lists, you have to
go through a cumbersome subscription procedure, and most people don't
even know what a news group is.

The problem with this scenario is that web browsers are not very good at
being newsreaders.  They do not keep track of what articles you've read;
they do not allow you to score on subjects you're interested in; they do
not allow off-line browsing; they require you to click around and drive
you mad in the end.

So---if web browsers suck at reading discussion forums, why not use Gnus
to do it instead?

Gnus has been getting a bit of a collection of back ends for providing
interfaces to these sources.

@end menu

All the web sources require Emacs/w3 and the url library to work.

The main caveat with all these web sources is that they probably won't
work for a very long time.  Gleaning information from the @sc{html} data
is guesswork at best, and when the layout is altered, the Gnus back end
will fail.  If you have reasonably new versions of these back ends,
though, you should be ok.

One thing all these Web methods have in common is that the Web sources

probably the most popular Web bulletin board system used.  It has a
quite regular and nice interface, and it's possible to get the
information Gnus needs to keep groups updated.

The easiest way to get started with @code{nnultimate} is to say
something like the following in the group buffer:  @kbd{B nnultimate @key{RET}
http://www.tcj.com/messboard/ubbcgi/ @key{RET}}.  (Substitute the @sc{url}
(not including @samp{Ultimate.cgi} or the like at the end) for a forum
you're interested in; there's quite a list of them on the Ultimate web
site.)  Then subscribe to the groups you're interested in from the
server buffer, and read them from the group buffer.

@cindex w3
@cindex html
@cindex url
@cindex Netscape

Gnus uses the url library to fetch web pages and Emacs/w3 to display web
pages.  Emacs/w3 is documented in its own manual, but there are some
things that may be more relevant for Gnus users.

For instance, a common question is how to make Emacs/w3 follow links
using the @code{browse-url} functions (which will call some external web
browser like Netscape).  Here's one way:

@lisp
(eval-after-load "w3"
  '(progn

Here's an example:

@lisp
(setq gnus-post-method
      '(nngateway
        "mail2news@@replay.com"
        (nngateway-header-transformation
         nngateway-mail2news-header-transformation)))
@end lisp

A server configuration in @code{~/.gnus} with a few @sc{imap} servers
might look something like this:

@lisp
(setq gnus-secondary-select-methods
      '((nnimap "simpleserver") ; no special configuration
        ; perhaps a ssh port forwarded server:
        (nnimap "dolk"
                (nnimap-address "localhost")
                (nnimap-server-port 1430))

Example server specification:

@lisp
(nnimap "mail.server.com"
        (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
                               ("~friend/Mail/" . "list/*"))))
@end lisp

@item nnimap-stream
@vindex nnimap-stream

matching the regexp in the second element in the sublist.  Got that?
Neither did I, we need examples.

@lisp
(setq nnimap-split-rule
      '(("INBOX.nnimap"
         "^Sender: owner-nnimap@@vic20.globalcom.se")
        ("INBOX.junk"    "^Subject:.*MAKE MONEY")
        ("INBOX.private" "")))
@end lisp

returned is the local score file.  Phu.

For example, to do hierarchical scoring but use a non-server-specific
overall score file, you could use the value
@example
(list (lambda (group) ("all.SCORE"))
      'gnus-score-find-hierarchical)
@end example

@item gnus-score-expiry-days
@vindex gnus-score-expiry-days

@item Multiple crossposts
If you want to lower the score of articles that have been crossposted to
more than, say, 3 groups:
@lisp
("xref"
  ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+"
   -1000 nil r))
@end lisp

@item Matching on the body

One common desire for a multiple frame split is to have a separate frame
for composing mail and news while leaving the original frame intact.  To
accomplish that, something like the following can be done:

@lisp
(message
  (frame 1.0
         (if (not (buffer-live-p gnus-summary-buffer))
             (car (cdr (assoc 'group gnus-buffer-configuration)))
           (car (cdr (assoc 'summary gnus-buffer-configuration))))
         (vertical ((user-position . t) (top . 1) (left . 1)

windows resized.

@subsection Example Window Configurations

@itemize @bullet
@item
Narrow left hand side occupied by group buffer.  Right hand side split
between summary buffer (top one-sixth) and article buffer (bottom).

@ifinfo
@example

@findex gnus-undo-mode
@vindex gnus-use-undo
@findex gnus-undo
The undoability is provided by the @code{gnus-undo-mode} minor mode.  It
is used if @code{gnus-use-undo} is non-@code{nil}, which is the
default.  The @kbd{C-M-_} key performs the @code{gnus-undo}
command, which should feel kinda like the normal Emacs @code{undo}
command.


@node Moderation

On September 13th 1997, Quassia Gnus was started and lasted 37 releases.
If was released as ``Gnus 5.6'' on March 8th 1998 (46 releases).

Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as
``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd
1999.

If you happen upon a version of Gnus that has a prefixed name --
``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' --
don't panic.  Don't let it know that you're frightened.  Back away.
Slowly.  Whatever you do, don't run.  Walk away, calmly, until you're

(setq nnmail-spool-file 'procmail)
(setq nnmail-procmail-directory "~/mail/incoming/")
(setq nnmail-procmail-suffix "\\.in")
@end lisp

this now has changed to

@lisp
(setq mail-sources
      '((directory :path "~/mail/incoming/"
		   :suffix ".in")))

of variables starting with @code{gnus-treat-} have been added.

@item The Gnus posting styles have been redone again and now works in a
subtly different manner.

@item New web-based back ends have been added: @code{nnslashdot},
@code{nnwarchive} and @code{nnultimate}.  nnweb has been revamped,
again, to keep up with ever-changing layouts.

@item Gnus can now read IMAP mail via @code{nnimap}.

I guess most manuals are written after-the-fact; documenting a program
that's already there.  This is not how this manual is written.  When
implementing something, I write the manual entry for that something
straight away.  I then see that it's difficult to explain the
functionality, so I write how it's supposed to be, and then I change the
implementation.  Writing the documentation and writing the code goes
hand in hand.

This, of course, means that this manual has no, or little, flow.  It
documents absolutely everything in Gnus, but often not where you're
looking for it.  It is a reference manual, and not a guide to how to get
started with Gnus.

That would be a totally different book, that should be written using the
reference manual as source material.  It would look quite differently.


@page
@node Terminology

(defvoo nndir-nov-is-evil nil
  "*Non-nil means that nndir will never retrieve NOV headers."
  nnml-nov-is-evil)

(defvoo nndir-current-group ""
  nil
  nnml-current-group nnmh-current-group)
(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)

(defvoo nndir-status-string "" nil nnmh-status-string)

        (or (cadr (assq 'nndir-directory defs))
            server))
  (unless (assq 'nndir-directory defs)
    (push `(nndir-directory ,server) defs))
  (push `(nndir-current-group
          ,(file-name-nondirectory
            (directory-file-name nndir-directory)))
        defs)
  (push `(nndir-top-directory
          ,(file-name-directory (directory-file-name nndir-directory)))
        defs)