Synch with Gnus.
[elisp/gnus.git-] / texi / gnus.texi
index d977d6f..7bbbb71 100644 (file)
@@ -277,15 +277,20 @@ Copyright \copyright{} 1995,96,97,98,99,2000 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being none, with the Front-Cover texts being ``A GNU
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
 license is included in the section entitled ``GNU Free Documentation
-License''.
+License'' in the Emacs manual.
 
 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
 this GNU Manual, like GNU software.  Copies published by the Free
 Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
 \newpage
 \end{titlepage}
 @end iflatex
@@ -303,11 +308,16 @@ any later version published by the Free Software Foundation; with the
 Invariant Sections being none, with the Front-Cover texts being ``A GNU
 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
 license is included in the section entitled ``GNU Free Documentation
-License''.
+License'' in the Emacs manual.
 
 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
 this GNU Manual, like GNU software.  Copies published by the Free
 Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
 @end ifnottex
 
 @tex
@@ -321,17 +331,22 @@ Software Foundation raise funds for GNU development.''
 @vskip 0pt plus 1filll
 Copyright @copyright{} 1995,96,97,98,99,2000 Free Software Foundation, Inc.
 
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
 
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
 
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
 
 @end titlepage
 @page
@@ -692,6 +707,7 @@ Gnus Unplugged
 * Agent Categories::       How to tell the Gnus Agent what to download.
 * Agent Commands::         New commands for all the buffers.
 * Agent Expiry::           How to make old articles go away.
+* Agent and IMAP::         How to use the Agent with IMAP.
 * Outgoing Messages::      What happens when you post/mail something?
 * Agent Variables::        Customizing is fun.
 * Example Setup::          An example @file{.gnus.el} file for offline people.
@@ -724,7 +740,7 @@ Scoring
 * Reverse Scoring::          That problem child of old is not problem.
 * Global Score Files::       Earth-spanning, ear-splitting score files.
 * Kill Files::               They are still here, but they can be ignored.
-@c * Converting Kill Files::    Translating kill files to score files.
+* 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.
@@ -2169,6 +2185,27 @@ reasons of efficiency.
 It is recommended that you keep all your mail groups (if any) on quite
 low levels (e.g. 1 or 2).
 
+Maybe the following description of the default behavior of Gnus helps to
+understand what these levels are all about.  By default, Gnus shows you
+subscribed nonempty groups, but by hitting @kbd{L} you can have it show
+empty subscribed groups and unsubscribed groups, too.  Type @kbd{l} to
+go back to showing nonempty subscribed groups again.  Thus, unsubscribed
+groups are hidden, in a way.
+
+Zombie and killed groups are similar to unsubscribed groups in that they
+are hidden by default.  But they are different from subscribed and
+unsubscribed groups in that Gnus doesn't ask the news server for
+information (number of messages, number of unread messages) on zombie
+and killed groups.  Normally, you use @kbd{C-k} to kill the groups you
+aren't interested in.  If most groups are killed, Gnus is faster.
+
+Why does Gnus distinguish between zombie and killed groups?  Well, when
+a new group arrives on the server, Gnus by default makes it a zombie
+group.  This means that you are normally not bothered with new groups,
+but you can type @kbd{A z} to get a list of all new groups.  Subscribe
+the ones you like and kill the ones you don't want.  (@kbd{A k} shows a
+list of killed groups.)
+
 If you want to play with the level variables, you should show some care.
 Set them once, and don't touch them ever again.  Better yet, don't touch
 them at all unless you know exactly what you're doing.
@@ -7179,7 +7216,9 @@ the @code{banner} group parameter (@pxref{Group Parameters}) to the
 group you want banners stripped from.  The parameter either be a string,
 which will be interpreted as a regular expression matching text to be
 removed, or the symbol @code{signature}, meaning that the (last)
-signature should be removed.
+signature should be removed, or other symbol, meaning that the
+corresponding regular expression in @code{gnus-article-banner-alist} is
+used.
 
 @item W W c
 @kindex W W c (Summary)
@@ -9419,6 +9458,7 @@ This is the delimiter mentioned above.  By default, it is @samp{^L}
 @cindex reply
 @cindex followup
 @cindex post
+@cindex using gpg
 
 @kindex C-c C-c (Post)
 All commands for posting and mailing will put you in a message buffer
@@ -9436,6 +9476,7 @@ on your setup (@pxref{Posting Server}).
 * Posting Styles::       An easier way to specify who you are.
 * Drafts::               Postponing messages and rejected messages.
 * Rejected Articles::    What happens if the server doesn't like your article?
+* Using GPG::            How to use GPG and MML to sign and encrypt messages
 @end menu
 
 Also see @pxref{Canceling and Superseding} for information on how to
@@ -9626,6 +9667,16 @@ This variable can be used to do the following:
 @itemize @bullet
 @item a string
 Messages will be saved in that group.
+
+Note that you can include a select method in the group name, then the
+message will not be stored in the select method given by
+@code{gnus-message-archive-method}, but in the select method specified
+by the group name, instead.  Suppose @code{gnus-message-archive-method}
+has the default value shown above.  Then setting
+@code{gnus-message-archive-group} to @code{"foo"} means that outgoing
+messages are stored in @samp{nnfolder+archive:foo}, but if you use the
+value @code{"nnml:foo"}, then outgoing messages will be stored in
+@samp{nnml:foo}.
 @item a list of strings
 Messages will be saved in all those groups.
 @item an alist of regexps, functions and forms
@@ -9796,7 +9847,7 @@ So here's a new example:
          (signature my-quote-randomizer))
         ((message-news-p)
          (signature my-news-signature))
-        (header "From.*To" "larsi.*org"
+        (header "From\\|To" "larsi.*org"
          (Organization "Somewhere, Inc."))
         ((posting-from-work-p)
          (signature-file "~/.work-signature")
@@ -9899,6 +9950,48 @@ The rejected articles will automatically be put in a special draft group
 (@pxref{Drafts}).  When the server comes back up again, you'd then
 typically enter that group and send all the articles off.
 
+@node Using GPG
+@section Using GPG
+@cindex using gpg
+
+Gnus has an ALPHA support to GPG that's provided by @file{gpg.el} and
+@file{mml2015.el}. When viewing signed or encrypted messages, Gnus automatically
+asks if you want to verify or decrypt them. 
+
+To use this correctly with GPG, you'll need the following lisp code in your
+@file{~/.emacs} or @file{~/.gnus}:
+
+@lisp
+(setq mml2015-use 'gpg)
+(setq gpg-temp-directory "~/.gnupg/tmp")
+@end lisp
+
+The @code{gpg-temp-directory} need to point to a directory with permissions set
+to 700, for your own safety.
+
+If you want to benefit of PGP2.6 compatibility, you might create a script named
+@file{gpg-2comp} with these instructions:
+
+@code{
+#!/bin/sh
+exec gpg --rfc1991 "$@@"
+}
+
+If you don't want to use such compatibility, you can add the following line to
+your @file{~/.emacs} or @file{~/.gnus}:
+
+@lisp
+(setq gpg-command-default-alist (quote ((gpg . "gpg") (gpg-2comp . "gpg"))))
+@end lisp
+
+To sign or encrypt your message you may choose to use the MML Security menu or
+@kbd{M-m s p} to sign your message using PGP/MIME, @kbd{M-m s s} to sign your
+message using S/MIME. There's also @kbd{M-m c p} to encrypt your message with
+PGP/MIME and @kbd{M-m c s} to encrypt using S/MIME.
+
+Gnus will ask for your passphrase three times and then it will send your
+message, if you've typed it correctly.
+
 
 @node Select Methods
 @chapter Select Methods
@@ -10382,15 +10475,17 @@ manual page, but here are the salient facts:
 The file contains one or more line, each of which define one server.
 
 @item
-Each line may contain an arbitrary number of token/value pairs.  The
-valid tokens include @samp{machine}, @samp{login}, @samp{password},
-@samp{default}, @samp{port} and @samp{force}.  (The latter is not a
-valid @file{.netrc}/@code{ftp} token, which is almost the only way the
-@file{.authinfo} file format deviates from the @file{.netrc} file
-format.)
-
+Each line may contain an arbitrary number of token/value pairs.  
 @end enumerate
 
+The valid tokens include @samp{machine}, @samp{login}, @samp{password},
+@samp{default}.  Gnus introduce two new tokens, not present in the
+original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and
+@samp{force}.  (This is the only way the @file{.authinfo} file format
+deviates from the @file{.netrc} file format.) @samp{port} is used to
+indicate what port on the server the credentials apply to, @samp{force}
+is explained below.
+
 Here's an example file:
 
 @example
@@ -11297,8 +11392,8 @@ Then all articles in the mailbox is fetched, no matter what.  For a
 complete list of predicates, see RFC 2060 §6.4.4.
 
 @item :fetchflag
-How to flag fetched articles on the server, the default @samp{Deleted}
-will mark them as deleted, an alternative would be @samp{Seen} which
+How to flag fetched articles on the server, the default @samp{\Deleted}
+will mark them as deleted, an alternative would be @samp{\Seen} which
 would simply mark them as read.  These are the two most likely choices,
 but more flags are defined in RFC 2060 §2.3.2.
 
@@ -11684,6 +11779,40 @@ matched string will be substituted.  Similarly, the elements @samp{\\1}
 up to @samp{\\9} will be substituted with the text matched by the
 groupings 1 through 9.
 
+@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
+you can't make splitting rules for all your mail.  For example, your
+boss might send you personal mail regarding different projects you are
+working on, and as you can't tell your boss to put a distinguishing
+string into the subject line, you have to resort to manually moving the
+messages into the right group.  With this function, you only have to do
+it once per thread.
+
+To use this feature, you have to set @code{nnmail-treat-duplicates} to a
+non-nil value.  And then you can include
+@code{nnmail-split-fancy-with-parent} using the colon feature, like so:
+@lisp
+(setq nnmail-split-fancy
+      '(| (: nnmail-split-fancy-with-parent)
+          ;; other splits go here
+        ))
+@end lisp
+
+This feature works as follows: when @code{nnmail-treat-duplicates} is
+non-nil, Gnus records the message id of every message it sees in the
+file specified by the variable @code{nnmail-message-id-cache-file},
+together with the group it is in (the group is omitted for non-mail
+messages).  When mail splitting is invoked, the function
+@code{nnmail-split-fancy-with-parent} then looks at the References (and
+In-Reply-To) header of each message to split and searches the file
+specified by @code{nnmail-message-id-cache-file} for the message ids.
+When it has found a parent, it returns the corresponding group name.  It
+is recommended that you set @code{nnmail-message-id-cache-length} to a
+somewhat higher number than the default so that the message ids are
+still in the cache.  (A value of 5000 appears to create a file some
+300 kBytes in size.)
+
 
 @node Group Mail Splitting
 @subsection Group Mail Splitting
@@ -13580,6 +13709,33 @@ think of it as a modernized @sc{nntp}.  Connecting to a @sc{imap} server
 is much similar to connecting to a news server, you just specify the
 network address of the server.
 
+A server configuration in @code{~/.gnus} with a few @sc{imap} servers
+might look something like this:
+
+@lisp
+(setq gnus-secondary-select-methods 
+      '((nnimap "simpleserver") ; no special configuration
+        ; perhaps a ssh port forwarded server:
+        (nnimap "dolk"
+                (nnimap-address "localhost")
+                (nnimap-server-port 1430))
+        ; a UW server running on localhost
+        (nnimap "barbar"
+                (nnimap-server-port 143)
+                (nnimap-address "localhost")
+                (nnimap-list-pattern ("INBOX" "mail/*")))
+        ; anonymous public cyrus server:
+        (nnimap "cyrus.andrew.cmu.edu"
+                (nnimap-authenticator anonymous)
+                (nnimap-list-pattern "archive.*")
+                (nnimap-stream network))
+        ; a ssl server on a non-standard port:
+        (nnimap "vic20"
+                (nnimap-address "vic20.somewhere.com")
+                (nnimap-server-port 9930)
+                (nnimap-stream ssl))))
+@end lisp
+
 The following variables can be used to create a virtual @code{nnimap}
 server:
 
@@ -13805,7 +13961,8 @@ mailboxes to split from.  Defaults to nil, which means that splitting is
 disabled!
 
 @lisp
-(setq nnimap-split-inbox '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
+(setq nnimap-split-inbox
+      '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap"))
 @end lisp
 
 No nnmail equivalent.
@@ -13824,9 +13981,9 @@ Neither did I, we need examples.
 
 @lisp
 (setq nnimap-split-rule
-        '(("INBOX.nnimap"        "^Sender: owner-nnimap@@vic20.globalcom.se")
-          ("INBOX.junk"          "^Subject:.*MAKE MONEY")
-          ("INBOX.private"       "")))
+      '(("INBOX.nnimap"  "^Sender: owner-nnimap@@vic20.globalcom.se")
+        ("INBOX.junk"    "^Subject:.*MAKE MONEY")
+        ("INBOX.private" "")))
 @end lisp
 
 This will put all articles from the nnimap mailing list into mailbox
@@ -14165,6 +14322,7 @@ Of course, to use it as such, you have to learn a few new commands.
 * Agent Categories::       How to tell the Gnus Agent what to download.
 * Agent Commands::         New commands for all the buffers.
 * Agent Expiry::           How to make old articles go away.
+* Agent and IMAP::         How to use the Agent with IMAP.
 * Outgoing Messages::      What happens when you post/mail something?
 * Agent Variables::        Customizing is fun.
 * Example Setup::          An example @file{.gnus.el} file for offline people.
@@ -14703,6 +14861,12 @@ Remove the current group from its category, if any
 (@code{gnus-agent-remove-group}).  This command understands the
 process/prefix convention (@pxref{Process/Prefix}).
 
+@item J Y
+@kindex J Y (Agent Group)
+@findex gnus-agent-synchronize-flags
+Synchronize flags changed while unplugged with remote server, if any.
+
+
 @end table
 
 
@@ -14777,6 +14941,60 @@ expire all articles---unread, read, ticked and dormant.  If @code{nil}
 unread, ticked and dormant articles will be kept indefinitely.
 
 
+@node Agent and IMAP
+@subsection Agent and IMAP
+
+The Agent work with any Gnus backend, including nnimap.  However, since
+there are some conceptual differences between NNTP and IMAP, this
+section (should) provide you with some information to make Gnus Agent
+work smoother as a IMAP Disconnected Mode client.
+
+The first thing to keep in mind is that all flags (read, ticked, etc)
+are kept on the IMAP server, rather than in @code{.newsrc} as is the
+case for nntp.  Thus Gnus need to remember flag changes when
+disconnected, and synchronize these flags when you plug back in.
+
+Gnus keep track of flag changes when reading nnimap groups under the
+Agent by default.  When you plug back in, by default Gnus will check if
+you have any changed any flags and ask if you wish to synchronize theese
+with the server.  This behaviour is customizable with
+@code{gnus-agent-synchronize-flags}.
+
+@vindex gnus-agent-synchronize-flags
+If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will
+never automatically synchronize flags.  If it is @code{ask}, the
+default, the Agent will check if you made any changes and if so ask if
+you wish to synchronize these when you re-connect.  If it has any other
+value, all flags will be synchronized automatically.
+
+If you do not wish to automatically synchronize flags when you
+re-connect, this can be done manually with the
+@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y}
+in the group buffer by default.
+
+Some things are currently not implemented in the Agent that you'd might
+expect from a disconnected IMAP client, including:
+
+@itemize @bullet
+
+@item
+Copying/moving articles into nnimap groups when unplugged.
+
+@item
+Creating/deleting nnimap groups when unplugged.
+
+@end itemize
+
+Technical note: the synchronization algorithm does not work by "pushing"
+all local flags to the server, but rather incrementally update the
+server view of flags by changing only those flags that were changed by
+the user.  Thus, if you set one flag on a article, quit the group and
+re-select the group and remove the flag; the flag will be set and
+removed from the server when you "synchronize".  The queued flag
+operations can be found in the per-server @code{flags} file in the Agent
+directory.  It's emptied when you synchronize flags.
+
+
 @node Outgoing Messages
 @subsection Outgoing Messages
 
@@ -14940,7 +15158,7 @@ silently to help keep the sizes of the score files down.
 * Reverse Scoring::          That problem child of old is not problem.
 * Global Score Files::       Earth-spanning, ear-splitting score files.
 * Kill Files::               They are still here, but they can be ignored.
-@c * Converting Kill Files::    Translating kill files to score files.
+* 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.
@@ -16230,8 +16448,7 @@ A hook called in kill-file mode buffers.
 
 @end table
 
-@c The URL below is invalid and the code isn't on gnus.org.
-@ignore
+
 @node Converting Kill Files
 @section Converting Kill Files
 @cindex kill files
@@ -16244,13 +16461,12 @@ by hand.
 
 The kill to score conversion package isn't included in Gnus by default.
 You can fetch it from
-@file{http://www.stud.ifi.uio.no/~larsi/ding-other/gnus-kill-to-score}.
+@file{http://www.stud.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}.
 
 If your old kill files are very complex---if they contain more
 non-@code{gnus-kill} forms than not, you'll have to convert them by
 hand.  Or just let them be as they are.  Gnus will still use them as
 before.
-@end ignore
 
 
 @node GroupLens
@@ -17286,6 +17502,43 @@ window is displayed vertically next to another window, you may also want
 to fiddle with @code{gnus-tree-minimize-window} to avoid having the
 windows resized.
 
+@subsection Example Window Configurations
+
+@itemize @bullet
+@item 
+Narrow left hand side occupied by group buffer.  Right hand side split
+between summary buffer (top one-sixth) and article buffer (bottom).
+
+@ifinfo
+@example
++---+---------+
+| G | Summary |
+| r +---------+
+| o |         |
+| u | Article |
+| p |         |
++---+---------+
+@end example
+@end ifinfo
+
+@lisp
+(gnus-add-configuration
+ '(article
+   (horizontal 1.0
+               (vertical 25 (group 1.0))
+               (vertical 1.0
+                         (summary 0.16 point)
+                         (article 1.0)))))
+
+(gnus-add-configuration
+ '(summary
+   (horizontal 1.0
+               (vertical 25 (group 1.0))
+               (vertical 1.0 (summary 1.0 point)))))
+@end lisp
+
+@end itemize
+
 
 @node Faces and Fonts
 @section Faces and Fonts
@@ -17654,32 +17907,11 @@ default is @code{("news.lists.filters" "news.admin.net-abuse.bulletins"
 @vindex gnus-nocem-issuers
 There are many people issuing NoCeM messages.  This list says what
 people you want to listen to.  The default is @code{("Automoose-1"
-"rbraver@@ohww.norman.ok.us" "clewis@@ferret.ocunix.on.ca"
-"jem@@xpat.com" "snowhare@@xmission.com" "red@@redpoll.mrfs.oh.us
-(Richard E. Depew)")}; fine, upstanding citizens all of them.
+"clewis@@ferret.ocunix.on.ca" "cosmo.roadkill" "SpamHippo"
+"hweede@@snafu.de")}; fine, upstanding citizens all of them.
 
-Known despammers that you can put in this list include:
-
-@table @samp
-@item clewis@@ferret.ocunix.on.ca;
-@cindex Chris Lewis
-Chris Lewis---Major Canadian despammer who has probably canceled more
-usenet abuse than anybody else.
-
-@item Automoose-1
-@cindex CancelMoose[tm]
-The CancelMoose[tm] on autopilot.  The CancelMoose[tm] is reputed to be
-Norwegian, and was the person(s) who invented NoCeM.
-
-@item jem@@xpat.com;
-@cindex Jem
-John Milburn---despammer located in Korea who is getting very busy these
-days.
-
-@item red@@redpoll.mrfs.oh.us (Richard E. Depew)
-Richard E. Depew---lone American despammer.  He mostly cancels binary
-postings to non-binary groups and removes spews (regurgitated articles).
-@end table
+Known despammers that you can put in this list are listed at
+@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}.
 
 You do not have to heed NoCeM messages from all these people---just the
 ones you want to listen to.  You also don't have to accept all NoCeM
@@ -17744,6 +17976,18 @@ The number of days before removing old NoCeM entries from the cache.
 The default is 15.  If you make it shorter Gnus will be faster, but you
 might then see old spam.
 
+@item gnus-nocem-check-from
+@vindex gnus-nocem-check-from
+Non-@code{nil} means check for valid issuers in message bodies.
+Otherwise don't bother fetching articles unless their author matches a
+valid issuer; that is much faster if you are selective about the
+issuers.
+
+@item gnus-nocem-check-article-limit
+@vindex gnus-nocem-check-article-limit
+If non-@code{nil}, the maximum number of articles to check in any NoCeM
+group.  NoCeM groups can be huge and very slow to process.
+
 @end table
 
 Using NoCeM could potentially be a memory hog.  If you have many living
@@ -18802,9 +19046,9 @@ supposed to be able to use these, and these are mostly discussed on the
 @samp{gnu.emacs.gnus} newsgroup.
 
 @cindex Incoming*
-@vindex nnmail-delete-incoming
+@vindex mail-source-delete-incoming
 Some variable defaults differ between alpha Gnusae and released Gnusae.
-In particular, @code{nnmail-delete-incoming} defaults to @code{nil} in
+In particular, @code{mail-source-delete-incoming} defaults to @code{nil} in
 alpha Gnusae and @code{t} in released Gnusae.  This is to prevent
 lossage of mail if an alpha release hiccups while handling the mail.