@direntry
* Gnus: (gnus). The newsreader Gnus.
@end direntry
+@documentencoding ISO-8859-1
@iftex
@finalout
@end iftex
\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Gnus v5.10.2}
+\newcommand{\gnusversionname}{Gnus v5.10.6}
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}
\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}}
\newcommand{\gnuscode}[1]{\gnustt{#1}}
+\newcommand{\gnusasis}[1]{\gnustt{#1}}
+\newcommand{\gnusurl}[1]{\gnustt{#1}}
\newcommand{\gnuscommand}[1]{\gnustt{#1}}
\newcommand{\gnusenv}[1]{\gnustt{#1}}
\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''}
}
}{\end{list}}
+\newenvironment{asislist}%
+{\begin{list}{}{
+}
+}{\end{list}}
+
\newenvironment{kbdlist}%
{\begin{list}{}{
\labelwidth=0cm
\thispagestyle{empty}
Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
-2002, 2003
+2002, 2003, 2004
Free Software Foundation, Inc.
This file documents Gnus, the GNU Emacs newsreader.
-Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
+Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@vskip 0pt plus 1filll
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001,
-2002, 2003
+2002, 2003, 2004
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
spool or your mbox file. All at the same time, if you want to push your
luck.
-This manual corresponds to Gnus v5.10.2.
+This manual corresponds to Gnus v5.10.6.
@end ifinfo
* Emacs-MIME:(emacs-mime). Composing messages; @acronym{MIME}-specific parts.
* Sieve:(sieve). Managing Sieve scripts in Emacs.
* PGG:(pgg). @acronym{PGP/MIME} with Gnus.
+* SASL:(sasl). @acronym{SASL} authentication in Emacs.
@detailmenu
--- The Detailed Node Listing ---
* Unread Articles:: Marks for unread articles.
* Read Articles:: Marks for read articles.
* Other Marks:: Marks that do not affect readedness.
-* Setting Marks:: How to set and remove marks.
-* Generic Marking Commands:: How to customize the marking.
-* Setting Process Marks:: How to mark articles for later processing.
+
+Marking Articles
+
+* Setting Marks:: How to set and remove marks.
+* Generic Marking Commands:: How to customize the marking.
+* Setting Process Marks:: How to mark articles for later processing.
Threading
* Mail:: Mailing and replying.
* Posting Server:: What server should you post and mail via?
+* POP before SMTP:: You cannot send a mail unless you read a mail.
* Mail and Post:: Mailing and posting at the same time.
* Archived Messages:: Where Gnus stores the messages you've sent.
* Posting Styles:: An easier way to specify who you are.
* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
+* Debugging IMAP:: What to do when things don't work.
Other Sources
* Global Score Files:: Earth-spanning, ear-splitting score files.
* Kill Files:: They are still here, but they can be ignored.
* Converting Kill Files:: Translating kill files to score files.
-* GroupLens:: Getting predictions on what you like to read.
* Advanced Scoring:: Using logical expressions to build score rules.
* Score Decays:: It can be useful to let scores wither away.
-GroupLens
-
-* Using GroupLens:: How to make Gnus use GroupLens.
-* Rating Articles:: Letting GroupLens know how you rate articles.
-* Displaying Predictions:: Displaying predictions given by GroupLens.
-* GroupLens Variables:: Customizing GroupLens.
-
Advanced Scoring
* Advanced Scoring Syntax:: A definition.
* Image Enhancements:: Modern versions of Emacs/XEmacs can display images.
* Fuzzy Matching:: What's the big fuzz?
* Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email.
+* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
Formatting Variables
Filtering Spam Using The Spam ELisp Package
-* Blacklists and Whitelists::
-* BBDB Whitelists::
-* Gmane Spam Reporting::
-* Anti-spam Hashcash Payments::
-* Blackholes::
-* Regular Expressions Header Matching::
-* Bogofilter::
-* ifile spam filtering::
-* spam-stat spam filtering::
-* SpamOracle::
-* Extending the spam elisp package::
+* Spam ELisp Package Sequence of Events::
+* Spam ELisp Package Filtering of Incoming Mail::
+* Spam ELisp Package Global Variables::
+* Spam ELisp Package Configuration Examples::
+* Blacklists and Whitelists::
+* BBDB Whitelists::
+* Gmane Spam Reporting::
+* Anti-spam Hashcash Payments::
+* Blackholes::
+* Regular Expressions Header Matching::
+* Bogofilter::
+* SpamAssassin backend::
+* ifile spam filtering::
+* spam-stat spam filtering::
+* SpamOracle::
+* Extending the Spam ELisp package::
Filtering Spam Using Statistics with spam-stat
* Troubleshooting:: What you might try if things do not work.
* Gnus Reference Guide:: Rilly, rilly technical stuff.
* Emacs for Heathens:: A short introduction to Emacsian terms.
-* Frequently Asked Questions:: The Gnus FAQ.
+* Frequently Asked Questions:: The Gnus FAQ
History
* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7.
* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9.
* Oort Gnus:: It's big. It's far out. Gnus 5.10.
+* No Gnus:: Lars, FIXME!
Customization
@vindex gnus-auto-subscribed-groups
Yet another variable that meddles here is
@code{gnus-auto-subscribed-groups}. It works exactly like
-@code{gnus-options-subscribe}, and is therefore really superfluous, but I
-thought it would be nice to have two of these. This variable is more
-meant for setting some ground rules, while the other variable is used
-more for user fiddling. By default this variable makes all new groups
-that come from mail back ends (@code{nnml}, @code{nnbabyl},
+@code{gnus-options-subscribe}, and is therefore really superfluous,
+but I thought it would be nice to have two of these. This variable is
+more meant for setting some ground rules, while the other variable is
+used more for user fiddling. By default this variable makes all new
+groups that come from mail back ends (@code{nnml}, @code{nnbabyl},
@code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir})
subscribed. If you don't like that, just set this variable to
@code{nil}.
A string that says when you last read the group (@pxref{Group
Timestamp}).
+@item F
+The disk space used by the articles fetched by both the cache and
+agent. The value is automatically scaled to bytes(B), kilobytes(K),
+megabytes(M), or gigabytes(G) to minimize the column width. A format
+of %7F is sufficient for a fixed-width column.
+
@item u
User defined specifier. The next character in the format string should
be a letter. Gnus will call the function
for a name, a method and possibly an @dfn{address}. For an easier way
to subscribe to @acronym{NNTP} groups (@pxref{Browse Foreign Server}).
+@item G M
+@kindex G M (Group)
+@findex gnus-group-read-ephemeral-group
+Make an ephemeral group (@code{gnus-group-read-ephemeral-group}). Gnus
+will prompt you for a name, a method and an @dfn{address}.
+
@item G r
@kindex G r (Group)
@findex gnus-group-rename-group
to a particular group by using a match string like
@samp{shaving group:alt.sysadmin.recovery}.
+@item G R
+@kindex G R (Group)
+@findex gnus-group-make-rss-group
+Make a group based on an @acronym{RSS} feed
+(@code{gnus-group-make-rss-group}). You will be prompted for an URL.
+@xref{RSS}.
+
@item G DEL
@kindex G DEL (Group)
@findex gnus-group-delete-group
actually delete all the articles in the group, and forcibly remove the
group itself from the face of the Earth. Use a prefix only if you are
absolutely sure of what you are doing. This command can't be used on
-read-only groups (like @code{nntp} group), though.
+read-only groups (like @code{nntp} groups), though.
@item G V
@kindex G V (Group)
sending the message if @code{gnus-add-to-list} is set to @code{t}.
@vindex gnus-add-to-list
-If you do an @kbd{a} command in a mail group and you don't have a
-@code{to-list} group parameter, one will be added automatically upon
-sending the message.
-
@findex gnus-mailing-list-mode
@cindex mail list groups
If this variable is set, @code{gnus-mailing-list-mode} is turned on when
@anchor{subscribed}
@item subscribed
@cindex subscribed
+@cindex Mail-Followup-To
+@findex gnus-find-subscribed-addresses
If this parameter is set to @code{t}, Gnus will consider the
to-address and to-list parameters for this group as addresses of
mailing lists you are subscribed to. Giving Gnus this information is
(only) a first step in getting it to generate correct Mail-Followup-To
-headers for your posts to these lists. @xref{Mailing Lists, ,Mailing
-Lists, message, The Message Manual}, for a complete treatment of
-available MFT support.
+headers for your posts to these lists. The second step is to put the
+following in your @file{.gnus.el}
+
+@lisp
+(setq message-subscribed-address-functions
+ '(gnus-find-subscribed-addresses))
+@end lisp
-See also @code{gnus-find-subscribed-addresses}, the function that
-directly uses this group parameter.
+@xref{Mailing Lists, ,Mailing Lists, message, The Message Manual}, for
+a complete treatment of available MFT support.
@item visible
@cindex visible
precedence over any default @code{Gcc} rules as described later
(@pxref{Archived Messages}).
-@strong{Caveat}: It yields an error putting @code{(gcc-self . t)} in
-groups of an @code{nntp} server or so, because an @code{nntp} server
+@strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of
+@code{nntp} groups (or the like) isn't valid. An @code{nntp} server
doesn't accept articles.
@item auto-expire
The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve,
Top, sieve, Emacs Sieve}.
+@item (agent parameters)
+If the agent has been enabled, you can set any of the its parameters
+to control the behavior of the agent in individual groups. See Agent
+Parameters in @ref{Category Syntax}. Most users will choose to set
+agent parameters in either an agent category or group topic to
+minimize the configuration effort.
+
@item (@var{variable} @var{form})
You can use the group parameters to set variables local to the group you
are entering. If you want to turn threading off in @samp{news.answers},
the group by putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")}
into the group parameters for the group.
-This can also be used as a group-specific hook function, if you'd like.
-If you want to hear a beep when you enter a group, you could put
-something like @code{(dummy-variable (ding))} in the parameters of that
-group. @code{dummy-variable} will be set to the result of the
-@code{(ding)} form, but who cares?
+This can also be used as a group-specific hook function. If you want to
+hear a beep when you enter a group, you could put something like
+@code{(dummy-variable (ding))} in the parameters of that group.
+@code{dummy-variable} will be set to the (meaningless) result of the
+@code{(ding)} form.
+
+Alternatively, since the VARIABLE becomes local to the group, this
+pattern can be used to temporarily change a hook. For example, if the
+following is added to a group parameter
+
+@lisp
+(gnus-summary-prepared-hook
+ '(lambda nil (local-set-key "d" (local-key-binding "n"))))
+@end lisp
+
+when the group is entered, the 'd' key will not mark the article as
+expired.
@end table
(@code{gnus-topic-sort-groups-by-server}).
@item T S s
-@kindex T S s
+@kindex T S s (Topic)
@findex gnus-topic-sort-groups
Sort the current topic according to the function(s) given by the
@code{gnus-group-sort-function} variable
@subsection Topic Parameters
@cindex topic parameters
-All groups in a topic will inherit group parameters from the parent (and
-ancestor) topic parameters. All valid group parameters are valid topic
-parameters (@pxref{Group Parameters}).
+All groups in a topic will inherit group parameters from the parent
+(and ancestor) topic parameters. All valid group parameters are valid
+topic parameters (@pxref{Group Parameters}). When the agent is
+enabled, all agent parameters (See Agent Parameters in @ref{Category
+Syntax}) are also valid topic parameters.
In addition, the following parameters are only valid as topic
parameters:
verb, although you may feel free to disagree with me here.)
@example
+@group
Gnus
Emacs
3: comp.emacs
8: comp.binaries.fractals
13: comp.sources.unix
452: alt.sex.emacs
+@end group
@end example
The @samp{Emacs} topic has the topic parameter @code{(score-file
This command understands the process/prefix convention
(@pxref{Process/Prefix}).
+@item S D e
+@kindex S D e (Summary)
+@findex gnus-summary-resend-message-edit
+
+Like the previous command, but will allow you to edit the message as
+if it were a new message before resending.
+
@item S O m
@kindex S O m (Summary)
@findex gnus-uu-digest-mail-forward
want to use the standard posting method, use the @samp{a} symbolic
prefix (@pxref{Symbolic Prefixes}).
+Gnus ensures that only you can cancel your own messages using a
+@code{Cancel-Lock} header (@pxref{Canceling News, Canceling News, ,
+message, Message Manual}).
+
If you discover that you have made some mistakes and want to do some
corrections, you can post a @dfn{superseding} article that will replace
your original article.
Mark articles in region (@code{gnus-uu-mark-region}).
@item M P g
-@kindex M P g
+@kindex M P g (Summary)
@findex gnus-uu-unmark-region
Unmark articles in region (@code{gnus-uu-unmark-region}).
(@code{gnus-summary-limit-to-display-predicate}). @xref{Group
Parameters}, for more on this predicate.
+@item / r
+@kindex / r (Summary)
+@findex gnus-summary-limit-to-replied
+Limit the summary buffer to replied articles
+(@code{gnus-summary-limit-to-replied}). If given a prefix, exclude
+replied articles.
+
@item / E
@itemx M S
@kindex M S (Summary)
@item gnus-fetch-old-headers
@vindex gnus-fetch-old-headers
If non-@code{nil}, Gnus will attempt to build old threads by fetching
-more old headers---headers to articles marked as read. If you
-would like to display as few summary lines as possible, but still
-connect as many loose threads as possible, you should set this variable
-to @code{some} or a number. If you set it to a number, no more than
-that number of extra old headers will be fetched. In either case,
-fetching old headers only works if the back end you are using carries
-overview files---this would normally be @code{nntp}, @code{nnspool},
+more old headers---headers to articles marked as read. If you would
+like to display as few summary lines as possible, but still connect as
+many loose threads as possible, you should set this variable to
+@code{some} or a number. If you set it to a number, no more than that
+number of extra old headers will be fetched. In either case, fetching
+old headers only works if the back end you are using carries overview
+files---this would normally be @code{nntp}, @code{nnspool},
@code{nnml}, and @code{nnmaildir}. Also remember that if the root of
-the thread has been expired by the server, there's not much Gnus can do
-about that.
+the thread has been expired by the server, there's not much Gnus can
+do about that.
This variable can also be set to @code{invisible}. This won't have any
visible effects, but is useful if you use the @kbd{A T} command a lot
Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
Quoted-Printable is one common @acronym{MIME} encoding employed when
sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically
-makes strings like @samp{déjà vu} look like @samp{d=E9j=E0 vu}, which
-doesn't look very readable to me. Note that this is usually done
-automatically by Gnus if the message in question has a
+makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu},
+which doesn't look very readable to me. Note that this is usually
+done automatically by Gnus if the message in question has a
@code{Content-Transfer-Encoding} header that says that this encoding
has been done. If a prefix is given, a charset will be asked for.
common encoding employed when sending Chinese articles. It typically
makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}.
+@item W A
+@kindex W A (Summary)
+@findex gnus-article-treat-ansi-sequences
+@cindex @acronym{ANSI} control sequences
+Translate @acronym{ANSI} SGR control sequences into overlays or
+extents (@code{gnus-article-treat-ansi-sequences}). @acronym{ANSI}
+sequences are used in some Chinese hierarchies for highlighting.
+
@item W u
@kindex W u (Summary)
@findex gnus-article-unsplit-urls
(@code{gnus-article-treat-fold-headers}).
@item W E w
-@kindex W E w
+@kindex W E w (Summary)
@findex gnus-article-remove-leading-whitespace
Remove excessive whitespace from all headers
(@code{gnus-article-remove-leading-whitespace}).
@item gnus-mime-multipart-functions
Alist of @acronym{MIME} multipart types and functions to handle them.
+@vindex gnus-mime-display-multipart-alternative-as-mixed
+@item gnus-mime-display-multipart-alternative-as-mixed
+Display "multipart/alternative" parts as "multipart/mixed".
+
+@vindex gnus-mime-display-multipart-related-as-mixed
+@item gnus-mime-display-multipart-related-as-mixed
+Display "multipart/related" parts as "multipart/mixed".
+
+If displaying "text/html" is discouraged, see
+@code{mm-discouraged-alternatives} in @ref{Display Customization,
+Display Customization, , emacs-mime, Emacs-Mime Manual}. Images or
+other material inside a "multipart/related" part might be overlooked
+when this variable is nil.
+
+@vindex gnus-mime-display-multipart-as-mixed
+@item gnus-mime-display-multipart-as-mixed
+Display "multipart" parts as "multipart/mixed". If t, it overrides nil
+values of @code{gnus-mime-display-multipart-alternative-as-mixed} and
+@code{gnus-mime-display-multipart-related-as-mixed}.
+
@vindex mm-file-name-rewrite-functions
@item mm-file-name-rewrite-functions
List of functions used for rewriting file names of @acronym{MIME} parts.
@cindex coding system aliases
@cindex preferred charset
+@xref{Encoding Customization, , Encoding Customization, emacs-mime,
+The Emacs MIME Manual}, for additional variables that control which
+MIME charsets are used when sending messages.
+
Other charset tricks that may be useful, although not Gnus-specific:
If there are several @acronym{MIME} charsets that encode the same Emacs
Most of the mail back ends support fetching by @code{Message-ID}, but
do not do a particularly excellent job at it. That is, @code{nnmbox},
-@code{nnbabyl}, and @code{nnmaildir} are able to locate articles from
-any groups, while @code{nnml}, @code{nnfolder}, and @code{nnimap} are
-only able to locate articles that have been posted to the current group.
-(Anything else would be too time consuming.) @code{nnmh} does not
-support this at all.
+@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate
+articles from any groups, while @code{nnfolder}, and @code{nnimap} are
+only able to locate articles that have been posted to the current
+group. (Anything else would be too time consuming.) @code{nnmh} does
+not support this at all.
@node Alternative Approaches
@vindex gnus-newsgroup-variables
@item gnus-newsgroup-variables
A list of newsgroup (summary buffer) local variables, or cons of
-variables and their default values (when the default values are not
-@code{nil}), that should be made global while the summary buffer is
-active. These variables can be used to set variables in the group
-parameters while still allowing them to affect operations done in
-other buffers. For example:
+variables and their default expressions to be evalled (when the default
+values are not @code{nil}), that should be made global while the summary
+buffer is active.
+
+Note: The default expressions will be evaluated (using function
+@code{eval}) before assignment to the local variable rather than just
+assigned to it. If the default expression is the symbol @code{global},
+that symbol will not be evaluated but the global value of the local
+variable will be used instead.
+
+These variables can be used to set variables in the group parameters
+while still allowing them to affect operations done in other
+buffers. For example:
@lisp
(setq gnus-newsgroup-variables
"^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:")))
@end lisp
+Also @pxref{Group Parameters}.
@end table
@table @kbd
@item Z Z
+@itemx Z Q
@itemx q
@kindex Z Z (Summary)
+@kindex Z Q (Summary)
@kindex q (Summary)
@findex gnus-summary-exit
@vindex gnus-summary-exit-hook
(@code{gnus-summary-catchup-and-goto-next-group}).
@item Z R
+@itemx C-x C-s
@kindex Z R (Summary)
+@kindex C-x C-s (Summary)
@findex gnus-summary-reselect-current-group
Exit this group, and then enter it again
(@code{gnus-summary-reselect-current-group}). If given a prefix, select
@item C-c C-n a
@kindex C-c C-n a (Summary)
-@findex gnus-mailing-list-owner
+@findex gnus-mailing-list-archive
Browse the mailing list archive, if List-Archive field exists.
@end table
You can hide further boring headers by setting
@code{gnus-treat-hide-boring-headers} to @code{head}. What this function
does depends on the @code{gnus-boring-article-headers} variable. It's a
-list, but this list doesn't actually contain header names. Instead is
+list, but this list doesn't actually contain header names. Instead it
lists various @dfn{boring conditions} that Gnus can check and remove
from sight.
Remove the @code{Followup-To} header if it is identical to the
@code{Newsgroups} header.
@item reply-to
-Remove the @code{Reply-To} header if it lists the same address as the
-@code{From} header, or if the @code{broken-reply-to} group parameter is
-set.
+Remove the @code{Reply-To} header if it lists the same addresses as
+the @code{From} header, or if the @code{broken-reply-to} group
+parameter is set.
@item newsgroups
Remove the @code{Newsgroups} header if it only contains the current group
name.
@item gnus-treat-play-sounds
@item gnus-treat-translate
+@item gnus-treat-ansi-sequences (t)
@item gnus-treat-x-pgp-sig (head)
@item gnus-treat-unfold-headers (head)
@vindex gnus-article-mode-line-format
@item gnus-article-mode-line-format
This variable is a format string along the same lines as
-@code{gnus-summary-mode-line-format} (@pxref{Mode Line Formatting}). It
-accepts the same format specifications as that variable, with two
-extensions:
+@code{gnus-summary-mode-line-format} (@pxref{Summary Buffer Mode
+Line}). It accepts the same format specifications as that variable,
+with two extensions:
@table @samp
@menu
* Mail:: Mailing and replying.
* Posting Server:: What server should you post and mail via?
+* POP before SMTP:: You cannot send a mail unless you read a mail.
* Mail and Post:: Mailing and posting at the same time.
* Archived Messages:: Where Gnus stores the messages you've sent.
* Posting Styles:: An easier way to specify who you are.
@end lisp
To the thing similar to this, there is
-@code{message-smtpmail-send-it}. It is useful if your ISP requires
-the @acronym{POP}-before-@acronym{SMTP} authentication. See the
-documentation for the function @code{mail-source-touch-pop}.
+@code{message-smtpmail-send-it}. It is useful if your @acronym{ISP}
+requires the @acronym{POP}-before-@acronym{SMTP} authentication.
+@xref{POP before SMTP}.
Other possible choices for @code{message-send-mail-function} includes
@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail},
and @code{feedmail-send-it}.
+@node POP before SMTP
+@section POP before SMTP
+@cindex pop before smtp
+@findex message-smtpmail-send-it
+@findex mail-source-touch-pop
+
+Does your @acronym{ISP} require the @acronym{POP}-before-@acronym{SMTP}
+authentication? It is whether you need to connect to the @acronym{POP}
+mail server within a certain time before sending mails. If so, there is
+a convenient way. To do that, put the following lines in your
+@file{~/.gnus.el} file:
+
+@lisp
+(setq message-send-mail-function 'message-smtpmail-send-it)
+(add-hook 'message-send-mail-hook 'mail-source-touch-pop)
+@end lisp
+
+@noindent
+It means to let Gnus connect to the @acronym{POP} mail server in advance
+whenever you send a mail. The @code{mail-source-touch-pop} function
+does only a @acronym{POP} authentication according to the value of
+@code{mail-sources} without fetching mails, just before sending a mail.
+Note that you have to use @code{message-smtpmail-send-it} which runs
+@code{message-send-mail-hook} rather than @code{smtpmail-send-it} and
+set the value of @code{mail-sources} for a @acronym{POP} connection
+correctly. @xref{Mail Sources}.
+
+If you have two or more @acronym{POP} mail servers set in
+@code{mail-sources}, you may want to specify one of them to
+@code{mail-source-primary-source} as the @acronym{POP} mail server to be
+used for the @acronym{POP}-before-@acronym{SMTP} authentication. If it
+is your primary @acronym{POP} mail server (i.e., you are fetching mails
+mainly from that server), you can set it permanently as follows:
+
+@lisp
+(setq mail-source-primary-source
+ '(pop :server "pop3.mail.server"
+ :password "secret"))
+@end lisp
+
+@noindent
+Otherwise, bind it dynamically only when performing the
+@acronym{POP}-before-@acronym{SMTP} authentication as follows:
+
+@lisp
+(add-hook 'message-send-mail-hook
+ (lambda ()
+ (let ((mail-source-primary-source
+ '(pop :server "pop3.mail.server"
+ :password "secret")))
+ (mail-source-touch-pop))))
+@end lisp
+
@node Mail and Post
@section Mail and Post
@code{gnus-message-replysignencrypted} (on by default) will sign
automatically encrypted messages.
-Instructing MML to perform security operations on a @acronym{MIME} part is
-done using the @kbd{C-c C-m s} key map for signing and the @kbd{C-c
-C-m c} key map for encryption, as follows.
+Instructing @acronym{MML} to perform security operations on a
+@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for
+signing and the @kbd{C-c C-m c} key map for encryption, as follows.
@table @kbd
@item C-c C-m s s
-@kindex C-c C-m s s
+@kindex C-c C-m s s (Message)
@findex mml-secure-message-sign-smime
Digitally sign current message using @acronym{S/MIME}.
@item C-c C-m s o
-@kindex C-c C-m s o
+@kindex C-c C-m s o (Message)
@findex mml-secure-message-sign-pgp
Digitally sign current message using @acronym{PGP}.
@item C-c C-m s p
-@kindex C-c C-m s p
+@kindex C-c C-m s p (Message)
@findex mml-secure-message-sign-pgp
Digitally sign current message using @acronym{PGP/MIME}.
@item C-c C-m c s
-@kindex C-c C-m c s
+@kindex C-c C-m c s (Message)
@findex mml-secure-message-encrypt-smime
Digitally encrypt current message using @acronym{S/MIME}.
@item C-c C-m c o
-@kindex C-c C-m c o
+@kindex C-c C-m c o (Message)
@findex mml-secure-message-encrypt-pgp
Digitally encrypt current message using @acronym{PGP}.
@item C-c C-m c p
-@kindex C-c C-m c p
+@kindex C-c C-m c p (Message)
@findex mml-secure-message-encrypt-pgpmime
Digitally encrypt current message using @acronym{PGP/MIME}.
@item C-c C-m C-n
-@kindex C-c C-m C-n
+@kindex C-c C-m C-n (Message)
@findex mml-unsecure-message
-Remove security related MML tags from message.
+Remove security related @acronym{MML} tags from message.
@end table
host.
@end table
+Note that you may want to change the value for @code{nntp-end-of-line}
+to @samp{\n} (@pxref{Common Variables}).
+
+@item nntp-open-via-rlogin-and-netcat
+@findex nntp-open-via-rlogin-and-netcat
+Does essentially the same, but uses
+@uref{http://netcat.sourceforge.net/, netcat} instead of @samp{telnet}
+to connect to the real @acronym{NNTP} server from the intermediate host.
+
+@code{nntp-open-via-rlogin-and-netcat}-specific variables:
+
+@table @code
+@item nntp-via-netcat-command
+@vindex nntp-via-netcat-command
+Command used to connect to the real @acronym{NNTP} server from the
+intermediate host. The default is @samp{nc}. You can also use other
+programs like @uref{http://www.imasy.or.jp/~gotoh/ssh/connect.html,
+connect} instead.
+
+@item nntp-via-netcat-switches
+@vindex nntp-via-netcat-switches
+List of strings to be used as the switches to the
+@code{nntp-via-telnet-command} command. The default is @code{nil}.
+
+@item nntp-via-rlogin-command
+@vindex nntp-via-rlogin-command
+Command used to log in on the intermediate host. The default is
+@samp{rsh}, but @samp{ssh} is a popular alternative.
+
+@item nntp-via-rlogin-command-switches
+@vindex nntp-via-rlogin-command-switches
+List of strings to be used as the switches to
+@code{nntp-via-rlogin-command}. The default is @code{nil}.
+@end table
+
@item nntp-open-via-telnet-and-telnet
@findex nntp-open-via-telnet-and-telnet
-Does essentially the same, but uses @samp{telnet} instead of
+Does essentially also the same, but uses @samp{telnet} instead of
@samp{rlogin} to connect to the intermediate host.
@code{nntp-open-via-telnet-and-telnet}-specific variables:
@end table
+Note that you may want to change the value for @code{nntp-end-of-line}
+to @samp{\n} (@pxref{Common Variables}).
@end table
@vindex nntp-end-of-line
String to use as end-of-line marker when talking to the @acronym{NNTP}
server. This is @samp{\r\n} by default, but should be @samp{\n} when
-using a non native connection function.
+using a non native telnet connection function.
@item nntp-telnet-command
@vindex nntp-telnet-command
@end lisp
@item webmail
-Get mail from a webmail server, such as @uref{www.hotmail.com},
-@uref{webmail.netscape.com}, @uref{www.netaddress.com},
-@uref{mail.yahoo.com}.
+Get mail from a webmail server, such as @uref{http://www.hotmail.com/},
+@uref{http://webmail.netscape.com/}, @uref{http://www.netaddress.com/},
+@uref{http://mail.yahoo.com/}.
-NOTE: Webmail largely depends cookies. A "one-line-cookie" patch is
+NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is
required for url "4.0pre.46".
WARNING: Mails may be lost. NO WARRANTY.
@lisp
(defun split-on-body ()
(save-excursion
- (widen)
- (goto-char (point-min))
- (when (re-search-forward "Some.*string" nil t)
- "string.group")))
+ (save-restriction
+ (widen)
+ (goto-char (point-min))
+ (when (re-search-forward "Some.*string" nil t)
+ "string.group"))))
@end lisp
The buffer is narrowed to the message in question when @var{function}
is run. That's why @code{(widen)} needs to be called after
-@code{save-excursion} in the example above. Also note that with the
-nnimap backend, message bodies will not be downloaded by default. You
-need to set @code{nnimap-split-download-body} to t to do that
+@code{save-excursion} and @code{save-restriction} in the example
+above. Also note that with the nnimap backend, message bodies will
+not be downloaded by default. You need to set
+@code{nnimap-split-download-body} to @code{t} to do that
(@pxref{Splitting in IMAP}).
@item (! @var{func} @var{split})
up to @samp{\\9} will be substituted with the text matched by the
groupings 1 through 9.
+@vindex nnmail-split-fancy-match-partial-words
+@code{nnmail-split-fancy-match-partial-words} controls whether partial
+words are matched during fancy splitting.
+
+Normally, regular expressions given in @code{nnmail-split-fancy} are
+implicitly surrounded by @code{\<...\>} markers, which are word
+delimiters. If this variable is true, they are not implicitly
+surrounded by anything.
+
+@example
+(any "joe" "joemail")
+@end example
+
+In this example, messages sent from @samp{joedavis@@foo.org} will
+normally not be filed in @samp{joemail}. With
+@code{nnmail-split-fancy-match-partial-words} set to t, however, the
+match will happen. In effect, the requirement of a word boundary is
+removed and instead the match becomes more like a grep.
+
@findex nnmail-split-fancy-with-parent
@code{nnmail-split-fancy-with-parent} is a function which allows you to
split followups into the same groups their parents are in. Sometimes
@findex gnus-group-split
If you subscribe to dozens of mailing lists but you don't want to
maintain mail splitting rules manually, group mail splitting is for you.
-You just have to set @var{to-list} and/or @var{to-address} in group
+You just have to set @code{to-list} and/or @code{to-address} in group
parameters or group customization and set @code{nnmail-split-methods} to
@code{gnus-group-split}. This splitting function will scan all groups
for those parameters and split mail accordingly, i.e., messages posted
-from or to the addresses specified in the parameters @var{to-list} or
-@var{to-address} of a mail group will be stored in that group.
+from or to the addresses specified in the parameters @code{to-list} or
+@code{to-address} of a mail group will be stored in that group.
Sometimes, mailing lists have multiple addresses, and you may want mail
-splitting to recognize them all: just set the @var{extra-aliases} group
+splitting to recognize them all: just set the @code{extra-aliases} group
parameter to the list of additional addresses and it's done. If you'd
-rather use a regular expression, set @var{split-regexp}.
+rather use a regular expression, set @code{split-regexp}.
All these parameters in a group will be used to create an
@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any},
the @var{value} is a single regular expression that matches
-@var{to-list}, @var{to-address}, all of @var{extra-aliases} and all
-matches of @var{split-regexp}, and the @var{split} is the name of the
+@code{to-list}, @code{to-address}, all of @code{extra-aliases} and all
+matches of @code{split-regexp}, and the @var{split} is the name of the
group. @var{restrict}s are also supported: just set the
-@var{split-exclude} parameter to a list of regular expressions.
+@code{split-exclude} parameter to a list of regular expressions.
If you can't get the right split to be generated using all these
parameters, or you just need something fancier, you can set the
-parameter @var{split-spec} to an @code{nnmail-split-fancy} split. In
+parameter @code{split-spec} to an @code{nnmail-split-fancy} split. In
this case, all other aforementioned parameters will be ignored by
-@code{gnus-group-split}. In particular, @var{split-spec} may be set to
+@code{gnus-group-split}. In particular, @code{split-spec} may be set to
@code{nil}, in which case the group will be ignored by
@code{gnus-group-split}.
by defining a single @code{&} fancy split containing one split for each
group. If a message doesn't match any split, it will be stored in the
group named in @code{gnus-group-split-default-catch-all-group}, unless
-some group has @var{split-spec} set to @code{catch-all}, in which case
+some group has @code{split-spec} set to @code{catch-all}, in which case
that group is used as the catch-all group. Even though this variable is
often used just to name a group, it may also be set to an arbitrarily
complex fancy split (after all, a group name is a fancy split), and this
parameters will be scanned to generate the output split.
@var{no-crosspost} can be used to disable cross-posting; in this case, a
single @code{|} split will be output. @var{catch-all} is the fall back
-fancy split, used like @var{gnus-group-split-default-catch-all-group}.
-If @var{catch-all} is @code{nil}, or if @var{split-regexp} matches the
+fancy split, used like @code{gnus-group-split-default-catch-all-group}.
+If @var{catch-all} is @code{nil}, or if @code{split-regexp} matches the
empty string in any selected group, no catch-all split will be issued.
-Otherwise, if some group has @var{split-spec} set to @code{catch-all},
+Otherwise, if some group has @code{split-spec} set to @code{catch-all},
this group will override the value of the @var{catch-all} argument.
@findex gnus-group-split-setup
@end table
@findex nnml-generate-nov-databases
-If your @code{nnml} groups and @acronym{NOV} files get totally out of whack,
-you can do a complete update by typing @kbd{M-x
+If your @code{nnml} groups and @acronym{NOV} files get totally out of
+whack, you can do a complete update by typing @kbd{M-x
nnml-generate-nov-databases}. This command will trawl through the
entire @code{nnml} hierarchy, looking at each and every article, so it
might take a while to complete. A better interface to this
@cindex mh-e mail spool
@code{nnmh} is just like @code{nnml}, except that is doesn't generate
-@acronym{NOV} databases and it doesn't keep an active file or marks file.
-This makes @code{nnmh} a @emph{much} slower back end than @code{nnml},
-but it also makes it easier to write procmail scripts for.
+@acronym{NOV} databases and it doesn't keep an active file or marks
+file. This makes @code{nnmh} a @emph{much} slower back end than
+@code{nnml}, but it also makes it easier to write procmail scripts
+for.
Virtual server settings:
@item nnmh-be-safe
@vindex nnmh-be-safe
If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make
-sure that the articles in the folder are actually what Gnus thinks they
-are. It will check date stamps and stat everything in sight, so
+sure that the articles in the folder are actually what Gnus thinks
+they are. It will check date stamps and stat everything in sight, so
setting this to @code{t} will mean a serious slow-down. If you never
-use anything but Gnus to read the @code{nnmh} articles, you do not have
-to set this variable to @code{t}. The default is @code{nil}.
+use anything but Gnus to read the @code{nnmh} articles, you do not
+have to set this variable to @code{t}. The default is @code{nil}.
@end table
@code{nnmaildir} stores mail in the maildir format, with each maildir
corresponding to a group in Gnus. This format is documented here:
@uref{http://cr.yp.to/proto/maildir.html} and here:
-@uref{http://www.qmail.org/man/man5/maildir.html}. nnmaildir also
-stores extra information in the @file{.nnmaildir/} directory within a
-maildir.
+@uref{http://www.qmail.org/man/man5/maildir.html}. @code{nnmaildir}
+also stores extra information in the @file{.nnmaildir/} directory
+within a maildir.
Maildir format was designed to allow concurrent deliveries and
reading, without needing locks. With other back ends, you would have
your mail delivered to a spool of some kind, and then you would
configure Gnus to split mail from that spool into your groups. You
-can still do that with nnmaildir, but the more common configuration is
-to have your mail delivered directly to the maildirs that appear as
-group in Gnus.
+can still do that with @code{nnmaildir}, but the more common
+configuration is to have your mail delivered directly to the maildirs
+that appear as group in Gnus.
-nnmaildir is designed to be perfectly reliable: @kbd{C-g} will never
-corrupt its data in memory, and @code{SIGKILL} will never corrupt its
-data in the filesystem.
+@code{nnmaildir} is designed to be perfectly reliable: @kbd{C-g} will
+never corrupt its data in memory, and @code{SIGKILL} will never
+corrupt its data in the filesystem.
-nnmaildir stores article marks and @acronym{NOV} data in each maildir. So you
-can copy a whole maildir from one Gnus setup to another, and you will
-keep your marks.
+@code{nnmaildir} stores article marks and @acronym{NOV} data in each
+maildir. So you can copy a whole maildir from one Gnus setup to
+another, and you will keep your marks.
Virtual server settings:
@table @code
@item directory
-For each of your nnmaildir servers (it's very unlikely that you'd need
-more than one), you need to create a directory and populate it with
-maildirs or symlinks to maildirs (and nothing else; do not choose a
-directory already used for other purposes). Each maildir will be
-represented in Gnus as a newsgroup on that server; the filename of the
-symlink will be the name of the group. Any filenames in the directory
-starting with @samp{.} are ignored. The directory is scanned when you
-first start Gnus, and each time you type @kbd{g} in the group buffer;
-if any maildirs have been removed or added, nnmaildir notices at these
-times.
+For each of your @code{nnmaildir} servers (it's very unlikely that
+you'd need more than one), you need to create a directory and populate
+it with maildirs or symlinks to maildirs (and nothing else; do not
+choose a directory already used for other purposes). Each maildir
+will be represented in Gnus as a newsgroup on that server; the
+filename of the symlink will be the name of the group. Any filenames
+in the directory starting with @samp{.} are ignored. The directory is
+scanned when you first start Gnus, and each time you type @kbd{g} in
+the group buffer; if any maildirs have been removed or added,
+@code{nnmaildir} notices at these times.
The value of the @code{directory} parameter should be a Lisp form
which is processed by @code{eval} and @code{expand-file-name} to get
optional; you must specify it. I don't recommend using
@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus
use that directory by default for various things, and may get confused
-if nnmaildir uses it too. @code{"~/.nnmaildir"} is a typical value.
+if @code{nnmaildir} uses it too. @code{"~/.nnmaildir"} is a typical
+value.
@item target-prefix
This should be a Lisp form which is processed by @code{eval} and
server is opened; the resulting string is used until the server is
closed.
-When you create a group on an nnmaildir server, the maildir is created
-with @code{target-prefix} prepended to its name, and a symlink
+When you create a group on an @code{nnmaildir} server, the maildir is
+created with @code{target-prefix} prepended to its name, and a symlink
pointing to that maildir is created, named with the plain group name.
So if @code{directory} is @code{"~/.nnmaildir"} and
@code{target-prefix} is @code{"../maildirs/"}, then when you create
-the group @code{foo}, nnmaildir will create
+the group @code{foo}, @code{nnmaildir} will create
@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create
@file{~/.nnmaildir/foo} as a symlink pointing to
@file{../maildirs/foo}.
value is @code{nil}.
Do @emph{not} use the same maildir both in @code{mail-sources} and as
-an nnmaildir group. The results might happen to be useful, but that
-would be by chance, not by design, and the results might be different
-in the future. If your split rules create new groups, remember to
-supply a @code{create-directory} server parameter.
+an @code{nnmaildir} group. The results might happen to be useful, but
+that would be by chance, not by design, and the results might be
+different in the future. If your split rules create new groups,
+remember to supply a @code{create-directory} server parameter.
@end table
@subsubsection Group parameters
-nnmaildir uses several group parameters. It's safe to ignore all
-this; the default behavior for nnmaildir is the same as the default
-behavior for other mail back ends: articles are deleted after one week,
-etc. Except for the expiry parameters, all this functionality is
-unique to nnmaildir, so you can ignore it if you're just trying to
-duplicate the behavior you already have with another back end.
+@code{nnmaildir} uses several group parameters. It's safe to ignore
+all this; the default behavior for @code{nnmaildir} is the same as the
+default behavior for other mail back ends: articles are deleted after
+one week, etc. Except for the expiry parameters, all this
+functionality is unique to @code{nnmaildir}, so you can ignore it if
+you're just trying to duplicate the behavior you already have with
+another back end.
If the value of any of these parameters is a vector, the first element
is evaluated as a Lisp form and the result is used, rather than the
@table @code
@item expire-age
-An integer specifying the minimum age, in seconds, of an article before
-it will be expired, or the symbol @code{never} to specify that
+An integer specifying the minimum age, in seconds, of an article
+before it will be expired, or the symbol @code{never} to specify that
articles should never be expired. If this parameter is not set,
-nnmaildir falls back to the usual
+@code{nnmaildir} falls back to the usual
@code{nnmail-expiry-wait}(@code{-function}) variables (overrideable by
the @code{expiry-wait}(@code{-function}) group parameters. If you
wanted a value of 3 days, you could use something like @code{[(* 3 24
-60 60)]}; nnmaildir will evaluate the form and use the result. An
-article's age is measured starting from the article file's
+60 60)]}; @code{nnmaildir} will evaluate the form and use the result.
+An article's age is measured starting from the article file's
modification time. Normally, this is the same as the article's
delivery time, but editing an article makes it younger. Moving an
article (other than via expiry) may also make an article younger.
@end example
and if it is not the name of the same group that the parameter belongs
to, then articles will be moved to the specified group during expiry
-before being deleted. @emph{If this is set to an nnmaildir group, the
-article will be just as old in the destination group as it was in the
-source group.} So be careful with @code{expire-age} in the
+before being deleted. @emph{If this is set to an @code{nnmaildir}
+group, the article will be just as old in the destination group as it
+was in the source group.} So be careful with @code{expire-age} in the
destination group. If this is set to the name of the same group that
the parameter belongs to, then the article is not expired at all. If
you use the vector form, the first element is evaluated once for each
article. So that form can refer to
@code{nnmaildir-article-file-name}, etc., to decide where to put the
-article. @emph{If this parameter is not set, nnmaildir does not fall
-back to the @code{expiry-target} group parameter or the
+article. @emph{If this parameter is not set, @code{nnmaildir} does
+not fall back to the @code{expiry-target} group parameter or the
@code{nnmail-expiry-target} variable.}
@item read-only
-If this is set to @code{t}, nnmaildir will treat the articles in this
-maildir as read-only. This means: articles are not renamed from
-@file{new/} into @file{cur/}; articles are only found in @file{new/},
-not @file{cur/}; articles are never deleted; articles cannot be
-edited. @file{new/} is expected to be a symlink to the @file{new/}
-directory of another maildir---e.g., a system-wide mailbox containing
-a mailing list of common interest. Everything in the maildir outside
-@file{new/} is @emph{not} treated as read-only, so for a shared
-mailbox, you do still need to set up your own maildir (or have write
-permission to the shared mailbox); your maildir just won't contain
-extra copies of the articles.
+If this is set to @code{t}, @code{nnmaildir} will treat the articles
+in this maildir as read-only. This means: articles are not renamed
+from @file{new/} into @file{cur/}; articles are only found in
+@file{new/}, not @file{cur/}; articles are never deleted; articles
+cannot be edited. @file{new/} is expected to be a symlink to the
+@file{new/} directory of another maildir---e.g., a system-wide mailbox
+containing a mailing list of common interest. Everything in the
+maildir outside @file{new/} is @emph{not} treated as read-only, so for
+a shared mailbox, you do still need to set up your own maildir (or
+have write permission to the shared mailbox); your maildir just won't
+contain extra copies of the articles.
@item directory-files
A function with the same interface as @code{directory-files}. It is
server's @code{directory-files} parameter.
@item distrust-Lines:
-If non-@code{nil}, nnmaildir will always count the lines of an
+If non-@code{nil}, @code{nnmaildir} will always count the lines of an
article, rather than use the @code{Lines:} header field. If
@code{nil}, the header field will be used if present.
@item always-marks
-A list of mark symbols, such as
-@code{['(read expire)]}. Whenever Gnus asks nnmaildir for
-article marks, nnmaildir will say that all articles have these
-marks, regardless of whether the marks stored in the filesystem
-say so. This is a proof-of-concept feature that will probably be
-removed eventually; it ought to be done in Gnus proper, or
-abandoned if it's not worthwhile.
+A list of mark symbols, such as @code{['(read expire)]}. Whenever
+Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will
+say that all articles have these marks, regardless of whether the
+marks stored in the filesystem say so. This is a proof-of-concept
+feature that will probably be removed eventually; it ought to be done
+in Gnus proper, or abandoned if it's not worthwhile.
@item never-marks
A list of mark symbols, such as @code{['(tick expire)]}. Whenever
-Gnus asks nnmaildir for article marks, nnmaildir will say that no
-articles have these marks, regardless of whether the marks stored in
-the filesystem say so. @code{never-marks} overrides
+Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will
+say that no articles have these marks, regardless of whether the marks
+stored in the filesystem say so. @code{never-marks} overrides
@code{always-marks}. This is a proof-of-concept feature that will
probably be removed eventually; it ought to be done in Gnus proper, or
abandoned if it's not worthwhile.
@item nov-cache-size
-An integer specifying the size of the @acronym{NOV} memory cache. To speed
-things up, nnmaildir keeps @acronym{NOV} data in memory for a limited number of
-articles in each group. (This is probably not worthwhile, and will
-probably be removed in the future.) This parameter's value is noticed
-only the first time a group is seen after the server is opened---i.e.,
-when you first start Gnus, typically. The @acronym{NOV} cache is never resized
-until the server is closed and reopened. The default is an estimate
-of the number of articles that would be displayed in the summary
-buffer: a count of articles that are either marked with @code{tick} or
-not marked with @code{read}, plus a little extra.
+An integer specifying the size of the @acronym{NOV} memory cache. To
+speed things up, @code{nnmaildir} keeps @acronym{NOV} data in memory
+for a limited number of articles in each group. (This is probably not
+worthwhile, and will probably be removed in the future.) This
+parameter's value is noticed only the first time a group is seen after
+the server is opened---i.e., when you first start Gnus, typically.
+The @acronym{NOV} cache is never resized until the server is closed
+and reopened. The default is an estimate of the number of articles
+that would be displayed in the summary buffer: a count of articles
+that are either marked with @code{tick} or not marked with
+@code{read}, plus a little extra.
@end table
@subsubsection Article identification
Articles are stored in the @file{cur/} subdirectory of each maildir.
Each article file is named like @code{uniq:info}, where @code{uniq}
-contains no colons. nnmaildir ignores, but preserves, the
+contains no colons. @code{nnmaildir} ignores, but preserves, the
@code{:info} part. (Other maildir readers typically use this part of
the filename to store marks.) The @code{uniq} part uniquely
identifies the article, and is used in various places in the
request the article in the summary buffer.
@subsubsection NOV data
-An article identified by @code{uniq} has its @acronym{NOV} data (used to
-generate lines in the summary buffer) stored in
+An article identified by @code{uniq} has its @acronym{NOV} data (used
+to generate lines in the summary buffer) stored in
@code{.nnmaildir/nov/uniq}. There is no
@code{nnmaildir-generate-nov-databases} function. (There isn't much
-need for it---an article's @acronym{NOV} data is updated automatically when the
-article or @code{nnmail-extra-headers} has changed.) You can force
-nnmaildir to regenerate the @acronym{NOV} data for a single article simply by
-deleting the corresponding @acronym{NOV} file, but @emph{beware}: this will also
-cause nnmaildir to assign a new article number for this article, which
-may cause trouble with @code{seen} marks, the Agent, and the cache.
+need for it---an article's @acronym{NOV} data is updated automatically
+when the article or @code{nnmail-extra-headers} has changed.) You can
+force @code{nnmaildir} to regenerate the @acronym{NOV} data for a
+single article simply by deleting the corresponding @acronym{NOV}
+file, but @emph{beware}: this will also cause @code{nnmaildir} to
+assign a new article number for this article, which may cause trouble
+with @code{seen} marks, the Agent, and the cache.
@subsubsection Article marks
An article identified by @code{uniq} is considered to have the mark
@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists.
-When Gnus asks nnmaildir for a group's marks, nnmaildir looks for such
-files and reports the set of marks it finds. When Gnus asks nnmaildir
-to store a new set of marks, nnmaildir creates and deletes the
-corresponding files as needed. (Actually, rather than create a new
-file for each mark, it just creates hard links to
-@file{.nnmaildir/markfile}, to save inodes.)
+When Gnus asks @code{nnmaildir} for a group's marks, @code{nnmaildir}
+looks for such files and reports the set of marks it finds. When Gnus
+asks @code{nnmaildir} to store a new set of marks, @code{nnmaildir}
+creates and deletes the corresponding files as needed. (Actually,
+rather than create a new file for each mark, it just creates hard
+links to @file{.nnmaildir/markfile}, to save inodes.)
You can invent new marks by creating a new directory in
@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from
your server, untar it later, and keep your marks. You can add and
remove marks yourself by creating and deleting mark files. If you do
-this while Gnus is running and your nnmaildir server is open, it's
-best to exit all summary buffers for nnmaildir groups and type @kbd{s}
-in the group buffer first, and to type @kbd{g} or @kbd{M-g} in the
-group buffer afterwards. Otherwise, Gnus might not pick up the
-changes, and might undo them.
+this while Gnus is running and your @code{nnmaildir} server is open,
+it's best to exit all summary buffers for @code{nnmaildir} groups and
+type @kbd{s} in the group buffer first, and to type @kbd{g} or
+@kbd{M-g} in the group buffer afterwards. Otherwise, Gnus might not
+pick up the changes, and might undo them.
@node Mail Folders
@cindex mbox folders
@cindex mail folders
-@code{nnfolder} is a back end for storing each mail group in a separate
-file. Each file is in the standard Un*x mbox format. @code{nnfolder}
-will add extra headers to keep track of article numbers and arrival
-dates.
+@code{nnfolder} is a back end for storing each mail group in a
+separate file. Each file is in the standard Un*x mbox format.
+@code{nnfolder} will add extra headers to keep track of article
+numbers and arrival dates.
@cindex self contained nnfolder servers
@cindex marks
proper @code{nnfolder} server) and have all your marks be preserved.
Marks for a group is usually stored in a file named as the mbox file
with @code{.mrk} concatenated to it (but see
-@code{nnfolder-marks-file-suffix}) within the @code{nnfolder} directory.
-Individual @code{nnfolder} groups are also possible to backup, use
-@kbd{G m} to restore the group (after restoring the backup into the
-@code{nnfolder} directory).
+@code{nnfolder-marks-file-suffix}) within the @code{nnfolder}
+directory. Individual @code{nnfolder} groups are also possible to
+backup, use @kbd{G m} to restore the group (after restoring the backup
+into the @code{nnfolder} directory).
Virtual server settings:
@table @code
@item nnfolder-directory
@vindex nnfolder-directory
-All the @code{nnfolder} mail boxes will be stored under this directory.
-The default is the value of @code{message-directory} (whose default is
-@file{~/Mail})
+All the @code{nnfolder} mail boxes will be stored under this
+directory. The default is the value of @code{message-directory}
+(whose default is @file{~/Mail})
@item nnfolder-active-file
@vindex nnfolder-active-file
@item nnfolder-get-new-mail
@vindex nnfolder-get-new-mail
-If non-@code{nil}, @code{nnfolder} will read incoming mail. The default
-is @code{t}
+If non-@code{nil}, @code{nnfolder} will read incoming mail. The
+default is @code{t}
@item nnfolder-save-buffer-hook
@vindex nnfolder-save-buffer-hook
@cindex backup files
Hook run before saving the folders. Note that Emacs does the normal
-backup renaming of files even with the @code{nnfolder} buffers. If you
-wish to switch this off, you could say something like the following in
-your @file{.emacs} file:
+backup renaming of files even with the @code{nnfolder} buffers. If
+you wish to switch this off, you could say something like the
+following in your @file{.emacs} file:
@lisp
(defun turn-off-backup ()
If the search engine changes its output substantially, @code{nnweb}
won't be able to parse it and will fail. One could hardly fault the Web
-providers if they were to do this---their @emph{raison d'être} is to
+providers if they were to do this---their @emph{raison d'@^etre} is to
make money off of advertisements, not to provide services to the
community. Since @code{nnweb} washes the ads off all the articles, one
might think that the providers might be somewhat miffed. We'll see.
When following up to @code{nnslashdot} comments (or posting new
comments), some light @acronym{HTML}izations will be performed. In
particular, text quoted with @samp{> } will be quoted with
-@code{blockquote} instead, and signatures will have @code{br} added to
+@samp{blockquote} instead, and signatures will have @samp{br} added to
the end of each line. Other than that, you can just write @acronym{HTML}
directly into the message buffer. Note that Slashdot filters out some
@acronym{HTML} forms.
@item nnslashdot-active-url
@vindex nnslashdot-active-url
-The @sc{url} format string that will be used to fetch the information on
-news articles and comments. The default is@*
+The @acronym{URL} format string that will be used to fetch the
+information on news articles and comments. The default is@*
@samp{http://slashdot.org/search.pl?section=&min=%d}.
@item nnslashdot-comments-url
@vindex nnslashdot-comments-url
-The @sc{url} format string that will be used to fetch comments. The
-default is
-@samp{http://slashdot.org/comments.pl?sid=%s&threshold=%d&commentsort=%d&mode=flat&startat=%d}.
+The @acronym{URL} format string that will be used to fetch comments.
@item nnslashdot-article-url
@vindex nnslashdot-article-url
-The @sc{url} format string that will be used to fetch the news article. The
-default is
+The @acronym{URL} format string that will be used to fetch the news
+article. The default is
@samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}.
@item nnslashdot-threshold
The easiest way to get started with @code{nnultimate} is to say
something like the following in the group buffer: @kbd{B nnultimate RET
-http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @sc{url}
+http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @acronym{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
@cindex nnrss
@cindex RSS
-Some sites have RDF site summary (RSS)
-@uref{http://purl.org/rss/1.0/spec}. It has a quite regular and nice
-interface, and it's possible to get the information Gnus needs to keep
-groups updated.
+Some web sites have an RDF Site Summary (@acronym{RSS}).
+@acronym{RSS} is a format for summarizing headlines from news related
+sites (such as BBC or CNN). But basically anything list-like can be
+presented as an @acronym{RSS} feed: weblogs, changelogs or recent
+changes to a wiki (e.g. @url{http://cliki.net/recent-changes.rdf}).
+
+@acronym{RSS} has a quite regular and nice interface, and it's
+possible to get the information Gnus needs to keep groups updated.
+
+@kindex G R (Summary)
+Use @kbd{G R} from the summary buffer to subscribe to a feed---you
+will be prompted for the location of the feed.
+
+An easy way to get started with @code{nnrss} is to say something like
+the following in the group buffer: @kbd{B nnrss RET y}, then
+subscribe to groups.
-The easiest way to get started with @code{nnrss} is to say something
-like the following in the group buffer: @kbd{B nnrss RET RET}, then
-subscribe groups.
+@cindex OPML
+You can also use the following commands to import and export your
+subscriptions from a file in @acronym{OPML} format (Outline Processor
+Markup Language).
+
+@defun nnrss-opml-import file
+Prompt for an @acronym{OPML} file, and subscribe to each feed in the
+file.
+@end defun
+
+@defun nnrss-opml-export
+Write your current @acronym{RSS} subscriptions to a buffer in
+@acronym{OPML} format.
+@end defun
The following @code{nnrss} variables can be altered:
The directory where @code{nnrss} stores its files. The default is
@file{~/News/rss/}.
+@item nnrss-use-local
+@vindex nnrss-use-local
+@findex nnrss-generate-download-script
+If you set @code{nnrss-use-local} to @code{t}, @code{nnrss} will read
+the feeds from local files in @code{nnrss-directory}. You can use
+the command @code{nnrss-generate-download-script} to generate a
+download script using @command{wget}.
@end table
The following code may be helpful, if you want to show the description in
* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus.
+* Debugging IMAP:: What to do when things don't work.
@end menu
@cindex editing imap acls
@cindex Access Control Lists
@cindex Editing @acronym{IMAP} ACLs
-@kindex G l
+@kindex G l (Group)
@findex gnus-group-nnimap-edit-acl
ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for
@cindex expunge
@cindex manual expunging
-@kindex G x
+@kindex G x (Group)
@findex gnus-group-nnimap-expunge
If you're using the @code{never} setting of @code{nnimap-expunge-on-close},
for more information on how to use the prefixes. They are a power
tool and should be used only if you are sure what the effects are.
+@node Debugging IMAP
+@subsection Debugging IMAP
+@cindex IMAP debugging
+@cindex protocol dump (IMAP)
+
+@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or
+@acronym{POP3}. Implementation bugs are not unlikely, and we do our
+best to fix them right away. If you encounter odd behaviour, chances
+are that either the server or Gnus is buggy.
+
+If you are familiar with network protocols in general, you will
+probably be able to extract some clues from the protocol dump of the
+exchanges between Gnus and the server. Even if you are not familiar
+with network protocols, when you include the protocol dump in
+@acronym{IMAP}-related bug reports you are helping us with data
+critical to solving the problem. Therefore, we strongly encourage you
+to include the protocol dump when reporting IMAP bugs in Gnus.
+
+
+@vindex imap-log
+Because the protocol dump, when enabled, generates lots of data, it is
+disabled by default. You can enable it by setting @code{imap-log} as
+follows:
+
+@lisp
+(setq imap-log t)
+@end lisp
+
+This instructs the @code{imap.el} package to log any exchanges with
+the server. The log is stored in the buffer @samp{*imap-log*}. Look
+for error messages, which sometimes are tagged with the keyword
+@code{BAD}---but when submitting a bug, make sure to include all the
+data.
+
@node Other Sources
@section Other Sources
reading news on a machine.
Setting up Gnus as an ``offline'' newsreader is quite simple. In
-fact, you don't even have to configure anything.
+fact, you don't have to configure anything as the agent is now enabled
+by default (@pxref{Agent Variables, gnus-agent}).
Of course, to use it as such, you have to learn a few new commands.
customizable variables. The complete list of agent parameters are
listed below.
+@cindex Agent Parameters
@table @code
-@item gnus-agent-cat-name
+@item agent-cat-name
The name of the category.
-@item gnus-agent-cat-groups
+@item agent-groups
The list of groups that are in this category.
-@item gnus-agent-cat-predicate
+@item agent-predicate
A predicate which (generally) gives a rough outline of which articles
are eligible for downloading; and
-@item gnus-agent-cat-score-file
+@item agent-score-file
a score rule which (generally) gives you a finer granularity when
deciding what articles to download. (Note that this @dfn{download
score} is not necessarily related to normal scores.)
-@item gnus-agent-cat-enable-expiration
+@item agent-enable-expiration
a boolean indicating whether the agent should expire old articles in
this group. Most groups should be expired to conserve disk space. In
fact, its probably safe to say that the gnus.* hierarchy contains the
only groups that should not be expired.
-@item gnus-agent-cat-days-until-old
+@item agent-days-until-old
an integer indicating the number of days that the agent should wait
before deciding that a read article is safe to expire.
-@item gnus-agent-cat-low-score
+@item agent-low-score
an integer that overrides the value of @code{gnus-agent-low-score}.
-@item gnus-agent-cat-high-score
+@item agent-high-score
an integer that overrides the value of @code{gnus-agent-high-score}.
-@item gnus-agent-cat-length-when-short
+@item agent-length-when-short
an integer that overrides the value of
@code{gnus-agent-short-article}.
-@item gnus-agent-cat-length-when-long
+@item agent-length-when-long
an integer that overrides the value of @code{gnus-agent-long-article}.
+
+@item agent-enable-undownloaded-faces
+a symbol indicating whether the summary buffer should display
+undownloaded articles using the @code{gnus-summary-*-undownloaded-face}
+faces. Any symbol other than @code{nil} will enable the use of
+undownloaded faces.
@end table
The name of a category can not be changed once the category has been
each time you visit it or to minimize your connection time), the
undownloaded face will probably seem like a good idea. The reason
being that you do all of our work (marking, reading, deleting) with
-downloaded articles so the normal faces always appear.
-
-For occasional Agent users, the undownloaded faces may appear to be an
-absolutely horrible idea. The issue being that, since most of their
-articles have not been fetched into the Agent, most of the normal
-faces will be obscured by the undownloaded faces. If this is your
-situation, you have two choices available. First, you can completely
-disable the undownload faces by customizing
-@code{gnus-summary-highlight} to delete the three cons-cells that
-refer to the @code{gnus-summary-*-undownloaded-face} faces. Second, if
-you prefer to take a more fine-grained approach, you may set the
-@code{agent-disable-undownloaded-faces} group parameter to t. This
-parameter, like all other agent parameters, may be set on an Agent
-Category (@pxref{Agent Categories}), a Group Topic (@pxref{Topic
-Parameters}), or an individual group (@pxref{Group Parameters}).
+downloaded articles so the normal faces always appear. For those
+users using the agent to improve online performance by caching the NOV
+database (most users since 5.10.2), the undownloaded faces may appear
+to be an absolutely horrible idea. The issue being that, since none
+of their articles have been fetched into the Agent, all of the
+normal faces will be obscured by the undownloaded faces.
+
+If you would like to use the undownloaded faces, you must enable the
+undownloaded faces by setting the @code{agent-enable-undownloaded-faces}
+group parameter to t. This parameter, like all other agent
+parameters, may be set on an Agent Category (@pxref{Agent
+Categories}), a Group Topic (@pxref{Topic Parameters}), or an
+individual group (@pxref{Group Parameters}).
+
+The one problem common to all users using the agent is how quickly it
+can consume disk space. If you using the agent on many groups, it is
+even more difficult to effectively recover disk space. One solution
+is the @samp{%F} format available in @code{gnus-group-line-format}.
+This format will display the actual disk space used by articles
+fetched into both the agent and cache. By knowing which groups use
+the most space, users know where to focus their efforts when ``agent
+expiring'' articles.
@node Agent as Cache
@subsection Agent as Cache
@node Outgoing Messages
@subsection Outgoing Messages
-When Gnus is unplugged, all outgoing messages (both mail and news) are
-stored in the draft group ``queue'' (@pxref{Drafts}). You can view
-them there after posting, and edit them at will.
+By default, when Gnus is unplugged, all outgoing messages (both mail
+and news) are stored in the draft group ``queue'' (@pxref{Drafts}).
+You can view them there after posting, and edit them at will.
-When Gnus is plugged again, you can send the messages either from the
-draft group with the special commands available there, or you can use
-the @kbd{J S} command in the group buffer to send all the sendable
-messages in the draft group.
+You can control the circumstances under which outgoing mail is queued
+(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing
+news is always queued when Gnus is unplugged, and never otherwise.
+You can send the messages either from the draft group with the special
+commands available there, or you can use the @kbd{J S} command in the
+group buffer to send all the sendable messages in the draft group.
+Posting news will only work when Gnus is plugged, but you can send
+mail at any time.
+If sending mail while unplugged does not work for you and you worry
+about hitting @kbd{J S} by accident when unplugged, you can have Gnus
+ask you to confirm your action (see
+@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}).
@node Agent Variables
@subsection Agent Variables
@table @code
+@item gnus-agent
+@vindex gnus-agent
+Is the agent enabled? The default is @code{t}. When first enabled,
+the agent will use @code{gnus-agent-auto-agentize-methods} to
+automatically mark some backends as agentized. You may change which
+backends are agentized using the agent commands in the server buffer.
+
+To enter the server buffer, use the @kbd{^}
+(@code{gnus-group-enter-server-mode}) command in the group buffer.
+
+
@item gnus-agent-directory
@vindex gnus-agent-directory
Where the Gnus Agent will store its files. The default is
@item gnus-agent-consider-all-articles
@vindex gnus-agent-consider-all-articles
If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the
-agent will fetch all missing headers. When @code{nil}, the agent will
-fetch only new headers. The default is @code{nil}.
+agent will let the agent predicate decide whether articles need to be
+downloaded or not, for all articles. When @code{nil}, the default,
+the agent will only let the predicate decide whether unread articles
+are downloaded or not. If you enable this, you may also want to look
+into the agent expiry settings (@pxref{Category Variables}), so that
+the agent doesn't download articles which the agent will later expire,
+over and over again.
@item gnus-agent-max-fetch-size
@vindex gnus-agent-max-fetch-size
ignores articles that have not been fetched), @code{unfetched}
(maneuvering ignores articles whose headers have not been fetched).
+@item gnus-agent-queue-mail
+@vindex gnus-agent-queue-mail
+When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always
+queue mail rather than sending it straight away. When @code{t}, Gnus
+will queue mail when unplugged only. When @code{nil}, never queue
+mail. The default is @code{t}.
+
+@item gnus-agent-prompt-send-queue
+@vindex gnus-agent-prompt-send-queue
+When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will
+prompt you to confirm that you really wish to proceed if you hit
+@kbd{J S} while unplugged. The default is @code{nil}.
+
+@item gnus-agent-auto-agentize-methods
+@vindex gnus-agent-auto-agentize-methods
+If you have never used the Agent before (or more technically, if
+@file{~/News/agent/lib/servers} does not exist), Gnus will
+automatically agentize a few servers for you. This variable control
+which backends should be auto-agentized. It is typically only useful
+to agentize remote backends. The auto-agentizing has the same effect
+as running @kbd{J a} on the servers (@pxref{Server Agent Commands}).
+If the file exist, you must manage the servers manually by adding or
+removing them, this variable is only applicable the first time you
+start Gnus. The default is @samp{(nntp nnimap)}.
+
@end table
@example
#!/bin/sh
-emacs -batch -l ~/.emacs -f -l ~/.gnus.el gnus-agent-batch >/dev/null 2>&1
+emacs -batch -l ~/.emacs -l ~/.gnus.el gnus-agent-batch >/dev/null 2>&1
@end example
* Global Score Files:: Earth-spanning, ear-splitting score files.
* Kill Files:: They are still here, but they can be ignored.
* Converting Kill Files:: Translating kill files to score files.
-* GroupLens:: Getting predictions on what you like to read.
* Advanced Scoring:: Using logical expressions to build score rules.
* Score Decays:: It can be useful to let scores wither away.
@end menu
@findex gnus-score-find-trace
Display all score rules that have been used on the current article
(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you
-can use @kbd{q} to quit. @kbd{e} edits the corresponding score file.
-When point is on a string within the match element, @kbd{e} will try to
-bring you to this string in the score file.
+may type @kbd{e} to edit score file corresponding to the score rule on
+current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the
+score file and edit it.
@item V w
@kindex V w (Summary)
@table @kbd
+@item W e
+@kindex W e (Group)
+@findex gnus-score-edit-all-score
+Edit the apply-to-all-groups all.SCORE file. You will be popped into
+a @code{gnus-score-mode} buffer (@pxref{Score File Editing}).
+
@item W f
@kindex W f (Group)
@findex gnus-score-flush-cache
gnus-extra-headers, you can score on these headers' values. In this
case, there is a 5th element in the score entry, being the name of the
header to be scored. The following entry is useful in your
-@file{all.SCORE} file in case of spam attacks from a single origin host,
-if your @acronym{NNTP} server tracks NNTP-Posting-Host in overviews:
+@file{all.SCORE} file in case of spam attacks from a single origin
+host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in
+overviews:
@lisp
-("111.222.333.444" -1000 nil s "NNTP-Posting-Host")
+("111.222.333.444" -1000 nil s
+ "NNTP-Posting-Host")
@end lisp
@item Lines, Chars
@vindex gnus-score-mode-hook
@code{gnus-score-menu-hook} is run in score mode buffers.
-In the summary buffer you can use commands like @kbd{V f} and @kbd{V
-e} to begin editing score files.
+In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and
+@kbd{V t} to begin editing score files.
@node Adaptive Scoring
before.
-@node GroupLens
-@section GroupLens
-@cindex GroupLens
-
-@sc{Note:} Unfortunately the GroupLens system seems to have shut down,
-so this section is mostly of historical interest.
-
-@uref{http://www.cs.umn.edu/Research/GroupLens/, GroupLens} is a
-collaborative filtering system that helps you work together with other
-people to find the quality news articles out of the huge volume of
-news articles generated every day.
-
-To accomplish this the GroupLens system combines your opinions about
-articles you have already read with the opinions of others who have done
-likewise and gives you a personalized prediction for each unread news
-article. Think of GroupLens as a matchmaker. GroupLens watches how you
-rate articles, and finds other people that rate articles the same way.
-Once it has found some people you agree with it tells you, in the form
-of a prediction, what they thought of the article. You can use this
-prediction to help you decide whether or not you want to read the
-article.
-
-@menu
-* Using GroupLens:: How to make Gnus use GroupLens.
-* Rating Articles:: Letting GroupLens know how you rate articles.
-* Displaying Predictions:: Displaying predictions given by GroupLens.
-* GroupLens Variables:: Customizing GroupLens.
-@end menu
-
-
-@node Using GroupLens
-@subsection Using GroupLens
-
-To use GroupLens you must register a pseudonym with your local
-@uref{http://www.cs.umn.edu/Research/GroupLens/bbb.html, Better Bit
-Bureau (BBB)} is the only better bit in town at the moment.
-
-Once you have registered you'll need to set a couple of variables.
-
-@table @code
-
-@item gnus-use-grouplens
-@vindex gnus-use-grouplens
-Setting this variable to a non-@code{nil} value will make Gnus hook into
-all the relevant GroupLens functions.
-
-@item grouplens-pseudonym
-@vindex grouplens-pseudonym
-This variable should be set to the pseudonym you got when registering
-with the Better Bit Bureau.
-
-@item grouplens-newsgroups
-@vindex grouplens-newsgroups
-A list of groups that you want to get GroupLens predictions for.
-
-@end table
-
-That's the minimum of what you need to get up and running with GroupLens.
-Once you've registered, GroupLens will start giving you scores for
-articles based on the average of what other people think. But, to get
-the real benefit of GroupLens you need to start rating articles
-yourself. Then the scores GroupLens gives you will be personalized for
-you, based on how the people you usually agree with have already rated.
-
-
-@node Rating Articles
-@subsection Rating Articles
-
-In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
-Where 1 means something like this article is a waste of bandwidth and 5
-means that the article was really good. The basic question to ask
-yourself is, ``on a scale from 1 to 5 would I like to see more articles
-like this one?''
-
-There are four ways to enter a rating for an article in GroupLens.
-
-@table @kbd
-
-@item r
-@kindex r (GroupLens)
-@findex bbb-summary-rate-article
-This function will prompt you for a rating on a scale of one to five.
-
-@item k
-@kindex k (GroupLens)
-@findex grouplens-score-thread
-This function will prompt you for a rating, and rate all the articles in
-the thread. This is really useful for some of those long running giant
-threads in rec.humor.
-
-@end table
-
-The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be
-the score of the article you're reading.
-
-@table @kbd
-
-@item 1-5 n
-@kindex n (GroupLens)
-@findex grouplens-next-unread-article
-Rate the article and go to the next unread article.
-
-@item 1-5 ,
-@kindex , (GroupLens)
-@findex grouplens-best-unread-article
-Rate the article and go to the next unread article with the highest score.
-
-@end table
-
-If you want to give the current article a score of 4 and then go to the
-next article, just type @kbd{4 n}.
-
-
-@node Displaying Predictions
-@subsection Displaying Predictions
-
-GroupLens makes a prediction for you about how much you will like a
-news article. The predictions from GroupLens are on a scale from 1 to
-5, where 1 is the worst and 5 is the best. You can use the predictions
-from GroupLens in one of three ways controlled by the variable
-@code{gnus-grouplens-override-scoring}.
-
-@vindex gnus-grouplens-override-scoring
-There are three ways to display predictions in grouplens. You may
-choose to have the GroupLens scores contribute to, or override the
-regular Gnus scoring mechanism. override is the default; however, some
-people prefer to see the Gnus scores plus the grouplens scores. To get
-the separate scoring behavior you need to set
-@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the
-GroupLens predictions combined with the grouplens scores set it to
-@code{'override} and to combine the scores set
-@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use
-the combine option you will also want to set the values for
-@code{grouplens-prediction-offset} and
-@code{grouplens-score-scale-factor}.
-
-@vindex grouplens-prediction-display
-In either case, GroupLens gives you a few choices for how you would like
-to see your predictions displayed. The display of predictions is
-controlled by the @code{grouplens-prediction-display} variable.
-
-The following are valid values for that variable.
-
-@table @code
-@item prediction-spot
-The higher the prediction, the further to the right an @samp{*} is
-displayed.
-
-@item confidence-interval
-A numeric confidence interval.
-
-@item prediction-bar
-The higher the prediction, the longer the bar.
-
-@item confidence-bar
-Numerical confidence.
-
-@item confidence-spot
-The spot gets bigger with more confidence.
-
-@item prediction-num
-Plain-old numeric value.
-
-@item confidence-plus-minus
-Prediction +/- confidence.
-
-@end table
-
-
-@node GroupLens Variables
-@subsection GroupLens Variables
-
-@table @code
-
-@item gnus-summary-grouplens-line-format
-The summary line format used in GroupLens-enhanced summary buffers. It
-accepts the same specs as the normal summary line format (@pxref{Summary
-Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-23,23n%]%)
-%s\n}.
-
-@item grouplens-bbb-host
-Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the
-default.
-
-@item grouplens-bbb-port
-Port of the host running the bbbd server. The default is 9000.
-
-@item grouplens-score-offset
-Offset the prediction by this value. In other words, subtract the
-prediction value by this number to arrive at the effective score. The
-default is 0.
-
-@item grouplens-score-scale-factor
-This variable allows the user to magnify the effect of GroupLens scores.
-The scale factor is applied after the offset. The default is 1.
-
-@end table
-
-
@node Advanced Scoring
@section Advanced Scoring
@lisp
(defun gnus-decay-score (score)
- "Decay SCORE.
-This is done according to `gnus-score-decay-constant'
+ "Decay SCORE according to `gnus-score-decay-constant'
and `gnus-score-decay-scale'."
- (floor
- (- score
- (* (if (< score 0) 1 -1)
- (min (abs score)
- (max gnus-score-decay-constant
- (* (abs score)
- gnus-score-decay-scale)))))))
+ (let ((n (- score
+ (* (if (< score 0) -1 1)
+ (min (abs score)
+ (max gnus-score-decay-constant
+ (* (abs score)
+ gnus-score-decay-scale)))))))
+ (if (and (featurep 'xemacs)
+ ;; XEmacs' floor can handle only the floating point
+ ;; number below the half of the maximum integer.
+ (> (abs n) (lsh -1 -2)))
+ (string-to-number
+ (car (split-string (number-to-string n) "\\.")))
+ (floor n))))
@end lisp
@vindex gnus-score-decay-scale
@include sieve.texi
@chapter PGG
@include pgg.texi
+@chapter SASL
+@include sasl.texi
@end iflatex
@end iftex
* Image Enhancements:: Modern versions of Emacs/XEmacs can display images.
* Fuzzy Matching:: What's the big fuzz?
* Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email.
+* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
@end menu
@end iftex
@c @anchor{X-Face}
-Decoding an @code{X-Face} header either requires an Emacs that has
+Gnus now uses the internal ELisp-based @code{uncompface} program for
+decoding an @code{X-Face} header normally in Emacs. While it doesn't
+require any other external program, you may feel it is slow if you are
+using a slow machine. In such a case, you can modify the following
+variables:
+
+@table @code
+@item uncompface-use-external
+@vindex uncompface-use-external
+Specify which of the internal or the external decoder should be used.
+@code{nil} means to use the internal ELisp-based @code{uncompface}
+program. @code{t} means to use the external decoder. The default value
+is normally @code{undecided} which means to determine it by checking
+whether the host machine is slow, being controlled by
+@code{uncompface-use-external-threshold} (which see).
+
+@item uncompface-use-external-threshold
+@vindex uncompface-use-external-threshold
+A number of seconds to check whether the host machine is slow. If the
+host takes time larger than this value for decoding an @code{X-Face}
+using the internal ELisp-based @code{uncompface} program, it will be
+changed to using the external decoder. The default is 0.1 seconds.
+@end table
+
+If the internal decoder is invalidated or if you are using XEmacs,
+decoding an @code{X-Face} header either requires an Emacs that has
@samp{compface} support (which most XEmacs versions has), or that you
have @samp{compface} installed on your system. If either is true,
Gnus will default to displaying @code{X-Face} headers.
(Note: @code{x-face} is used in the variable/function names, not
@code{xface}).
+@noindent
+Face and variable:
+
+@table @code
+@item gnus-x-face
+@vindex gnus-x-face
+Face to show X-Face. The colors from this face are used as the
+foreground and background colors of the displayed X-Faces. The
+default colors are black and white.
+
+@item gnus-face-properties-alist
+@vindex gnus-face-properties-alist
+Alist of image types and properties applied to Face (@pxref{Face}) and
+X-Face images. The default value is @code{((pbm . (:face gnus-x-face))
+(png . nil))} for Emacs or @code{((xface . (:face gnus-x-face)))} for
+XEmacs. Here are examples:
+
+@lisp
+;; Specify the altitude of Face and X-Face images in the From header.
+(setq gnus-face-properties-alist
+ '((pbm . (:face gnus-x-face :ascent 80))
+ (png . (:ascent 80))))
+
+;; Show Face and X-Face images as pressed buttons.
+(setq gnus-face-properties-alist
+ '((pbm . (:face gnus-x-face :relief -2))
+ (png . (:relief -2))))
+@end lisp
+
+@pxref{Image Descriptors, ,Image Descriptors, elisp, The Emacs Lisp
+Reference Manual} for the valid properties for various image types.
+Currently, @code{pbm} is used for X-Face images and @code{png} is used
+for Face images in Emacs. Only the @code{:face} property is effective
+on the @code{xface} image type in XEmacs if it is built with the
+@samp{libcompface} library.
+@end table
+
Gnus provides a few convenience functions and variables to allow
easier insertion of X-Face headers in outgoing messages.
See @uref{http://quimby.gnus.org/circus/face/} for the precise
specifications.
+The @code{gnus-face-properties-alist} variable affects the appearance of
+displayed Face images. @xref{X-Face}.
+
Gnus provides a few convenience functions and variables to allow
easier insertion of Face headers in outgoing messages.
First, some background on spam.
If you have access to e-mail, you are familiar with spam (technically
-termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it exists
-because e-mail delivery is very cheap compared to paper mail, so only
-a very small percentage of people need to respond to an UCE to make it
-worthwhile to the advertiser. Ironically, one of the most common
-spams is the one offering a database of e-mail addresses for further
-spamming. Senders of spam are usually called @emph{spammers}, but terms like
-@emph{vermin}, @emph{scum}, and @emph{morons} are in common use as well.
+termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it
+exists because e-mail delivery is very cheap compared to paper mail,
+so only a very small percentage of people need to respond to an UCE to
+make it worthwhile to the advertiser. Ironically, one of the most
+common spams is the one offering a database of e-mail addresses for
+further spamming. Senders of spam are usually called @emph{spammers},
+but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and
+@emph{morons} are in common use as well.
Spam comes from a wide variety of sources. It is simply impossible to
dispose of all spam without discarding useful messages. A good
requires its users to have a basic understanding of e-mail delivery
and processing.
-The simplest approach to filtering spam is filtering. If you get 200
-spam messages per day from @samp{random-address@@vmadmin.com}, you
-block @samp{vmadmin.com}. If you get 200 messages about
-@samp{VIAGRA}, you discard all messages with @samp{VIAGRA} in the
-message. This, unfortunately, is a great way to discard legitimate
-e-mail. For instance, the very informative and useful RISKS digest
-has been blocked by overzealous mail filters because it
-@strong{contained} words that were common in spam messages.
-Nevertheless, in isolated cases, with great care, direct filtering of
-mail can be useful.
+The simplest approach to filtering spam is filtering, at the mail
+server or when you sort through incoming mail. If you get 200 spam
+messages per day from @samp{random-address@@vmadmin.com}, you block
+@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you
+discard all messages with @samp{VIAGRA} in the message. If you get
+lots of spam from Bulgaria, for example, you try to filter all mail
+from Bulgarian IPs.
+
+This, unfortunately, is a great way to discard legitimate e-mail. The
+risks of blocking a whole country (Bulgaria, Norway, Nigeria, China,
+etc.) or even a continent (Asia, Africa, Europe, etc.) from contacting
+you should be obvious, so don't do it if you have the choice.
+
+In another instance, the very informative and useful RISKS digest has
+been blocked by overzealous mail filters because it @strong{contained}
+words that were common in spam messages. Nevertheless, in isolated
+cases, with great care, direct filtering of mail can be useful.
Another approach to filtering e-mail is the distributed spam
processing, for instance DCC implements such a system. In essence,
@var{N} systems around the world agree that a machine @var{X} in
-China, Ghana, or California is sending out spam e-mail, and these
-@var{N} systems enter @var{X} or the spam e-mail from @var{X} into
-a database. The criteria for spam detection vary---it may be the
-number of messages sent, the content of the messages, and so on. When
-a user of the distributed processing system wants to find out if a
-message is spam, he consults one of those @var{N} systems.
+Ghana, Estonia, or California is sending out spam e-mail, and these
+@var{N} systems enter @var{X} or the spam e-mail from @var{X} into a
+database. The criteria for spam detection vary---it may be the number
+of messages sent, the content of the messages, and so on. When a user
+of the distributed processing system wants to find out if a message is
+spam, he consults one of those @var{N} systems.
Distributed spam processing works very well against spammers that send
a large number of messages at once, but it requires the user to set up
fairly complicated checks. There are commercial and free distributed
spam processing systems. Distributed spam processing has its risks as
well. For instance legitimate e-mail senders have been accused of
-sending spam, and their web sites have been shut down for some time
-because of the incident.
+sending spam, and their web sites and mailing lists have been shut
+down for some time because of the incident.
The statistical approach to spam filtering is also popular. It is
based on a statistical analysis of previous spam messages. Usually
analysis of spam works very well in most of the cases, but it can
classify legitimate e-mail as spam in some cases. It takes time to
run the analysis, the full message must be analyzed, and the user has
-to store the database of spam analyses.
+to store the database of spam analyses. Statistical analysis on the
+server is gaining popularity. This has the advantage of letting the
+user Just Read Mail, but has the disadvantage that it's harder to tell
+the server that it has misclassified mail.
+
+Fighting spam is not easy, no matter what anyone says. There is no
+magic switch that will distinguish Viagra ads from Mom's e-mails.
+Even people are having a hard time telling spam apart from non-spam,
+because spammers are actively looking to fool us into thinking they
+are Mom, essentially. Spamming is irritating, irresponsible, and
+idiotic behavior from a bunch of people who think the world owes them
+a favor. We hope the following sections will help you in fighting the
+spam plague.
@node Anti-Spam Basics
@subsection Anti-Spam Basics
(@pxref{Fancy Mail Splitting}):
@lisp
-(
- ...
+(...
(to "larsi@@trym.ifi.uio.no"
- (| ("subject" "re:.*" "misc")
- ("references" ".*@@.*" "misc")
- "spam"))
- ...
-)
+ (| ("subject" "re:.*" "misc")
+ ("references" ".*@@.*" "misc")
+ "spam"))
+ ...)
@end lisp
This says that all mail to this address is suspect, but if it has a
spam. It's a win-win situation. Forging @code{From} headers to point
to non-existent domains is yucky, in my opinion.
+Be careful with this approach. Spammers are wise to it.
@node SpamAssassin
@cindex Vipul's Razor
@cindex DCC
-The days where the hints in the previous section was sufficient in
+The days where the hints in the previous section were sufficient in
avoiding spam are coming to an end. There are many tools out there
that claim to reduce the amount of spam you get. This section could
easily become outdated fast, as new products replace old, but
though this section will use SpamAssassin as an example, it should be
easy to adapt it to most other tools.
+Note that this section does not involve the @code{spam.el} package,
+which is discussed in the next section. If you don't care for all
+the features of @code{spam.el}, you can make do with these simple
+recipes.
+
If the tool you are using is not installed on the mail server, you
need to invoke it yourself. Ideas on how to use the
@code{:postscript} mail source parameter (@pxref{Mail Source
'((file :prescript "formail -bs spamassassin < /var/mail/%u")
(pop :user "jrl"
:server "pophost"
- :postscript "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t")))
+ :postscript
+ "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t")))
@end lisp
Once you manage to process your incoming spool somehow, thus making
...))
(defun kevin-spamassassin ()
(save-excursion
- (widen)
- (if (eq 1 (call-process-region (point-min) (point-max)
- "spamc" nil nil nil "-c"))
- "spam")))
+ (save-restriction
+ (widen)
+ (if (eq 1 (call-process-region (point-min) (point-max)
+ "spamc" nil nil nil "-c"))
+ "spam"))))
@end lisp
Note that with the nnimap backend, message bodies will not be
downloaded by default. You need to set
-@code{nnimap-split-download-body} to t to do that (@pxref{Splitting in
-IMAP}).
+@code{nnimap-split-download-body} to @code{t} to do that
+(@pxref{Splitting in IMAP}).
That is about it. As some spam is likely to get through anyway, you
might want to have a nifty function to call when you happen to read
new form of spam appears. This means that a small percentage of spam
will always get through. It also means that somewhere, someone needs
to read lots of spam to update these tools. Hashcash avoids that, but
-instead requires that everyone you communicate with supports the
+instead prefers that everyone you contact through e-mail supports the
scheme. You can view the two approaches as pragmatic vs dogmatic.
The approaches have their own advantages and disadvantages, but as
often in the real world, a combination of them is stronger than either
The idea behind @file{spam.el} is to have a control center for spam detection
and filtering in Gnus. To that end, @file{spam.el} does two things: it
-filters incoming mail, and it analyzes mail known to be spam or ham.
+filters new mail, and it analyzes mail known to be spam or ham.
@dfn{Ham} is the name used throughout @file{spam.el} to indicate
non-spam messages.
-So, what happens when you load @file{spam.el}?
-
-First of all, you @strong{must} set the variable
-@code{spam-install-hooks} to @code{t} and install the @code{spam.el} hooks:
+First of all, you @strong{must} run the function
+@code{spam-initialize} to autoload @code{spam.el} and to install the
+@code{spam.el} hooks. There is one exception: if you use the
+@code{spam-use-stat} (@pxref{spam-stat spam filtering}) setting, you
+should turn it on before @code{spam-initialize}:
@example
-(setq spam-install-hooks t)
-(spam-install-hooks-function)
+(setq spam-use-stat t) ;; if needed
+(spam-initialize)
@end example
-This is automatically done for you if you load @code{spam.el}
-@emph{after} one of the @code{spam-use-*} variables explained later
-are set. So you should load @code{spam.el} after you set one of the
-@code{spam-use-*} variables:
+So, what happens when you load @file{spam.el}?
-@example
-(setq spam-use-bogofilter t)
-(require 'spam)
-@end example
+First, some hooks will get installed by @code{spam-initialize}. There
+are some hooks for @code{spam-stat} so it can save its databases, and
+there are hooks so interesting things will happen when you enter and
+leave a group. More on the sequence of events later (@pxref{Spam
+ELisp Package Sequence of Events}).
You get the following keyboard commands:
variables. Try @code{customize-group} on the @samp{spam} variable
group.
+@menu
+* Spam ELisp Package Sequence of Events::
+* Spam ELisp Package Filtering of Incoming Mail::
+* Spam ELisp Package Global Variables::
+* Spam ELisp Package Configuration Examples::
+* Blacklists and Whitelists::
+* BBDB Whitelists::
+* Gmane Spam Reporting::
+* Anti-spam Hashcash Payments::
+* Blackholes::
+* Regular Expressions Header Matching::
+* Bogofilter::
+* SpamAssassin backend::
+* ifile spam filtering::
+* spam-stat spam filtering::
+* SpamOracle::
+* Extending the Spam ELisp package::
+@end menu
+
+@node Spam ELisp Package Sequence of Events
+@subsubsection Spam ELisp Package Sequence of Events
+@cindex spam filtering
+@cindex spam filtering sequence of events
+@cindex spam
+
+You must read this section to understand how @code{spam.el} works.
+Do not skip, speed-read, or glance through this section.
+
+There are two @emph{contact points}, if you will, between
+@code{spam.el} and the rest of Gnus: checking new mail for spam, and
+leaving a group.
+
+Getting new mail is done in one of two ways. You can either split
+your incoming mail or you can classify new articles as ham or spam
+when you enter the group.
+
+Splitting incoming mail is better suited to mail backends such as
+@code{nnml} or @code{nnimap} where new mail appears in a single file
+called a @dfn{Spool File}. See @xref{Spam ELisp Package Filtering of
+Incoming Mail}.
+
+@vindex gnus-spam-autodetect
+@vindex gnus-spam-autodetect-methods
+For backends such as @code{nntp} there is no incoming mail spool, so
+an alternate mechanism must be used. This may also happen for
+backends where the server is in charge of splitting incoming mail, and
+Gnus does not do further splitting. The @code{spam-autodetect} and
+@code{spam-autodetect-methods} group parameters (accessible with
+@kbd{G c} and @kbd{G p} as usual), and the corresponding variables
+@code{gnus-spam-autodetect} and @code{gnus-spam-autodetect-methods}
+(accessible with @kbd{M-x customize-variable} as usual) can help.
+
+When @code{spam-autodetect} is used (you can turn it on for a
+group/topic or wholesale by regex, as needed), it hooks into the
+process of entering a group. Thus, entering a group with unseen or
+unread articles becomes the substitute for checking incoming mail.
+Whether only unseen articles or all unread articles will be processed
+is determined by the @code{spam-autodetect-recheck-messages}. When
+set to @code{t}, unread messages will be rechecked.
+
+@code{spam-autodetect} grants the user at once more and less control
+of spam filtering. The user will have more control over each group's
+spam methods, so for instance the @samp{ding} group may have
+@code{spam-use-BBDB} as the autodetection method, while the
+@samp{suspect} group may have the @code{spam-use-blacklist} and
+@code{spam-use-bogofilter} methods enabled. Every article detected to
+be spam will be marked with the spam mark @samp{$} and processed on
+exit from the group as normal spam. The user has less control over
+the @emph{sequence} of checks, as he might with @code{spam-split}.
+
+When the newly split mail goes into groups, or messages are
+autodetected to be ham or spam, those groups must be exited (after
+entering, if needed) for further spam processing to happen. It
+matters whether the group is considered a ham group, a spam group, or
+is unclassified, based on its @code{spam-content} parameter
+(@pxref{Spam ELisp Package Global Variables}). Spam groups have the
+additional characteristic that, when entered, any unseen or unread
+articles (depending on the @code{spam-mark-only-unseen-as-spam}
+variable) will be marked as spam. Thus, mail split into a spam group
+gets automatically marked as spam when you enter the group.
+
+So, when you exit a group, the @code{spam-processors} are applied, if
+any are set, and the processed mail is moved to the
+@code{ham-process-destination} or the @code{spam-process-destination}
+depending on the article's classification. If the
+@code{ham-process-destination} or the @code{spam-process-destination},
+whichever is appropriate, are @code{nil}, the article is left in the
+current group.
+
+If a spam is found in any group (this can be changed to only non-spam
+groups with @code{spam-move-spam-nonspam-groups-only}), it is
+processed by the active @code{spam-processors} (@pxref{Spam ELisp
+Package Global Variables}) when the group is exited. Furthermore, the
+spam is moved to the @code{spam-process-destination} (@pxref{Spam
+ELisp Package Global Variables}) for further training or deletion.
+You have to load the @code{gnus-registry.el} package and enable the
+@code{spam-log-to-registry} variable if you want spam to be processed
+no more than once. Thus, spam is detected and processed everywhere,
+which is what most people want. If the
+@code{spam-process-destination} is @code{nil}, the spam is marked as
+expired, which is usually the right thing to do.
+
+If spam can not be moved---because of a read-only backend such as
+@acronym{NNTP}, for example, it will be copied.
+
+If a ham mail is found in a ham group, as determined by the
+@code{ham-marks} parameter, it is processed as ham by the active ham
+@code{spam-processor} when the group is exited. With the variables
+@code{spam-process-ham-in-spam-groups} and
+@code{spam-process-ham-in-nonham-groups} the behavior can be further
+altered so ham found anywhere can be processed. You have to load the
+@code{gnus-registry.el} package and enable the
+@code{spam-log-to-registry} variable if you want ham to be processed
+no more than once. Thus, ham is detected and processed only when
+necessary, which is what most people want. More on this in
+@xref{Spam ELisp Package Configuration Examples}.
+
+If ham can not be moved---because of a read-only backend such as
+@acronym{NNTP}, for example, it will be copied.
+
+If all this seems confusing, don't worry. Soon it will be as natural
+as typing Lisp one-liners on a neural interface@dots{} err, sorry, that's
+50 years in the future yet. Just trust us, it's not so bad.
+
+@node Spam ELisp Package Filtering of Incoming Mail
+@subsubsection Spam ELisp Package Filtering of Incoming Mail
+@cindex spam filtering
+@cindex spam filtering incoming mail
+@cindex spam
+
+To use the @file{spam.el} facilities for incoming mail filtering, you
+must add the following to your fancy split list
+@code{nnmail-split-fancy} or @code{nnimap-split-fancy}:
+
+@example
+(: spam-split)
+@end example
+
+Note that the fancy split may be called @code{nnmail-split-fancy} or
+@code{nnimap-split-fancy}, depending on whether you use the nnmail or
+nnimap back ends to retrieve your mail.
+
+Also, @code{spam-split} will not modify incoming mail in any way.
+
+The @code{spam-split} function will process incoming mail and send the
+mail considered to be spam into the group name given by the variable
+@code{spam-split-group}. By default that group name is @samp{spam},
+but you can customize @code{spam-split-group}. Make sure the contents
+of @code{spam-split-group} are an @emph{unqualified} group name, for
+instance in an @code{nnimap} server @samp{your-server} the value
+@samp{spam} will turn out to be @samp{nnimap+your-server:spam}. The
+value @samp{nnimap+server:spam}, therefore, is wrong and will
+actually give you the group
+@samp{nnimap+your-server:nnimap+server:spam} which may or may not
+work depending on your server's tolerance for strange group names.
+
+You can also give @code{spam-split} a parameter,
+e.g. @code{spam-use-regex-headers} or @code{"maybe-spam"}. Why is
+this useful?
+
+Take these split rules (with @code{spam-use-regex-headers} and
+@code{spam-use-blackholes} set):
+
+@example
+ nnimap-split-fancy '(|
+ (any "ding" "ding")
+ (: spam-split)
+ ;; @r{default mailbox}
+ "mail")
+@end example
+
+Now, the problem is that you want all ding messages to make it to the
+ding folder. But that will let obvious spam (for example, spam
+detected by SpamAssassin, and @code{spam-use-regex-headers}) through,
+when it's sent to the ding list. On the other hand, some messages to
+the ding list are from a mail server in the blackhole list, so the
+invocation of @code{spam-split} can't be before the ding rule.
+
+You can let SpamAssassin headers supersede ding rules, but all other
+@code{spam-split} rules (including a second invocation of the
+regex-headers check) will be after the ding rule:
+
+@example
+nnimap-split-fancy
+ '(|
+ ;; @r{all spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}}
+ (: spam-split "regex-spam" 'spam-use-regex-headers)
+ (any "ding" "ding")
+ ;; @r{all other spam detected by spam-split goes to @code{spam-split-group}}
+ (: spam-split)
+ ;; @r{default mailbox}
+ "mail")
+@end example
+
+This lets you invoke specific @code{spam-split} checks depending on
+your particular needs, and to target the results of those checks to a
+particular spam group. You don't have to throw all mail into all the
+spam tests. Another reason why this is nice is that messages to
+mailing lists you have rules for don't have to have resource-intensive
+blackhole checks performed on them. You could also specify different
+spam checks for your nnmail split vs. your nnimap split. Go crazy.
+
+You should still have specific checks such as
+@code{spam-use-regex-headers} set to @code{t}, even if you
+specifically invoke @code{spam-split} with the check. The reason is
+that when loading @file{spam.el}, some conditional loading is done
+depending on what @code{spam-use-xyz} variables you have set. This
+is usually not critical, though.
+
+@emph{Note for IMAP users}
+
+The boolean variable @code{nnimap-split-download-body} needs to be
+set, if you want to split based on the whole message instead of just
+the headers. By default, the nnimap back end will only retrieve the
+message headers. If you use @code{spam-check-bogofilter},
+@code{spam-check-ifile}, or @code{spam-check-stat} (the splitters that
+can benefit from the full message body), you should set this variable.
+It is not set by default because it will slow @acronym{IMAP} down, and
+that is not an appropriate decision to make on behalf of the user.
+
+@xref{Splitting in IMAP}.
+
+@emph{TODO: spam.el needs to provide a uniform way of training all the
+statistical databases. Some have that functionality built-in, others
+don't.}
+
+@node Spam ELisp Package Global Variables
+@subsubsection Spam ELisp Package Global Variables
+@cindex spam filtering
+@cindex spam filtering variables
+@cindex spam variables
+@cindex spam
+
@vindex gnus-spam-process-newsgroups
The concepts of ham processors and spam processors are very important.
Ham processors and spam processors for a group can be set with the
processors take mail known to be spam and process it so similar spam
will be detected later.
+The format of the spam or ham processor entry used to be a symbol,
+but now it is a @sc{cons} cell. See the individual spam processor entries
+for more information.
+
@vindex gnus-spam-newsgroup-contents
Gnus learns from the spam you get. You have to collect your spam in
one or more spam groups, and set or customize the variable
unmarked it, it won't be marked as spam when you enter the group
thereafter. You can disable that behavior, so all unread messages
will get the @samp{$} mark, if you set the
-@code{spam-mark-only-unseen-as-spam} parameter to nil. You should
-remove the @samp{$} mark when you are in the group summary buffer for
-every message that is not spam after all. To remove the @samp{$}
-mark, you can use @kbd{M-u} to ``unread'' the article, or @kbd{d} for
-declaring it read the non-spam way. When you leave a group, all
-spam-marked (@samp{$}) articles are sent to a spam processor which
-will study them as spam samples.
+@code{spam-mark-only-unseen-as-spam} parameter to @code{nil}. You
+should remove the @samp{$} mark when you are in the group summary
+buffer for every message that is not spam after all. To remove the
+@samp{$} mark, you can use @kbd{M-u} to ``unread'' the article, or
+@kbd{d} for declaring it read the non-spam way. When you leave a
+group, all spam-marked (@samp{$}) articles are sent to a spam
+processor which will study them as spam samples.
Messages may also be deleted in various other ways, and unless
@code{ham-marks} group parameter gets overridden below, marks @samp{R}
@defvar ham-marks
You can customize this group or topic parameter to be the list of
marks you want to consider ham. By default, the list contains the
-deleted, read, killed, kill-filed, and low-score marks.
+deleted, read, killed, kill-filed, and low-score marks (the idea is
+that these articles have been read, but are not spam). It can be
+useful to also include the tick mark in the ham marks. It is not
+recommended to make the unread mark a ham mark, because it normally
+indicates a lack of classification. But you can do it, and we'll be
+happy for you.
@end defvar
@defvar spam-marks
You can customize this group or topic parameter to be the list of
marks you want to consider spam. By default, the list contains only
-the spam mark.
+the spam mark. It is not recommended to change that, but you can if
+you really want to.
@end defvar
When you leave @emph{any} group, regardless of its
determined by either the @code{ham-process-destination} group
parameter or a match in the @code{gnus-ham-process-destinations}
variable, which is a list of regular expressions matched with group
-names (it's easiest to customize this variable with
-@code{customize-variable gnus-ham-process-destinations}). The ultimate
-location is a group name. If the @code{ham-process-destination}
+names (it's easiest to customize this variable with @kbd{M-x
+customize-variable @key{RET} gnus-ham-process-destinations}). Each
+group name list is a standard Lisp list, if you prefer to customize
+the variable manually. If the @code{ham-process-destination}
parameter is not set, ham articles are left in place. If the
@code{spam-mark-ham-unread-before-move-from-spam-group} parameter is
set, the ham articles are marked as unread before being moved.
+If ham can not be moved---because of a read-only backend such as
+@acronym{NNTP}, for example, it will be copied.
+
+Note that you can use multiples destinations per group or regular
+expression! This enables you to send your ham to a regular mail
+group and to a @emph{ham training} group.
+
When you leave a @emph{ham} group, all ham-marked articles are sent to
a ham processor, which will study these as non-spam samples.
@vindex spam-process-ham-in-spam-groups
By default the variable @code{spam-process-ham-in-spam-groups} is
-nil. Set it to t if you want ham found in spam groups to be
-processed. Normally this is not done, you are expected instead to
-send your ham to a ham group and process it there.
+@code{nil}. Set it to @code{t} if you want ham found in spam groups
+to be processed. Normally this is not done, you are expected instead
+to send your ham to a ham group and process it there.
@vindex spam-process-ham-in-nonham-groups
By default the variable @code{spam-process-ham-in-nonham-groups} is
-nil. Set it to t if you want ham found in non-ham (spam or
-unclassified) groups to be processed. Normally this is not done, you
-are expected instead to send your ham to a ham group and process it
-there.
+@code{nil}. Set it to @code{t} if you want ham found in non-ham (spam
+or unclassified) groups to be processed. Normally this is not done,
+you are expected instead to send your ham to a ham group and process
+it there.
@vindex gnus-spam-process-destinations
When you leave a @emph{ham} or @emph{unclassified} group, all
the @code{spam-process-destination} group parameter or a match in the
@code{gnus-spam-process-destinations} variable, which is a list of
regular expressions matched with group names (it's easiest to
-customize this variable with @code{customize-variable
-gnus-spam-process-destinations}). The ultimate location is a group
-name. If the @code{spam-process-destination} parameter is not set,
-the spam articles are only expired.
+customize this variable with @kbd{M-x customize-variable @key{RET}
+gnus-spam-process-destinations}). Each group name list is a standard
+Lisp list, if you prefer to customize the variable manually. If the
+@code{spam-process-destination} parameter is not set, the spam
+articles are only expired. The group name is fully qualified, meaning
+that if you see @samp{nntp:servername} before the group name in the
+group buffer then you need it here as well.
+
+If spam can not be moved---because of a read-only backend such as
+@acronym{NNTP}, for example, it will be copied.
+
+Note that you can use multiples destinations per group or regular
+expression! This enables you to send your spam to multiple @emph{spam
+training} groups.
+
+@vindex spam-log-to-registry
+The problem with processing ham and spam is that Gnus doesn't track
+this processing by default. Enable the @code{spam-log-to-registry}
+variable so @code{spam.el} will use @code{gnus-registry.el} to track
+what articles have been processed, and avoid processing articles
+multiple times. Keep in mind that if you limit the number of registry
+entries, this won't work as well as it does without a limit.
+
+@vindex spam-mark-only-unseen-as-spam
+Set this variable if you want only unseen articles in spam groups to
+be marked as spam. By default, it is set. If you set it to
+@code{nil}, unread articles will also be marked as spam.
+
+@vindex spam-mark-ham-unread-before-move-from-spam-group
+Set this variable if you want ham to be unmarked before it is moved
+out of the spam group. This is very useful when you use something
+like the tick mark @samp{!} to mark ham---the article will be placed
+in your @code{ham-process-destination}, unmarked as if it came fresh
+from the mail server.
+
+@vindex spam-autodetect-recheck-messages
+When autodetecting spam, this variable tells @code{spam.el} whether
+only unseen articles or all unread articles should be checked for
+spam. It is recommended that you leave it off.
+
+@node Spam ELisp Package Configuration Examples
+@subsubsection Spam ELisp Package Configuration Examples
+@cindex spam filtering
+@cindex spam filtering configuration examples
+@cindex spam configuration examples
+@cindex spam
-To use the @file{spam.el} facilities for incoming mail filtering, you
-must add the following to your fancy split list
-@code{nnmail-split-fancy} or @code{nnimap-split-fancy}:
+@subsubheading Ted's setup
+From Ted Zlatanov <tzz@@lifelogs.com>.
@example
-(: spam-split)
-@end example
+;; @r{for @code{gnus-registry-split-fancy-with-parent} and spam autodetection}
+;; @r{see @file{gnus-registry.el} for more information}
+(gnus-registry-initialize)
+(spam-initialize)
+
+;; @r{I like @kbd{C-s} for marking spam}
+(define-key gnus-summary-mode-map "\C-s" 'gnus-summary-mark-as-spam)
+
+(setq
+ spam-log-to-registry t ; @r{for spam autodetection}
+ spam-use-BBDB t
+ spam-use-regex-headers t ; @r{catch X-Spam-Flag (SpamAssassin)}
+ ;; @r{all groups with @samp{spam} in the name contain spam}
+ gnus-spam-newsgroup-contents
+ '(("spam" gnus-group-spam-classification-spam))
+ ;; @r{see documentation for these}
+ spam-move-spam-nonspam-groups-only nil
+ spam-mark-only-unseen-as-spam t
+ spam-mark-ham-unread-before-move-from-spam-group t
+ nnimap-split-rule 'nnimap-split-fancy
+ ;; @r{understand what this does before you copy it to your own setup!}
+ nnimap-split-fancy '(|
+ ;; @r{trace references to parents and put in their group}
+ (: gnus-registry-split-fancy-with-parent)
+ ;; @r{this will catch server-side SpamAssassin tags}
+ (: spam-split 'spam-use-regex-headers)
+ (any "ding" "ding")
+ ;; @r{note that spam by default will go to @samp{spam}}
+ (: spam-split)
+ ;; @r{default mailbox}
+ "mail"))
-Note that the fancy split may be called @code{nnmail-split-fancy} or
-@code{nnimap-split-fancy}, depending on whether you use the nnmail or
-nnimap back ends to retrieve your mail.
+;; @r{my parameters, set with @kbd{G p}}
-The @code{spam-split} function will process incoming mail and send the
-mail considered to be spam into the group name given by the variable
-@code{spam-split-group}. By default that group name is @samp{spam},
-but you can customize @code{spam-split-group}.
+;; @r{all nnml groups, and all nnimap groups except}
+;; @r{@samp{nnimap+mail.lifelogs.com:train} and}
+;; @r{@samp{nnimap+mail.lifelogs.com:spam}: any spam goes to nnimap training,}
+;; @r{because it must have been detected manually}
-You can also give @code{spam-split} a parameter,
-e.g. @samp{'spam-use-regex-headers}. Why is this useful?
+((spam-process-destination . "nnimap+mail.lifelogs.com:train"))
-Take these split rules (with @code{spam-use-regex-headers} and
-@code{spam-use-blackholes} set):
+;; @r{all @acronym{NNTP} groups}
+;; @r{autodetect spam with the blacklist and ham with the BBDB}
+((spam-autodetect-methods spam-use-blacklist spam-use-BBDB)
+;; @r{send all spam to the training group}
+ (spam-process-destination . "nnimap+mail.lifelogs.com:train"))
-@example
- nnimap-split-fancy '(|
- (any "ding" "ding")
- (: spam-split)
- ;; default mailbox
- "mail")
-@end example
+;; @r{only some @acronym{NNTP} groups, where I want to autodetect spam}
+((spam-autodetect . t))
-Now, the problem is that you want all ding messages to make it to the
-ding folder. But that will let obvious spam (for example, spam
-detected by SpamAssassin, and @code{spam-use-regex-headers}) through,
-when it's sent to the ding list. On the other hand, some messages to
-the ding list are from a mail server in the blackhole list, so the
-invocation of @code{spam-split} can't be before the ding rule.
+;; @r{my nnimap @samp{nnimap+mail.lifelogs.com:spam} group}
-You can let SpamAssassin headers supersede ding rules, but all other
-@code{spam-split} rules (including a second invocation of the
-regex-headers check) will be after the ding rule:
+;; @r{this is a spam group}
+((spam-contents gnus-group-spam-classification-spam)
-@example
- nnimap-split-fancy '(|
- (: spam-split 'spam-use-regex-headers)
- (any "ding" "ding")
- (: spam-split)
- ;; default mailbox
- "mail")
-@end example
+ ;; @r{any spam (which happens when I enter for all unseen messages,}
+ ;; @r{because of the @code{gnus-spam-newsgroup-contents} setting above), goes to}
+ ;; @r{@samp{nnimap+mail.lifelogs.com:train} unless I mark it as ham}
-Basically, this lets you invoke specific @code{spam-split} checks
-depending on your particular needs. You don't have to throw all mail
-into all the spam tests. Another reason why this is nice is that
-messages to mailing lists you have rules for don't have to have
-resource-intensive blackhole checks performed on them. You could also
-specify different spam checks for your nnmail split vs. your nnimap
-split. Go crazy.
+ (spam-process-destination "nnimap+mail.lifelogs.com:train")
-You still have to have specific checks such as
-@code{spam-use-regex-headers} set to @code{t}, even if you specifically
-invoke @code{spam-split} with the check. The reason is that when
-loading @file{spam.el}, some conditional loading is done depending on
-what @code{spam-use-xyz} variables you have set.
+ ;; @r{any ham goes to my @samp{nnimap+mail.lifelogs.com:mail} folder, but}
+ ;; @r{also to my @samp{nnimap+mail.lifelogs.com:trainham} folder for training}
-@emph{Note for IMAP users}
+ (ham-process-destination "nnimap+mail.lifelogs.com:mail"
+ "nnimap+mail.lifelogs.com:trainham")
+ ;; @r{in this group, only @samp{!} marks are ham}
+ (ham-marks
+ (gnus-ticked-mark))
+ ;; @r{remembers senders in the blacklist on the way out---this is}
+ ;; @r{definitely not needed, it just makes me feel better}
+ (spam-process (gnus-group-spam-exit-processor-blacklist)))
-The boolean variable @code{nnimap-split-download-body} needs to be
-set, if you want to split based on the whole message instead of just
-the headers. By default, the nnimap back end will only retrieve the
-message headers. If you use @code{spam-check-bogofilter},
-@code{spam-check-ifile}, or @code{spam-check-stat} (the splitters that
-can benefit from the full message body), you should set this variable.
-It is not set by default because it will slow @acronym{IMAP} down, and
-that is not an appropriate decision to make on behalf of the user.
+;; @r{Later, on the @acronym{IMAP} server I use the @samp{train} group for training}
+;; @r{SpamAssassin to recognize spam, and the @samp{trainham} group fora}
+;; @r{recognizing ham---but Gnus has nothing to do with it.}
-@xref{Splitting in IMAP}.
+@end example
-@emph{TODO: Currently, spam.el only supports insertion of articles
-into a back end. There is no way to tell spam.el that an article is no
-longer spam or ham.}
+@subsubheading Using @file{spam.el} on an IMAP server with a statistical filter on the server
+From Reiner Steib <reiner.steib@@gmx.de>.
+
+My provider has set up bogofilter (in combination with @acronym{DCC}) on
+the mail server (@acronym{IMAP}). Recognized spam goes to
+@samp{spam.detected}, the rest goes through the normal filter rules,
+i.e. to @samp{some.folder} or to @samp{INBOX}. Training on false
+positives or negatives is done by copying or moving the article to
+@samp{training.ham} or @samp{training.spam} respectively. A cron job on
+the server feeds those to bogofilter with the suitable ham or spam
+options and deletes them from the @samp{training.ham} and
+@samp{training.spam} folders.
+
+With the following entries in @code{gnus-parameters}, @code{spam.el}
+does most of the job for me:
+
+@lisp
+ ("nnimap:spam\\.detected"
+ (gnus-article-sort-functions '(gnus-article-sort-by-chars))
+ (ham-process-destination "nnimap:INBOX" "nnimap:training.ham")
+ (spam-contents gnus-group-spam-classification-spam))
+ ("nnimap:\\(INBOX\\|other-folders\\)"
+ (spam-process-destination . "nnimap:training.spam")
+ (spam-contents gnus-group-spam-classification-ham))
+@end lisp
+
+@itemize
+
+@item @b{The Spam folder:}
+
+In the folder @samp{spam.detected}, I have to check for false positives
+(i.e. legitimate mails, that were wrongly judged as spam by
+bogofilter or DCC).
+
+Because of the @code{gnus-group-spam-classification-spam} entry, all
+messages are marked as spam (with @code{$}). When I find a false
+positive, I mark the message with some other ham mark (@code{ham-marks},
+@ref{Spam ELisp Package Global Variables}). On group exit, those
+messages are copied to both groups, @samp{INBOX} (where I want to have
+the article) and @samp{training.ham} (for training bogofilter) and
+deleted from the @samp{spam.detected} folder.
+
+The @code{gnus-article-sort-by-chars} entry simplifies detection of
+false positives for me. I receive lots of worms (sweN, @dots{}), that all
+have a similar size. Grouping them by size (i.e. chars) makes finding
+other false positives easier. (Of course worms aren't @i{spam}
+(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is
+an excellent tool for filtering those unwanted mails for me.)
+
+@item @b{Ham folders:}
+
+In my ham folders, I just hit @kbd{S x}
+(@code{gnus-summary-mark-as-spam}) whenever I see an unrecognized spam
+mail (false negative). On group exit, those messages are moved to
+@samp{training.ham}.
+@end itemize
-@emph{TODO: spam.el needs to provide a uniform way of training all the
-statistical databases. Some have that functionality built-in, others
-don't.}
+@subsubheading Reporting spam articles in Gmane groups with @code{spam-report.el}
-The following are the methods you can use to control the behavior of
-@code{spam-split} and their corresponding spam and ham processors:
+From Reiner Steib <reiner.steib@@gmx.de>.
-@menu
-* Blacklists and Whitelists::
-* BBDB Whitelists::
-* Gmane Spam Reporting::
-* Anti-spam Hashcash Payments::
-* Blackholes::
-* Regular Expressions Header Matching::
-* Bogofilter::
-* ifile spam filtering::
-* spam-stat spam filtering::
-* SpamOracle::
-* Extending the spam elisp package::
-@end menu
+With following entry in @code{gnus-parameters}, @kbd{S x}
+(@code{gnus-summary-mark-as-spam}) marks articles in @code{gmane.*}
+groups as spam and reports the to Gmane at group exit:
+
+@lisp
+ ("^gmane\\."
+ (spam-process (gnus-group-spam-exit-processor-report-gmane)))
+@end lisp
+
+Additionally, I use @code{(setq spam-report-gmane-use-article-number nil)}
+because I don't read the groups directly from news.gmane.org, but
+through my local news server (leafnode). I.e. the article numbers are
+not the same as on news.gmane.org, thus @code{spam-report.el} has to check
+the @code{X-Report-Spam} header to find the correct number.
@node Blacklists and Whitelists
@subsubsection Blacklists and Whitelists
added to a group's @code{spam-process} parameter, the senders of
spam-marked articles will be added to the blacklist.
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-blacklist}, it is recommended
+that you use @code{'(spam spam-use-blacklist)}. Everything will work
+the same way, we promise.
+
@end defvar
@defvar gnus-group-ham-exit-processor-whitelist
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, the senders of
ham-marked articles in @emph{ham} groups will be added to the
-whitelist. Note that this ham processor has no effect in @emph{spam}
-or @emph{unclassified} groups.
+whitelist.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-whitelist}, it is recommended
+that you use @code{'(ham spam-use-whitelist)}. Everything will work
+the same way, we promise.
@end defvar
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, the senders of
ham-marked articles in @emph{ham} groups will be added to the
-BBDB. Note that this ham processor has no effect in @emph{spam}
-or @emph{unclassified} groups.
+BBDB.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-BBDB}, it is recommended
+that you use @code{'(ham spam-use-BBDB)}. Everything will work
+the same way, we promise.
@end defvar
Gmane can be found at @uref{http://gmane.org}.
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-report-gmane}, it is recommended
+that you use @code{'(spam spam-use-gmane)}. Everything will work the
+same way, we promise.
+
@end defvar
@defvar spam-report-gmane-use-article-number
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, spam-marked articles
will be added to the Bogofilter spam database.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-bogofilter}, it is recommended
+that you use @code{'(spam spam-use-bogofilter)}. Everything will work
+the same way, we promise.
@end defvar
@defvar gnus-group-ham-exit-processor-bogofilter
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, the ham-marked
articles in @emph{ham} groups will be added to the Bogofilter database
-of non-spam messages. Note that this ham processor has no effect in
-@emph{spam} or @emph{unclassified} groups.
+of non-spam messages.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-bogofilter}, it is recommended
+that you use @code{'(ham spam-use-bogofilter)}. Everything will work
+the same way, we promise.
@end defvar
@defvar spam-bogofilter-database-directory
used, or has already been used on the article. The 0.9.2.1 version of
Bogofilter was used to test this functionality.
+@node SpamAssassin backend
+@subsubsection SpamAssassin backend
+@cindex spam filtering
+@cindex spamassassin, spam filtering
+@cindex spam
+
+@defvar spam-use-spamassassin
+
+Set this variable if you want @code{spam-split} to use SpamAssassin.
+
+SpamAssassin assigns a score to each article based on a set of rules
+and tests, including a Bayesian filter. The Bayesian filter can be
+trained by associating the @samp{$} mark for spam articles. The
+spam score can be viewed by using the command @kbd{S t} in summary
+mode.
+
+If you set this variable, each article will be processed by
+SpamAssassin when @code{spam-split} is called. If your mail is
+preprocessed by SpamAssassin, and you want to just use the
+SpamAssassin headers, set @code{spam-use-spamassassin-headers}
+instead.
+
+You should not enable this is you use
+@code{spam-use-spamassassin-headers}.
+
+@end defvar
+
+@defvar spam-use-spamassassin-headers
+
+Set this variable if your mail is preprocessed by SpamAssassin and
+want @code{spam-split} to split based on the SpamAssassin headers.
+
+You should not enable this is you use @code{spam-use-spamassassin}.
+
+@end defvar
+
+@defvar spam-spamassassin-path
+
+This variable points to the SpamAssassin executable. If you have
+@code{spamd} running, you can set this variable to the @code{spamc}
+executable for faster processing. See the SpamAssassin documentation
+for more information on @code{spamd}/@code{spamc}.
+
+@end defvar
+
+SpamAssassin is a powerful and flexible spam filter that uses a wide
+variety of tests to identify spam. A ham and a spam processors are
+provided, plus the @code{spam-use-spamassassin} and
+@code{spam-use-spamassassin-headers} variables to indicate to
+spam-split that SpamAssassin should be either used, or has already
+been used on the article. The 2.63 version of SpamAssassin was used
+to test this functionality.
+
@node ifile spam filtering
@subsubsection ifile spam filtering
@cindex spam filtering
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, the spam-marked
articles will be added to the spam-stat database of spam messages.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-stat}, it is recommended
+that you use @code{'(spam spam-use-stat)}. Everything will work
+the same way, we promise.
@end defvar
@defvar gnus-group-ham-exit-processor-stat
@code{gnus-spam-process-newsgroups} variable. When this symbol is
added to a group's @code{spam-process} parameter, the ham-marked
articles in @emph{ham} groups will be added to the spam-stat database
-of non-spam messages. Note that this ham processor has no effect in
-@emph{spam} or @emph{unclassified} groups.
+of non-spam messages.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-stat}, it is recommended
+that you use @code{'(ham spam-use-stat)}. Everything will work
+the same way, we promise.
@end defvar
This enables @file{spam.el} to cooperate with @file{spam-stat.el}.
@code{gnus-spam-process-newsgroups} variable. When this symbol is added
to a group's @code{spam-process} parameter, spam-marked articles will be
sent to SpamOracle as spam samples.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-spam-exit-processor-spamoracle}, it is recommended
+that you use @code{'(spam spam-use-spamoracle)}. Everything will work
+the same way, we promise.
@end defvar
@defvar gnus-group-ham-exit-processor-spamoracle
Add this symbol to a group's @code{spam-process} parameter by
customizing the group parameter or the
@code{gnus-spam-process-newsgroups} variable. When this symbol is added
-to a grup's @code{spam-process} parameter, the ham-marked articles in
+to a group's @code{spam-process} parameter, the ham-marked articles in
@emph{ham} groups will be sent to the SpamOracle as samples of ham
-messages. Note that this ham processor has no effect in @emph{spam} or
-@emph{unclassified} groups.
+messages.
+
+@emph{WARNING}
+
+Instead of the obsolete
+@code{gnus-group-ham-exit-processor-spamoracle}, it is recommended
+that you use @code{'(ham spam-use-spamoracle)}. Everything will work
+the same way, we promise.
@end defvar
-@emph{Example:} These are the Group Parameters of an group that has been
+@emph{Example:} These are the Group Parameters of a group that has been
classified as a ham group, meaning that it should only contain ham
messages.
@example
((spam-contents gnus-group-spam-classification-ham)
- (spam-process
- (gnus-group-spam-exit-processor-spamoracle)))
+ (spam-process ((ham spam-use-spamoracle)
+ (spam spam-use-spamoracle))))
@end example
-For this group the @code{gnus-group-spam-exit-processor-spamoracle} is
-installed. If the group contains spam message (e.g. because SpamOracle
-has not had enough sample messages yet) and the user marks some
-messages as spam messages, these messages will be processed by
-@code{gnus-group-spam-exit-processor-spamoracle}. This processor sends
-the messages to SpamOracle as new samples for spam.
-
-@node Extending the spam elisp package
-@subsubsection Extending the spam elisp package
+For this group the @code{spam-use-spamoracle} is installed for both
+ham and spam processing. If the group contains spam message
+(e.g. because SpamOracle has not had enough sample messages yet) and
+the user marks some messages as spam messages, these messages will be
+processed by SpamOracle. The processor sends the messages to
+SpamOracle as new samples for spam.
+
+@node Extending the Spam ELisp package
+@subsubsection Extending the Spam ELisp package
@cindex spam filtering
@cindex spam elisp package, extending
@cindex extending the spam elisp package
@enumerate
@item
-code
+Code
@lisp
(defvar spam-use-blackbox nil
@end lisp
Add
-@example
- (spam-use-blackbox . spam-check-blackbox)
-@end example
+@lisp
+(spam-use-blackbox . spam-check-blackbox)
+@end lisp
to @code{spam-list-of-checks}.
+Add
+@lisp
+(gnus-group-ham-exit-processor-blackbox ham spam-use-blackbox)
+(gnus-group-spam-exit-processor-blackbox spam spam-use-blackbox)
+@end lisp
+
+to @code{spam-list-of-processors}.
+
+Add
+@lisp
+(spam-use-blackbox spam-blackbox-register-routine
+ nil
+ spam-blackbox-unregister-routine
+ nil)
+@end lisp
+
+to @code{spam-registration-functions}. Write the register/unregister
+routines using the bogofilter register/unregister routines as a
+start, or other restister/unregister routines more appropriate to
+Blackbox.
+
@item
-functionality
+Functionality
Write the @code{spam-check-blackbox} function. It should return
-@samp{nil} or @code{spam-split-group}. See the existing
-@code{spam-check-*} functions for examples of what you can do.
+@samp{nil} or @code{spam-split-group}, observing the other
+conventions. See the existing @code{spam-check-*} functions for
+examples of what you can do, and stick to the template unless you
+fully understand the reasons why you aren't.
Make sure to add @code{spam-use-blackbox} to
@code{spam-list-of-statistical-checks} if Blackbox is a statistical
@enumerate
@item
-code
+Code
Note you don't have to provide a spam or a ham processor. Only
provide them if Blackbox supports spam or ham processing.
+Also, ham and spam processors are being phased out as single
+variables. Instead the form @code{'(spam spam-use-blackbox)} or
+@code{'(ham spam-use-blackbox)} is favored. For now, spam/ham
+processor variables are still around but they won't be for long.
+
@lisp
-(defvar gnus-group-spam-exit-processor-blackbox "blackbox"
+(defvar gnus-group-spam-exit-processor-blackbox "blackbox-spam"
"The Blackbox summary exit spam processor.
Only applicable to spam groups.")
-(defvar gnus-group-ham-exit-processor-blackbox "blackbox"
+(defvar gnus-group-ham-exit-processor-blackbox "blackbox-ham"
"The whitelist summary exit ham processor.
Only applicable to non-spam (unclassified and ham) groups.")
@end lisp
@item
-functionality
+Gnus parameters
+Add
@lisp
-(defun spam-blackbox-register-spam-routine ()
- (spam-generic-register-routine
- ;; @r{the spam function}
- (lambda (article)
- (let ((from (spam-fetch-field-from-fast article)))
- (when (stringp from)
- (blackbox-do-something-with-this-spammer from))))
- ;; @r{the ham function}
- nil))
-
-(defun spam-blackbox-register-ham-routine ()
- (spam-generic-register-routine
- ;; @r{the spam function}
- nil
- ;; @r{the ham function}
- (lambda (article)
- (let ((from (spam-fetch-field-from-fast article)))
- (when (stringp from)
- (blackbox-do-something-with-this-ham-sender from))))))
+(const :tag "Spam: Blackbox" (spam spam-use-blackbox))
+(const :tag "Ham: Blackbox" (ham spam-use-blackbox))
@end lisp
+to the @code{spam-process} group parameter in @code{gnus.el}. Make
+sure you do it twice, once for the parameter and once for the
+variable customization.
-Write the @code{blackbox-do-something-with-this-ham-sender} and
-@code{blackbox-do-something-with-this-spammer} functions. You can add
-more complex code than fetching the message sender, but keep in mind
-that retrieving the whole message takes significantly longer than the
-sender through @code{spam-fetch-field-from-fast}, because the message
-senders are kept in memory by Gnus.
+Add
+@lisp
+(variable-item spam-use-blackbox)
+@end lisp
+to the @code{spam-autodetect-methods} group parameter in
+@code{gnus.el}.
@end enumerate
@lisp
(setq nnmail-split-fancy
`(| (: spam-stat-split-fancy)
- "mail.misc"))
+ "mail.misc"))
@end lisp
@defvar spam-stat-split-fancy-spam-group
@lisp
(setq nnmail-split-fancy
`(| ("Subject" "\\bspam-stat\\b" "mail.emacs")
- (: spam-stat-split-fancy)
- "mail.misc"))
+ (: spam-stat-split-fancy)
+ "mail.misc"))
@end lisp
If you want to filter for spam first, then you must be careful when
(setq nnmail-split-fancy
`(| (: spam-stat-split-fancy)
("Subject" "\\bspam-stat\\b" "mail.emacs")
- "mail.misc"))
+ "mail.misc"))
@end lisp
You can combine this with traditional filtering. Here, we move all
@lisp
(setq nnmail-split-fancy
`(| ("Content-Type" "text/html" "mail.spam.filtered")
- (: spam-stat-split-fancy)
+ (: spam-stat-split-fancy)
("Subject" "\\bspam-stat\\b" "mail.emacs")
- "mail.misc"))
+ "mail.misc"))
@end lisp
Save table: (spam-stat-save)
@end smallexample
+@node Other modes
+@section Interaction with other modes
+
+@subsection Dired
+@cindex dired
+
+@code{gnus-dired-minor-mode} provided some useful functions for dired
+buffers. It is enabled with
+@lisp
+(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
+@end lisp
+
+@table @kbd
+@item C-c C-m C-a
+@findex gnus-dired-attach
+Send dired's marked files as an attachment (@code{gnus-dired-attach}).
+You will be prompted for a message buffer.
+
+@item C-c C-m C-l
+@findex gnus-dired-find-file-mailcap
+Visit a file according to the appropriate mailcap entry
+(@code{gnus-dired-find-file-mailcap}). With prefix, open file in a new
+buffer.
+
+@item C-c C-m C-p
+@findex gnus-dired-print
+Print file according to the mailcap entry (@code{gnus-dired-print}). If
+there is no print command, print in a PostScript image.
+@end table
+
@node Various Various
@section Various Various
@cindex mode lines
XEmacs is distributed as a collection of packages. You should install
whatever packages the Gnus XEmacs package requires. The current
-requirements are @samp{gnus}, @samp{w3}, @samp{mh-e},
-@samp{mailcrypt}, @samp{rmail}, @samp{eterm}, @samp{mail-lib},
-@samp{xemacs-base}, @samp{sh-script} and @samp{fsf-compat}. The
-@samp{misc-games} package is required for Morse decoding.
+requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base},
+@samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils},
+@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{w3},
+@samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}.
@node History
@cindex Mule
@cindex Emacs
-Gnus should work on :
+Gnus should work on:
@itemize @bullet
@item
-Emacs 20.7 and up.
+Emacs 21.1 and up.
@item
-XEmacs 21.1 and up.
+XEmacs 21.4 and up.
@end itemize
Kim-Minh Kaplan---further work on the picon code.
@item
-Brad Miller---@file{gnus-gl.el} and the GroupLens manual section
-(@pxref{GroupLens}).
+Brad Miller---@file{gnus-gl.el} and the GroupLens manual section.
@item
Sudish Joseph---innumerable bug fixes.
Kevin Davidson---came up with the name @dfn{ding}, so blame him.
@item
-François Pinard---many, many interesting and thorough bug reports, as
+Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as
well as autoconf support.
@end itemize
Jesper Harder,
Paul Jarc,
Simon Josefsson,
-David Kågedal,
+David K@aa{}gedal,
Richard Pieri,
Fabrice Popineau,
Daniel Quinlan,
Richard Hoskins,
Brad Howes,
Miguel de Icaza,
-François Felix Ingrand,
+Fran@,{c}ois Felix Ingrand,
Tatsuya Ichikawa, @c Ichikawa
Ishikawa Ichiro, @c Ishikawa
Lee Iverson,
* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7.
* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9.
* Oort Gnus:: It's big. It's far out. Gnus 5.10.
+* No Gnus:: Lars, FIXME!
@end menu
These lists are, of course, just @emph{short} overviews of the
referred.
@item
-Gnus can make use of GroupLens predictions (@pxref{GroupLens}).
+Gnus can make use of GroupLens predictions.
@item
Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}).
@itemize @bullet
+@item
+@kbd{F} (@code{gnus-article-followup-with-original}) and @kbd{R}
+(@code{gnus-article-reply-with-original}) only yank the text in the
+region if the region is active.
+
+@item
+@code{gnus-group-read-ephemeral-group} can be called interactively,
+using @kbd{G M}.
+
+@item
+In draft groups, @kbd{e} is now bound to @code{gnus-draft-edit-message}.
+Use @kbd{B w} for @code{gnus-summary-edit-article} instead.
+
@item
The revised Gnus @acronym{FAQ} is included in the manual,
@xref{Frequently Asked Questions}.
@item
Dired integration
-@code{gnus-dired-minor-mode} installs key bindings in dired buffers to send
-a file as an attachment (@kbd{C-c C-a}), open a file using the appropriate
-mailcap entry (@kbd{C-c C-l}), and print a file using the mailcap entry
-(@kbd{C-c P}). It is enabled with
-@lisp
-(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
-@end lisp
+@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key
+bindings in dired buffers to send a file as an attachment, open a file
+using the appropriate mailcap entry, and print a file using the mailcap
+entry.
@item
Gnus can display RSS newsfeeds as a newsgroup. @xref{RSS}.
@lisp
(setq gnus-parameters
'(("mail\\..*"
- (gnus-show-threads nil)
- (gnus-use-scoring nil))
- ("^nnimap:\\(foo.bar\\)$"
- (to-group . "\\1"))))
+ (gnus-show-threads nil)
+ (gnus-use-scoring nil))
+ ("^nnimap:\\(foo.bar\\)$"
+ (to-group . "\\1"))))
@end lisp
@item
The old format like the lines below is obsolete, but still accepted.
@lisp
(header "to" "larsi.*org"
- (Organization "Somewhere, Inc."))
+ (Organization "Somewhere, Inc."))
@end lisp
@item
This change was made to avoid conflict with the standard binding of
@code{back-to-indentation}, which is also useful in message mode.
+
+@item
+The default for @code{message-forward-show-mml} changed to symbol @code{best}.
+
+The behaviour for the @code{best} value is to show @acronym{MML} (i.e.,
+convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be
+used when forwarding signed or encrypted messages, as the conversion
+invalidate the digital signature.
@end itemize
+@node No Gnus
+@subsubsection No Gnus
+@cindex No Gnus
+
+New features in No Gnus:
+@c FIXME: Gnus 5.12?
+
+@include gnus-news.texi
+
@iftex
@page
@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
summary buffer faster.
+Gnus uses the internal ELisp-based @code{uncompface} program for
+decoding an @code{X-Face} header normally in Emacs. If you feel it is
+slow, set @code{uncompface-use-external} to @code{t}. @xref{X-Face}.
+
@page
@node Troubleshooting
@item
Try doing an @kbd{M-x gnus-version}. If you get something that looks
-like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If,
-on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp
-flee}, you have some old @file{.el} files lying around. Delete these.
+like @samp{Gnus v5.10.6} you have the right files loaded. Otherwise
+you have some old @file{.el} files lying around. Delete these.
@item
Read the help group (@kbd{G h} in the group buffer) for a
@c mode: texinfo
@c coding: iso-8859-1
@c End:
+
+@ignore
+ arch-tag: c9fa47e7-78ca-4681-bda9-9fef45d1c819
+@end ignore
projects / gnus / blobdiff