+@node Group Mail Splitting
+@subsection Group Mail Splitting
+@cindex mail splitting
+@cindex group mail splitting
+
+@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
+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.
+
+Sometimes, mailing lists have multiple addresses, and you may want mail
+splitting to recognize them all: just set the @var{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}.
+
+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
+group. @var{RESTRICT}s are also supported: just set the
+@var{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
+this case, all other aforementioned parameters will be ignored by
+@code{gnus-group-split}. In particular, @var{split-spec} may be set to
+@code{nil}, in which case the group will be ignored by
+@code{gnus-group-split}.
+
+@vindex gnus-group-split-default-catch-all-group
+@code{gnus-group-split} will do cross-posting on all groups that match,
+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
+that group is used as the catch-all group. Note that, in this case,
+there's no cross-posting, as a @code{|} fancy split encloses the
+@code{&} split and the catch-all group.
+
+It's time for an example. Assume the following group parameters have
+been defined:
+
+@example
+nnml:mail.bar:
+((to-address . "bar@@femail.com")
+ (split-regexp . ".*@@femail\\.com"))
+nnml:mail.foo:
+((to-list . "foo@@nowhere.gov")
+ (extra-aliases "foo@@localhost" "foo-redist@@home")
+ (split-exclude "bugs-foo" "rambling-foo")
+ (admin-address . "foo-request@@nowhere.gov"))
+nnml:mail.others:
+((split-spec . catch-all))
+@end example
+
+Setting @code{nnmail-split-methods} to @code{gnus-group-split} will
+behave as if @code{nnmail-split-fancy} had been selected and variable
+@code{nnmail-split-fancy} had been set as follows:
+
+@lisp
+(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar")
+ (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)"
+ - "bugs-foo" - "rambling-foo" "mail.foo"))
+ "mail.others")
+@end lisp
+
+@findex gnus-group-split-fancy
+If you'd rather not use group splitting for all your mail groups, you
+may use it for only some of them, by using @code{nnmail-split-fancy}
+splits like this:
+
+@lisp
+(: gnus-mlsplt-fancy GROUPS NO-CROSSPOST CATCH-ALL)
+@end lisp
+
+@var{GROUPS} may be a regular expression or a list of group names whose
+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} may be the name
+of a group to be used as the default catch-all group. If
+@var{CATCH-ALL} is @code{nil}, or if @var{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},
+this group will override the value of the @var{CATCH-ALL} argument.
+
+@findex gnus-group-split-setup
+Unfortunately, scanning all groups and their parameters can be quite
+slow, especially considering that it has to be done for every message.
+But don't despair! The function @code{gnus-group-split-setup} can be
+used to select @code{gnus-group-split} in a much more efficient way. It
+sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets
+@code{nnmail-split-fancy} to the split produced by
+@code{gnus-group-split-fancy}. Thus, the group parameters are only
+scanned once, no matter how many messages are split.
+
+@findex gnus-group-split-update
+However, if you change group parameters, you have to update
+@code{nnmail-split-fancy} manually. You can do it by running
+@code{gnus-group-split-update}. If you'd rather have it updated
+automatically, just tell @code{gnus-group-split-setup} to do it for
+you. For example, add to your @file{.gnus}:
+
+@lisp
+(gnus-group-split-setup AUTO-UPDATE CATCH-ALL)
+@end lisp
+
+If @var{AUTO-UPDATE} is non-@code{nil}, @code{gnus-group-split-update}
+will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever
+have to worry about updating @code{nnmail-split-fancy} again. If you
+don't omit @var{CATCH-ALL} (it's optional),
+@code{gnus-group-split-default-catch-all-group} will be set to its
+value.
+
+@vindex gnus-group-split-updated-hook
+Because you may want to change @code{nnmail-split-fancy} after it is set
+by @code{gnus-group-split-update}, this function will run
+@code{gnus-group-split-updated-hook} just before finishing.
+
projects / elisp / gnus.git- / blobdiff