\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Oort Gnus v0.15}
+\newcommand{\gnusversionname}{Oort Gnus v0.18}
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}
spool or your mbox file. All at the same time, if you want to push your
luck.
-This manual corresponds to Oort Gnus v0.15.
+This manual corresponds to Oort Gnus v0.18.
@end ifinfo
* Article Washing:: Lots of way-neat functions to make life better.
* Article Header:: Doing various header transformations.
* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
+* Article Button Levels:: Controlling appearance of buttons.
* Article Date:: Grumble, UT!
* Article Display:: Display various stuff---X-Face, Picons, Smileys
* Article Signature:: What is a signature?
Choosing a Mail Back End
* Unix Mail Box:: Using the (quite) standard Un*x mbox.
-* Rmail Babyl:: Emacs programs use the rmail babyl format.
+* Rmail Babyl:: Emacs programs use the Rmail Babyl format.
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
+* Maildir:: Another one-file-per-message format.
* Mail Folders:: Having one file for each group.
* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
* 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.
+* Example Setup:: An example @file{~/.gnus.el} file for offline people.
* Batching Agents:: How to fetch news from a @code{cron} job.
* Agent Caveats:: What you think it'll do and what it does.
@kbd{M-x gnus-other-frame} instead.
If things do not go smoothly at startup, you have to twiddle some
-variables in your @file{~/.gnus} file. This file is similar to
+variables in your @file{~/.gnus.el} file. This file is similar to
@file{~/.emacs}, but is read when gnus starts.
If you puzzle at any terms used in this manual, please refer to the
If non-@code{nil}, the startup message won't be displayed. That way,
your boss might not notice as easily that you are reading news instead
of doing your job. Note that this variable is used before
-@file{.gnus.el} is loaded, so it should be set in @file{.emacs} instead.
+@file{~/.gnus.el} is loaded, so it should be set in @file{.emacs} instead.
@item gnus-no-groups-message
@vindex gnus-no-groups-message
comment element in the group parameters.
@item D
-Newsgroup description.
+Newsgroup description. You need to read the group descriptions
+before these will appear, and to do that, you either have to set
+@code{gnus-read-active-file} or use the group buffer @kbd{M-d}
+command.
@item o
@samp{m} if moderated.
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. Look here @pxref{(message)Mailing
-Lists} for a complete treatment of available MFT support.
+headers for your posts to these lists. Look here @pxref{Mailing
+Lists, , Mailing Lists, message, The Message Manual} for a complete
+treatment of available MFT support.
See also @code{gnus-find-subscribed-addresses}, the function that
directly uses this group parameter.
@item broken-reply-to
@cindex broken-reply-to
Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To}
-headers in this group are to be ignored. This can be useful if you're
-reading a mailing list group where the listserv has inserted
-@code{Reply-To} headers that point back to the listserv itself. This is
-broken behavior. So there!
+headers in this group are to be ignored, and for the header to be hidden
+if @code{reply-to} is part of @code{gnus-boring-article-headers}. This
+can be useful if you're reading a mailing list group where the listserv
+has inserted @code{Reply-To} headers that point back to the listserv
+itself. That is broken behavior. So there!
@item to-group
@cindex to-group
in the summary buffer you enter, and the form @code{nil} will be
@code{eval}ed there.
+Note that this feature sets the variable locally to the summary buffer.
+But some variables are evaluated in the article buffer, or in the
+message buffer (of a reply or followup or otherwise newly created
+message). As a workaround, it might help to add the variable in
+question to @code{gnus-newsgroup-variables}. @xref{Various Summary
+Stuff}. So if you want to set @code{message-from-style} via the group
+parameters, then you may need the following statement elsewhere in your
+@file{~/.gnus} file:
+@lisp
+(add-to-list 'gnus-newsgroup-variables 'message-from-style)
+@end lisp
+
@vindex gnus-list-identifiers
A use for this feature, is to remove a mailing list identifier tag in
the subject fields of articles. E.g. if the news group
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
@code{gnus-after-exiting-gnus-hook} is called as the final item when
exiting Gnus.
-@findex gnus-unload
-@cindex unloading
-If you wish to completely unload Gnus and all its adherents, you can use
-the @code{gnus-unload} command. This command is also very handy when
-trying to customize meta-variables.
-
Note:
@quotation
If you want this permanently enabled, you should add that minor mode to
the hook for the group mode. Put the following line in your
-@file{~/.gnus} file:
+@file{~/.gnus.el} file:
@lisp
(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
and displayed in an ephemeral group.
Note that the control messages are compressed. To use this command
-you need to turn on @code{auto-compression-mode}
-(@pxref{(emacs)Compressed Files}).
+you need to turn on @code{auto-compression-mode} (@pxref{Compressed
+Files, ,Compressed Files, emacs, The Emacs Manual}).
@item H d
@itemx C-c C-d
@vindex gnus-init-file
@cindex reading init file
Re-read the init file (@code{gnus-init-file}, which defaults to
-@file{~/.gnus}) (@code{gnus-group-read-init-file}).
+@file{~/.gnus.el}) (@code{gnus-group-read-init-file}).
@item s
@kindex s (Group)
@item gnus-sum-thread-tree-root
@vindex gnus-sum-thread-tree-root
Used for the root of a thread. If @code{nil}, use subject
-instead. The default is @samp{> }.
+instead. The default is @samp{> }.
+
+@item gnus-sum-thread-tree-false-root
+@vindex gnus-sum-thread-tree-false-root
+Used for the false root of a thread (@pxref{Loose Threads}). If
+@code{nil}, use subject instead. The default is @samp{> }.
@item gnus-sum-thread-tree-single-indent
@vindex gnus-sum-thread-tree-single-indent
@code{gnus-summary-line-format} variable.
In summary, you'd typically put something like the following in
-@file{~/.gnus}:
+@file{~/.gnus.el}:
@lisp
(setq gnus-extra-headers
next article (@code{gnus-summary-next-page}).
@vindex gnus-article-boring-faces
-If the rest of the article consists only of citations and signature,
-then it will be skipped; the next article will be shown instead. You
-can customize what is considered uninteresting with
-@code{gnus-article-boring-faces}, or set it to @code{nil} to disable
-this feature. You can manually view the article's pages, no matter how
-boring, using @kbd{C-v} in the article buffer.
+@vindex gnus-article-skip-boring
+If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of
+the article consists only of citations and signature, then it will be
+skipped; the next article will be shown instead. You can customize
+what is considered uninteresting with
+@code{gnus-article-boring-faces}. You can manually view the article's
+pages, no matter how boring, using @kbd{C-M-v}.
@item DEL
@kindex DEL (Summary)
@findex gnus-summary-reply-broken-reply-to
Mail a reply to the author of the current article but ignore the
@code{Reply-To} field (@code{gnus-summary-reply-broken-reply-to}).
+If you need this because a mailing list incorrectly sets a
+@code{Reply-To} header pointing to the list, you probably want to set
+the @code{broken-reply-to} group parameter instead, so things will work
+correctly. @xref{Group Parameters}.
@item S B R
@kindex S B R (Summary)
@item O r
@kindex O r (Summary)
@findex gnus-summary-save-article-rmail
-Save the current article in rmail format
+Save the current article in Rmail format
(@code{gnus-summary-save-article-rmail}).
@item O f
@findex gnus-summary-save-in-rmail
@vindex gnus-rmail-save-name
@findex gnus-plain-save-name
-This is the default format, @dfn{babyl}. Uses the function in the
+This is the default format, @dfn{Babyl}. Uses the function in the
@code{gnus-rmail-save-name} variable to get a file name to save the
article in. The default is @code{gnus-plain-save-name}.
* Article Washing:: Lots of way-neat functions to make life better.
* Article Header:: Doing various header transformations.
* Article Buttons:: Click on URLs, Message-IDs, addresses and the like.
+* Article Button Levels:: Controlling appearance of buttons.
* Article Date:: Grumble, UT!
* Article Display:: Display various stuff---X-Face, Picons, Smileys
* Article Signature:: What is a signature?
@vindex gnus-article-wash-function
The default is to use the function specified by
-@code{mm-text-html-renderer} (@pxref{(emacs-mime)Display
-Customization}) to convert the @sc{html}, but this is controlled by
-the @code{gnus-article-wash-function} variable. Pre-defined functions
-you can use include:
+@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display
+Customization, emacs-mime, The Emacs MIME Manual}) to convert the
+@sc{html}, but this is controlled by the
+@code{gnus-article-wash-function} variable. Pre-defined functions you
+can use include:
@table @code
@item w3
@vindex gnus-button-man-handler
Gnus adds @dfn{buttons} to certain standard references by default:
-Well-formed URLs, mail addresses, Message-IDs, Info links and man pages.
-This is controlled by two variables, one that handles article bodies and
-one that handles article heads:
+Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and
+Emacs or Gnus related references. This is controlled by two variables,
+one that handles article bodies and one that handles article heads:
@table @code
considered an external reference. Here's a typical regexp that matches
embedded URLs: @samp{<URL:\\([^\n\r>]*\\)>}. This can also be a
variable containing a regexp, useful variables to use include
-@code{gnus-button-url-regexp}.
+@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}.
@item button-par
Gnus has to know which parts of the matches is to be highlighted. This
@item use-p
This form will be @code{eval}ed, and if the result is non-@code{nil},
this is considered a match. This is useful if you want extra sifting to
-avoid false matches.
+avoid false matches. Often variables named
+@code{gnus-button-@var{*}-level} are used here, @xref{Article Button
+Levels}, but any other form may be used too.
+
+@c @code{use-p} is @code{eval}ed only if @code{regexp} matches.
@item function
This function will be called when you click on this button.
@var{header} is a regular expression.
+@subsubheading Related variables and functions
+
+@item gnus-button-@var{*}-level
+@xref{Article Button Levels}.
+
+@c Stuff related to gnus-button-browse-level
+
@item gnus-button-url-regexp
@vindex gnus-button-url-regexp
A regular expression that matches embedded URLs. It is used in the
default values of the variables above.
+@c Stuff related to gnus-button-man-level
+
+@item gnus-button-man-handler
+@vindex gnus-button-man-handler
+The function to use for displaying man pages. It must take at least one
+argument with a string naming the man page.
+
+@c Stuff related to gnus-button-message-level
+
+@item gnus-button-mid-or-mail-regexp
+@vindex gnus-button-mid-or-mail-regexp
+Regular expression that matches a message ID or a mail address.
+
+@item gnus-button-prefer-mid-or-mail
+@vindex gnus-button-prefer-mid-or-mail
+This variable determines what to do when the button on a string as
+@samp{foo123@@bar.invalid} is pushed. Strings like this can be either a
+message ID or a mail address. If it is one of the symbols @code{mid} or
+@code{mail}, Gnus will always assume that the string is a message ID or
+a mail address, respectivly. If this variable is set to the symbol
+@code{ask}, always query the user what do do. If it is a function, this
+function will be called with the string as it's only argument. The
+function must return @code{mid}, @code{mail}, @code{invalid} or
+@code{ask}. The default value is the function
+@code{gnus-button-mid-or-mail-heuristic}.
+
+@item gnus-button-mid-or-mail-heuristic
+@findex gnus-button-mid-or-mail-heuristic
+Function that guesses whether it's argument is a message ID or a mail
+address. Returns @code{mid} it's a message IDs, @code{mail} if it's a
+mail address, @code{ask} if unsure and @code{invalid} if the string is
+invalid.
+
+@item gnus-button-mid-or-mail-heuristic-alist
+@vindex gnus-button-mid-or-mail-heuristic-alist
+An alist of @code{(RATE . REGEXP)} pairs used by the function
+@code{gnus-button-mid-or-mail-heuristic}.
+
+@c Stuff related to gnus-button-tex-level
+
+@item gnus-button-ctan-handler
+@findex gnus-button-ctan-handler
+The function to use for displaying CTAN links. It must take one
+argument, the string naming the URL.
+
+@item gnus-ctan-url
+@vindex gnus-ctan-url
+Top directory of a CTAN (Comprehensive TeX Archive Network) archive used
+by @code{gnus-button-ctan-handler}.
+
+@c Misc stuff
+
@item gnus-article-button-face
@vindex gnus-article-button-face
Face used on buttons.
@xref{Customizing Articles}, for how to buttonize articles automatically.
+@node Article Button Levels
+@subsection Article button levels
+@cindex button levels
+The higher the value of the variables @code{gnus-button-@var{*}-level},
+the more buttons will appear. If the level is zero, no corresponding
+buttons are displayed. With the default value (which is 5) you should
+already see quite a lot of buttons. With higher levels, you will see
+more buttons, but you may also get more false positives. To avoid them,
+you can set the variables @code{gnus-button-@var{*}-level} local to
+specific groups (@pxref{Group Parameters}). Here's an example for the
+variable @code{gnus-parameters}:
+
+@lisp
+;; increase `gnus-button-*-level' in some groups:
+(setq gnus-parameters
+ '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10))
+ ("\\<unix\\>" (gnus-button-man-level 10))
+ ("\\<tex\\>" (gnus-button-tex-level 10))))
+@end lisp
+
+@table @code
+
+@item gnus-button-browse-level
+@vindex gnus-button-browse-level
+Controls the display of references to message IDs, mail addresses and
+news URLs. Related variables and functions include
+@code{gnus-button-url-regexp}, @code{browse-url}, and
+@code{browse-url-browser-function}.
+
+@item gnus-button-emacs-level
+@vindex gnus-button-emacs-level
+Controls the display of Emacs or Gnus references. Related functions are
+@code{gnus-button-handle-custom},
+@code{gnus-button-handle-describe-function},
+@code{gnus-button-handle-describe-variable},
+@code{gnus-button-handle-symbol},
+@code{gnus-button-handle-describe-key},
+@code{gnus-button-handle-apropos},
+@code{gnus-button-handle-apropos-command},
+@code{gnus-button-handle-apropos-variable},
+@code{gnus-button-handle-apropos-documentation}, and
+@code{gnus-button-handle-library}.
+
+@item gnus-button-man-level
+@vindex gnus-button-man-level
+Controls the display of references to (Unix) man pages.
+See @code{gnus-button-man-handler}.
+
+@item gnus-button-message-level
+@vindex gnus-button-message-level
+Controls the display of message IDs, mail addresses and news URLs.
+Related variables and functions include
+@code{gnus-button-mid-or-mail-regexp},
+@code{gnus-button-prefer-mid-or-mail},
+@code{gnus-button-mid-or-mail-heuristic}, and
+@code{gnus-button-mid-or-mail-heuristic-alist}.
+
+@item gnus-button-tex-level
+@vindex gnus-button-tex-level
+Controls the display of references to TeX or LaTeX stuff, e.g. for CTAN
+URLs. See the variables @code{gnus-ctan-url},
+@code{gnus-button-ctan-handler},
+@code{gnus-button-ctan-directory-regexp}, and
+@code{gnus-button-handle-ctan-bogus-regexp}.
+
+@end table
+
+
@node Article Date
@subsection Article Date
(gnus-start-date-timer)
@end lisp
-in your @file{.gnus.el} file, or you can run it off of some hook. If
+in your @file{~/.gnus.el} file, or you can run it off of some hook. If
you want to stop the timer, you can use the @code{gnus-stop-date-timer}
command.
displayed or this variable is overridden by
@code{gnus-buttonized-mime-types}. The default value is
@code{(".*/.*")}. This variable is only used when
-@code{gnus-inhibit-mime-unbuttonizing} is nil.
+@code{gnus-inhibit-mime-unbuttonizing} is @code{nil}.
@item gnus-buttonized-mime-types
@vindex gnus-buttonized-mime-types
displayed. This variable overrides
@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}.
This variable is only used when @code{gnus-inhibit-mime-unbuttonizing}
-is nil.
+is @code{nil}.
To see e.g. security buttons but no other buttons, you could set this
variable to @code{("multipart/signed")} and leave
@item gnus-inhibit-mime-unbuttonizing
@vindex gnus-inhibit-mime-unbuttonizing
-If this is non-nil, then all @sc{mime} parts get buttons. The default
-value is @code{nil}.
+If this is non-@code{nil}, then all @sc{mime} parts get buttons. The
+default value is @code{nil}.
@item gnus-article-mime-part-function
@vindex gnus-article-mime-part-function
@end lisp
@noindent
-to your @file{.gnus.el} file.
+to your @file{~/.gnus.el} file.
@end table
If you're using horizontal trees, it might be nice to display the trees
side-by-side with the summary buffer. You could add something like the
-following to your @file{.gnus.el} file:
+following to your @file{~/.gnus.el} file:
@lisp
(setq gnus-use-trees t
@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
-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:
+@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:
@lisp
(setq gnus-newsgroup-variables
@end table
+@cindex snarfing keys
+@cindex importing PGP keys
+@cindex PGP key ring import
+Snarfing OpenPGP keys (i.e., importing keys from articles into your
+key ring) is not supported explicitly through a menu item or command,
+rather Gnus do detect and label keys as @samp{application/pgp-keys},
+allowing you to specify whatever action you think is appropriate
+through the usual MIME infrastructure. You can use a
+@file{~/.mailcap} entry (@pxref{mailcap, , mailcap, emacs-mime, The
+Emacs MIME Manual}) such as the following to import keys using GNU
+Privacy Guard when you click on the MIME button (@pxref{Using MIME}).
+
+@example
+application/pgp-keys; gpg --import --interactive --verbose; needsterminal
+@end example
+
+This happens to also be the default action defined in
+@var{mailcap-mime-data}.
+
@node Mailing List
@section Mailing List
@end table
+
@node Article Buffer
@chapter Article Buffer
@cindex article buffer
@code{Newsgroups} header.
@item reply-to
Remove the @code{Reply-To} header if it lists the same address as the
-@code{From} header.
+@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.
Prompt for a file name, then save the @sc{mime} object and strip it from
the article. Then proceed to article editing, where a reasonable
suggestion is being made on how the altered article should look
-like. The stripped @sc{mime} object will be referred via the
+like. The stripped @sc{mime} object will be referred via the
message/external-body @sc{mime} type.
(@code{gnus-mime-save-part-and-strip}).
+@findex gnus-mime-delete-part
+@item d (Article)
+@kindex d (Article)
+Delete the @sc{mime} object from the article and replace it with some
+information about the removed @sc{mime} object
+(@code{gnus-mime-delete-part}).
+
@findex gnus-mime-copy-part
@item c (Article)
@kindex c (Article)
Syntax table used in article buffers. It is initialized from
@code{text-mode-syntax-table}.
+@vindex gnus-article-over-scroll
+@item gnus-article-over-scroll
+If non-@code{nil}, allow scrolling the article buffer even when there
+no more new text to scroll in. The default is @code{nil}.
+
@vindex gnus-article-mode-line-format
@item gnus-article-mode-line-format
This variable is a format string along the same lines as
@vindex gnus-page-delimiter
This is the delimiter mentioned above. By default, it is @samp{^L}
(formfeed).
+
+@cindex IDNA
+@cindex internationalized domain names
+@vindex gnus-use-idna
+@item gnus-use-idna
+This variable controls whether Gnus performs IDNA decoding of
+internationalized domain names inside @sc{From:}, @sc{To:} and
+@sc{Cc:} headers. This requires GNU Libidn
+(@url{http://www.gnu.org/software/libidn/}, and this variable is only
+enabled if you have installed it.
+
@end table
If the group doesn't exist, it will be created and you'll be subscribed
to it. The only way to make it disappear from the Group buffer is to
-unsubscribe it.
+unsubscribe it. The special properties of the draft group comes from
+a group property (@pxref{Group Parameters}), and if lost the group
+behaves like any other group. This means the commands below will not
+be available. To restore the special properties of the group, the
+simplest way is to kill the group, using @kbd{C-k}, and restart
+Gnus. The group is automatically created again with the
+correct parameters. The content of the group is not lost.
@c @findex gnus-dissociate-buffer-from-draft
@c @kindex C-c M-d (Mail)
@node Server Variables
@subsection Server Variables
+@cindex server variables
+@cindex server parameters
One sticky point when defining variables (both on back ends and in Emacs
in general) is that some variables are typically initialized from other
(nnml-newsgroups-file "~/my-mail/newsgroups"))
@end lisp
+Server variables are often called @dfn{server parameters}.
@node Servers and Methods
@subsection Servers and Methods
This is the default, and simply connects to some port or other on the
remote system.
+@findex nntp-open-tls-stream
+@item nntp-open-tls-stream
+Opens a connection to a server over a @dfn{secure} channel. To use
+this you must have GNUTLS installed (see
+@uref{http://www.gnu.org/software/gnutls/}). You then define a server
+as follows:
+
+@lisp
+;; "nntps" is port 563 and is predefined in our /etc/services
+;; however, gnutls-cli -p doesn't like named ports.
+;;
+(nntp "snews.bar.com"
+ (nntp-open-connection-function nntp-open-tls-stream)
+ (nntp-port-number )
+ (nntp-address "snews.bar.com"))
+@end lisp
+
@findex nntp-open-ssl-stream
@item nntp-open-ssl-stream
Opens a connection to a server over a @dfn{secure} channel. To use this
define a server as follows:
@lisp
-;; Type `C-c C-c' after you've finished editing.
-;;
;; "snews" is port 563 and is predefined in our /etc/services
-;; however, openssl s_client -port doesn't like named ports
+;; however, openssl s_client -port doesn't like named ports.
;;
(nntp "snews.bar.com"
(nntp-open-connection-function nntp-open-ssl-stream)
@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use
@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to
@samp{("-C")} in order to compress all data connections, otherwise set
-this to @samp{("-t")} or @samp{("-C" "-t")} if the telnet command
-requires a pseudo-tty allocation on an intermediate host.
+this to @samp{("-t" "-e" "none")} or @samp{("-C" "-t" "-e" "none")} if
+the telnet command requires a pseudo-tty allocation on an intermediate
+host.
@end table
@item nntp-open-via-telnet-and-telnet
@item nntp-pre-command
@vindex nntp-pre-command
-A command wrapper to use when connecting through a non native connection
-function (all except @code{nntp-open-network-stream} and
-@code{nntp-open-ssl-stream}. This is where you would put a @samp{SOCKS}
-wrapper for instance.
+A command wrapper to use when connecting through a non native
+connection function (all except @code{nntp-open-network-stream},
+@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}. This is
+where you would put a @samp{SOCKS} wrapper for instance.
@item nntp-address
@vindex nntp-address
@item nntp-port-number
@vindex nntp-port-number
-Port number to connect to the @sc{nntp} server. The default is @samp{nntp}.
-If you use @sc{nntp} over @sc{ssl}, you may want to use integer ports rather
-than named ports (i.e, use @samp{563} instead of @samp{snews}), because
-external SSL tools may not work with named ports.
+Port number to connect to the @sc{nntp} server. The default is
+@samp{nntp}. If you use @sc{nntp} over @sc{tls}/@sc{ssl}, you may
+want to use integer ports rather than named ports (i.e, use @samp{563}
+instead of @samp{snews} or @samp{nntps}), because external TLS/SSL
+tools may not work with named ports.
@item nntp-end-of-line
@vindex nntp-end-of-line
@vindex nnspool-sift-nov-with-sed
@cindex sed
If non-@code{nil}, which is the default, use @code{sed} to get the
-relevant portion from the overview file. If nil, @code{nnspool} will
-load the entire file into a buffer and process it there.
+relevant portion from the overview file. If @code{nil},
+@code{nnspool} will load the entire file into a buffer and process it
+there.
@end table
and things will happen automatically.
For instance, if you want to use @code{nnml} (which is a ``one file per
-mail'' back end), you could put the following in your @file{.gnus.el} file:
+mail'' back end), you could put the following in your @file{~/.gnus.el} file:
@lisp
(setq gnus-secondary-select-methods '((nnml "")))
@vindex nnmail-mail-splitting-charset
@vindex nnmail-mail-splitting-decodes
-By default the splitting codes @sc{mime} decodes headers so you can match
-on non-ASCII strings. The @code{nnmail-mail-splitting-charset}
+By default the splitting codes @sc{mime} decodes headers so you can
+match on non-ASCII strings. The @code{nnmail-mail-splitting-charset}
variable specifies the default charset for decoding. The behaviour
can be turned off completely by binding
-@code{nnmail-mail-splitting-decodes} to nil, which is useful if you
-want to match articles based on the raw header data.
+@code{nnmail-mail-splitting-decodes} to @code{nil}, which is useful if
+you want to match articles based on the raw header data.
@vindex nnmail-resplit-incoming
-By default, splitting is performed on all incoming messages. If
-you specify a @code{directory} entry for the variable
-@code{mail-sources} @pxref{Mail Source Specifiers}, however, then
-splitting does @emph{not} happen by default. You can set the variable
-@code{nnmail-resplit-incoming} to a non-nil value to make splitting
-happen even in this case. (This variable has no effect on other kinds
-of entries.)
+By default, splitting is performed on all incoming messages. If you
+specify a @code{directory} entry for the variable @code{mail-sources}
+@pxref{Mail Source Specifiers}, however, then splitting does
+@emph{not} happen by default. You can set the variable
+@code{nnmail-resplit-incoming} to a non-@code{nil} value to make
+splitting happen even in this case. (This variable has no effect on
+other kinds of entries.)
Gnus gives you all the opportunity you could possibly want for shooting
yourself in the foot. Let's say you create a group that will contain
@item directory
@vindex nnmail-scan-directory-mail-source-once
-Get mail from several files in a directory. This is typically used when
-you have procmail split the incoming mail into several files. That is,
-there is a one-to-one correspondence between files in that directory and
-groups, so that mail from the file @file{foo.bar.spool} will be put in
-the group @code{foo.bar}. (You can change the suffix to be used instead
-of @code{.spool}.) Setting
-@code{nnmail-scan-directory-mail-source-once} to non-nil forces Gnus to
-scan the mail source only once. This is particularly useful if you want
-to scan mail groups at a specified level.
+Get mail from several files in a directory. This is typically used
+when you have procmail split the incoming mail into several files.
+That is, there is a one-to-one correspondence between files in that
+directory and groups, so that mail from the file @file{foo.bar.spool}
+will be put in the group @code{foo.bar}. (You can change the suffix
+to be used instead of @code{.spool}.) Setting
+@code{nnmail-scan-directory-mail-source-once} to non-@code{nil} forces
+Gnus to scan the mail source only once. This is particularly useful
+if you want to scan mail groups at a specified level.
@vindex nnmail-resplit-incoming
There is also the variable @code{nnmail-resplit-incoming}, if you set
-that to a non-nil value, then the normal splitting process is applied
-to all the files from the directory, @ref{Splitting Mail}.
+that to a non-@code{nil} value, then the normal splitting process is
+applied to all the files from the directory, @ref{Splitting Mail}.
Keywords:
and fetches articles from a given @sc{imap} mailbox. @xref{IMAP}, for
more information.
-Note that for the Kerberos, GSSAPI, SSL/TLS and STARTTLS support you
+Note that for the Kerberos, GSSAPI, TLS/SSL and STARTTLS support you
may need external programs and libraries, @xref{IMAP}.
Keywords:
@item :port
The port number of the @sc{imap} server. The default is @samp{143}, or
-@samp{993} for SSL/TLS connections.
+@samp{993} for TLS/SSL connections.
@item :user
The user name to give to the @sc{imap} server. The default is the login
@item :stream
What stream to use for connecting to the server, this is one of the
symbols in @code{imap-stream-alist}. Right now, this means
-@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{ssl},
-@samp{shell} or the default @samp{network}.
+@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls},
+@samp{ssl}, @samp{shell} or the default @samp{network}.
@item :authentication
Which authenticator to use for authenticating to the server, this is
but more flags are defined in RFC 2060 section 2.3.2.
@item :dontexpunge
-If non-nil, don't remove all articles marked as deleted in the mailbox
-after finishing the fetch.
+If non-@code{nil}, don't remove all articles marked as deleted in the
+mailbox after finishing the fetch.
@end table
prompted.
@item :dontexpunge
-If non-nil, only fetch unread articles and don't move them to trash
-folder after finishing the fetch.
+If non-@code{nil}, only fetch unread articles and don't move them to
+trash folder after finishing the fetch.
@end table
@table @code
@item :plugged
-If non-nil, fetch the mail even when Gnus is unplugged. If you use
-directory source to get mail, you can specify it as in this example:
+If non-@code{nil}, fetch the mail even when Gnus is unplugged. If you
+use directory source to get mail, you can specify it as in this
+example:
@lisp
(setq mail-sources
@item mail-source-delete-old-incoming-confirm
@vindex mail-source-delete-old-incoming-confirm
-If @code{non-nil}, ask for for confirmation before deleting old incoming
+If non-@code{nil}, ask for for confirmation before deleting old incoming
files. This variable only applies when
@code{mail-source-delete-incoming} is a positive number.
@item mail-source-movemail-program
@vindex mail-source-movemail-program
-If non-nil, name of program for fetching new mail. If nil,
-@code{movemail} in @var{exec-directory}.
+If non-@code{nil}, name of program for fetching new mail. If
+@code{nil}, @code{movemail} in @var{exec-directory}.
@end table
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} and
-@code{nnmail-cache-accepted-message-ids} to a non-nil value. And then
-you can include @code{nnmail-split-fancy-with-parent} using the colon
-feature, like so:
+To use this feature, you have to set @code{nnmail-treat-duplicates}
+and @code{nnmail-cache-accepted-message-ids} to a non-@code{nil}
+value. And then you can include @code{nnmail-split-fancy-with-parent}
+using the colon feature, like so:
@lisp
(setq nnmail-treat-duplicates 'warn ; or 'delete
nnmail-cache-accepted-message-ids t
@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
-unless the group name matches the regexp
-@code{nnmail-split-fancy-with-parent-ignore-groups}. 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.)
+non-@code{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 unless the group name matches the regexp
+@code{nnmail-split-fancy-with-parent-ignore-groups}. 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.)
@vindex nnmail-cache-accepted-message-ids
When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus
also records the message ids of moved articles, so that the followup
@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.el}:
+you. For example, add to your @file{~/.gnus.el}:
@lisp
(gnus-group-split-setup AUTO-UPDATE CATCH-ALL)
articles you read as expirable, no matter if they were read or unread
before. To avoid having articles marked as read marked as expirable
automatically, you can put something like the following in your
-@file{.gnus.el} file:
+@file{~/.gnus.el} file:
@vindex gnus-mark-article-hook
@lisp
@vindex nnmh-get-new-mail
@vindex nnfolder-get-new-mail
This might be too much, if, for instance, you are reading mail quite
-happily with @code{nnml} and just want to peek at some old @sc{rmail}
+happily with @code{nnml} and just want to peek at some old Rmail
file you have stashed away with @code{nnbabyl}. All back ends have
variables called back-end-@code{get-new-mail}. If you want to disable
the @code{nnbabyl} mail reading, you edit the virtual server for the
@menu
* Unix Mail Box:: Using the (quite) standard Un*x mbox.
-* Rmail Babyl:: Emacs programs use the rmail babyl format.
+* Rmail Babyl:: Emacs programs use the Rmail Babyl format.
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
* Maildir:: Another one-file-per-message format.
@node Rmail Babyl
@subsubsection Rmail Babyl
@cindex nnbabyl
-@cindex rmail mbox
+@cindex Rmail mbox
@vindex nnbabyl-active-file
@vindex nnbabyl-mbox-file
-The @dfn{nnbabyl} back end will use a babyl mail box (aka. @dfn{rmail
+The @dfn{nnbabyl} back end will use a Babyl mail box (aka. @dfn{Rmail
mbox}) to store mail. @code{nnbabyl} will add extra headers to each
mail article to say which group it belongs in.
@table @code
@item nnbabyl-mbox-file
@vindex nnbabyl-mbox-file
-The name of the rmail mbox file. The default is @file{~/RMAIL}
+The name of the Rmail mbox file. The default is @file{~/RMAIL}
@item nnbabyl-active-file
@vindex nnbabyl-active-file
@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
-symlinks to maildirs (and nothing else; do not choose a directory
-already used for other purposes). You could also put maildirs
-themselves (instead of symlinks to them) directly in the server
-directory, but that would break @code{nnmaildir-request-delete-group},
-so you wouldn't be able to delete those groups from within Gnus. (You
-could still delete them from your shell with @code{rm -r foo}.) 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 `.' 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.
+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 `.' 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.
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
only when the server is opened; the resulting string is used until the
server is closed. (If you don't know about forms and @code{eval},
don't worry - a simple string will work.) This parameter is not
-optional; you must specify it. I don't recommend using @file{~/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. @file{~/.nnmaildir} is a typical value.
+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.
-@item create-directory
+@item target-prefix
This should be a Lisp form which is processed by @code{eval} and
-@code{expand-file-name} to get the name of the directory where new
-maildirs are created. The form is @code{eval}ed only when the server
-is opened; the resulting string is used until the server is closed.
-This parameter is optional, but if you do not supply it, you cannot
-create new groups from within Gnus. (You could still create them from
-your shell with @code{mkdir -m 0700 foo foo/tmp foo/new foo/cur}.) A
-relative path is interpreted as relative to the @code{directory} path.
-@code{create-directory} and @code{directory} must be different;
-otherwise, group creation and deletion will break. (If you don't need
-those features, you can omit @code{create-directory} entirely.)
+@code{expand-file-name}. The form is @code{eval}ed only when the
+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
+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
+@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create
+@file{~/.nnmaildir/foo} as a symlink pointing to
+@file{../maildirs/foo}.
+
+You can set @code{target-prefix} to a string without any slashes to
+create both maildirs and symlinks in the same @code{directory}; in
+this case, any maildirs found in @code{directory} whose names start
+with @code{target-prefix} will not be listed as groups (but the
+symlinks pointing to them will be).
+
+As a special case, if @code{target-prefix} is @code{""} (the default),
+then when you create a group, the maildir will be created in
+@code{directory} without a corresponding symlink. Beware that you
+cannot use @code{gnus-group-delete-group} on such groups without the
+@code{force} argument.
@item directory-files
This should be a function with the same interface as
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 destination
-group.
+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
+@code{nnmail-expiry-target} variable.}
@item read-only
If this is set to @code{t}, nnmaildir will treat the articles in this
group to find articles. The default is the function specified by the
server's @code{directory-files} parameter.
+@item distrust-Lines:
+If non-@code{nil}, 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
@item nnfolder-nov-directory
@vindex nnfolder-nov-directory
-The directory where the @sc{nov} files should be stored. If nil,
-@code{nnfolder-directory} is used.
+The directory where the @sc{nov} files should be stored. If
+@code{nil}, @code{nnfolder-directory} is used.
@item nnfolder-marks-is-evil
@vindex nnfolder-marks-is-evil
@item nnfolder-marks-directory
@vindex nnfolder-marks-directory
-The directory where the @sc{marks} files should be stored. If nil,
-@code{nnfolder-directory} is used.
+The directory where the @sc{marks} files should be stored. If
+@code{nil}, @code{nnfolder-directory} is used.
@end table
format to which mail was converted, primarily involving creating a
spool-file-like entity with a scheme for inserting Babyl-specific
headers and status bits above the top of each message in the file.
-RMAIL was Emacs' first mail reader, it was written by Richard Stallman,
-and Stallman came out of that TOPS/Babyl environment, so he wrote RMAIL
+Rmail was Emacs' first mail reader, it was written by Richard Stallman,
+and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail
to understand the mail files folks already had in existence. Gnus (and
VM, for that matter) continue to support this format because it's
perceived as having some good qualities in those mailer-specific
-headers/status bits stuff. RMAIL itself still exists as well, of
+headers/status bits stuff. Rmail itself still exists as well, of
course, and is still maintained by Stallman.
Both of the above forms leave your mail in a single file on your
@item nnmaildir
+For configuring expiry and other things, @code{nnmaildir} uses
+incompatible group parameters, slightly different from those of other
+mail back ends.
+
@code{nnmaildir} is largely similar to @code{nnml}, with some notable
differences. Each message is stored in a separate file, but the
filename is unrelated to the article number in Gnus. @code{nnmaildir}
thus damaging message bodies), and another set to be used as groups (in
whatever format you like). A maildir has a built-in spool, in the
@code{new/} subdirectory. Beware that currently, mail moved from
-@code{new/} to @code{cur/} instead of via mail splitting will undergo
-treatment such as duplicate checking.
-
-An article will not necessarily keep the same number across Gnus
-sessions; articles are renumbered starting from 1 for each Gnus session
-(more precisely, each time you open the @code{nnmaildir} server). This
-way, you don't get gaps in your article number ranges, and when entering
-large groups, Gnus is likely to give a more accurate article count. The
-price is that @code{nnmaildir} doesn't work with the cache or agent.
-This will probably be changed in the future.
+@code{new/} to @code{cur/} instead of via mail splitting will not
+undergo treatment such as duplicate checking.
@code{nnmaildir} stores article marks for a given group in the
corresponding maildir, in a way designed so that it's easy to manipulate
it's not as easy to work with them from outside Gnus as with
@code{nnmaildir}.
-For configuring expiry and other things, @code{nnmaildir} uses group
-parameters slightly different from those of other mail back ends.
-
@code{nnmaildir} uses a significant amount of memory to speed things up.
(It keeps in memory some of the things that @code{nnml} stores in files
and that @code{nnmh} repeatedly parses out of message files.) If this
is a problem for you, you can set the @code{nov-cache-size} group
parameter to something small (0 would probably not work, but 1 probably
-would) to make it use less memory.
+would) to make it use less memory. This caching will probably be
+removed in the future.
-Startup and shutdown are likely to be slower with @code{nnmaildir} than
-with other back ends. Everything in between is likely to be faster,
-depending in part on your file system.
+Startup is likely to be slower with @code{nnmaildir} than with other
+back ends. Everything else is likely to be faster, depending in part
+on your file system.
@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo}
to write an @code{nnmaildir}-derived back end.
let you read this forum in a convenient manner.
The easiest way to read this source is to put something like the
-following in your @file{.gnus.el} file:
+following in your @file{~/.gnus.el} file:
@lisp
(setq gnus-secondary-select-methods
manipulate mails stored on the @sc{imap} server. This is the kind of
usage explained in this section.
-A server configuration in @file{~/.gnus} with a few @sc{imap} servers
-might look something like the following. (Note that for SSL/TLS, you
+A server configuration in @file{~/.gnus.el} with a few @sc{imap} servers
+might look something like the following. (Note that for TLS/SSL, you
need external programs and libraries, see below.)
@lisp
@item nnimap-server-port
@vindex nnimap-server-port
-Port on server to contact. Defaults to port 143, or 993 for SSL.
+Port on server to contact. Defaults to port 143, or 993 for TLS/SSL.
Note that this should be an integer, example server specification:
@vindex nnimap-stream
The type of stream used to connect to your server. By default, nnimap
will detect and automatically use all of the below, with the exception
-of SSL/TLS. (@sc{imap} over SSL/TLS is being replaced by STARTTLS, which
+of TLS/SSL. (@sc{imap} over TLS/SSL is being replaced by STARTTLS, which
can be automatically detected, but it's not widely deployed yet.)
Example server specification:
@itemize @bullet
@item
@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the
-@samp{imtest} program.
+@samp{gsasl} or @samp{imtest} program.
@item
@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program.
@item
@dfn{starttls:} Connect via the STARTTLS extension (similar to
-SSL). Requires the external library @samp{starttls.el} and program
+TLS/SSL). Requires the external library @samp{starttls.el} and program
@samp{starttls}.
@item
+@dfn{tls:} Connect through TLS. Requires GNUTLS (the program
+@samp{gnutls-cli}).
+@item
@dfn{ssl:} Connect through SSL. Requires OpenSSL (the program
@samp{openssl}) or SSLeay (@samp{s_client}).
@item
@code{imap-kerberos4-program} contain parameters to pass to the imtest
program.
+For TLS connection, the @code{gnutls-cli} program from GNUTLS is
+needed. It is available from
+@uref{http://www.gnu.org/software/gnutls/}.
+
+@vindex imap-gssapi-program
+This parameter specifies a list of command lines that invoke a GSSAPI
+authenticated IMAP stream in a subshell. They are tried sequentially
+until a connection is made, or the list has been exhausted. By
+default, @samp{gsasl} from GNU SASL, available from
+@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest}
+program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are
+tried.
+
@vindex imap-ssl-program
For SSL connections, the OpenSSL program is available from
@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay,
@itemize @bullet
@item
@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires
-external program @code{imtest}.
+external program @code{gsasl} or @code{imtest}.
@item
@dfn{kerberos4:} Kerberos 4 authentication. Requires external program
@code{imtest}.
@item nnimap-importantize-dormant
@vindex nnimap-importantize-dormant
-If non-nil (the default), marks dormant articles as ticked (as well),
-for other @sc{imap} clients. Within Gnus, dormant articles will
+If non-@code{nil} (the default), marks dormant articles as ticked (as
+well), for other @sc{imap} clients. Within Gnus, dormant articles will
naturally still (only) be marked as dormant. This is to make dormant
articles stand out, just like ticked articles, in other @sc{imap}
clients. (In other words, Gnus has two ``Tick'' marks and @sc{imap}
@cindex crosspost
@vindex nnimap-split-crosspost
-If non-nil, do crossposting if several split methods match the mail. If
-nil, the first match in @code{nnimap-split-rule} found will be used.
+If non-@code{nil}, do crossposting if several split methods match the
+mail. If @code{nil}, the first match in @code{nnimap-split-rule}
+found will be used.
Nnmail equivalent: @code{nnmail-crosspost}.
@vindex nnimap-split-inbox
A string or a list of strings that gives the name(s) of @sc{imap}
-mailboxes to split from. Defaults to nil, which means that splitting is
-disabled!
+mailboxes to split from. Defaults to @code{nil}, which means that
+splitting is disabled!
@lisp
(setq nnimap-split-inbox
The second element can also be a function. In that case, it will be
called with the first element of the rule as the argument, in a buffer
-containing the headers of the article. It should return a non-nil value
-if it thinks that the mail belongs in that group.
+containing the headers of the article. It should return a
+non-@code{nil} value if it thinks that the mail belongs in that group.
Nnmail users might recollect that the last regexp had to be empty to
match all articles (like in the example above). This is not required in
@findex nnimap-split-download-body
@vindex nnimap-split-download-body
-Set to non-nil to download entire articles during splitting. This is
-generally not required, and will slow things down considerably. You
-may need it if you want to use an advanced splitting function that
-analyses the body to split the article.
+Set to non-@code{nil} to download entire articles during splitting.
+This is generally not required, and will slow things down
+considerably. You may need it if you want to use an advanced
+splitting function that analyses the body to split the article.
@end table
as a newsgroup. Several files types are supported:
@table @code
-@cindex babyl
-@cindex rmail mbox
+@cindex Babyl
+@cindex Rmail mbox
@item babyl
-The babyl (rmail) mail box.
+The Babyl (Rmail) mail box.
@cindex mbox
@cindex Unix mbox
* 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.
+* Example Setup:: An example @file{~/.gnus.el} file for offline people.
* Batching Agents:: How to fetch news from a @code{cron} job.
* Agent Caveats:: What you think it'll do and what it does.
@end menu
@code{gnus-secondary-select-methods} are agentized.
@item
-Decide on download policy. @xref{Agent Categories}.
+
+Decide on download policy. It's fairly simple once you decide whether
+you are going to use agent categories, topic parameters, and/or group
+parameters to implement your policy. If you're new to gnus, it
+is probably best to start with a category @xref{Agent Categories}.
+
+Both topic parameters (@pxref{Topic Parameters}) and agent categories
+(@pxref{Agent Categories}) provide for setting a policy that applies
+to multiple groups. Which you use is entirely up to you. Topic
+parameters do override categories so, if you mix the two, you'll have
+to take that into account. If you have a few groups that deviate from
+your policy, you can use grou parameters (@pxref{Group Parameters}) to
+configure them.
@item
Uhm@dots{} that's it.
mark the articles for downloading manually if it should turn out that
you're interested in the articles anyway.
-The main way to control what is to be downloaded is to create a
-@dfn{category} and then assign some (or all) groups to this category.
-Groups that do not belong in any other category belong to the
-@code{default} category. Gnus has its own buffer for creating and
-managing categories.
+One of the more effective methods for controlling what is to be
+downloaded is to create a @dfn{category} and then assign some (or all)
+groups to this category. Groups that do not belong in any other
+category belong to the @code{default} category. Gnus has its own
+buffer for creating and managing categories.
+
+If you prefer, you can also use group parameters (@pxref{Group
+Parameters}) and topic parameters (@pxref{Topic Parameters}) for an
+alternative approach to controlling the agent. The only real
+difference is that categories are specific to the agent (so there is
+less to learn) while group and topic parameters include the kitchen
+sink.
+
+Since you can set agent parameters in several different places we have
+a rule to decide which source to believe. This rule specifies that
+the parameter sources are checked in the following order: group
+parameters, topic parameters, agent category, and finally customizable
+variables. So you can mix all of these sources to produce a wide range
+of behavior, just don't blame me if you don't remember where you put
+your settings.
@menu
* Category Syntax:: What a category looks like.
@node Category Syntax
@subsubsection Category Syntax
-A category consists of two things.
+A category consists of a name, the list of groups belonging to the
+category, and a number of optional parameters that override the
+customizable variables. The complete list of agent parameters are
+listed below.
-@enumerate
-@item
+@table @code
+@item gnus-agent-cat-name
+The name of the category.
+
+@item gnus-agent-cat-groups
+The list of groups that are in this category.
+
+@item gnus-agent-cat-predicate
A predicate which (generally) gives a rough outline of which articles
are eligible for downloading; and
-@item
+@item gnus-agent-cat-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.)
-@end enumerate
+
+@item gnus-agent-cat-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
+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
+an integer that overrides the value of @code{gnus-agent-low-score}.
+
+@item gnus-agent-cat-high-score
+an integer that overrides the value of @code{gnus-agent-high-score}.
+
+@item gnus-agent-cat-length-when-short
+an integer that overrides the value of
+@code{gnus-agent-short-article}.
+
+@item gnus-agent-cat-length-when-long
+an integer that overrides the value of @code{gnus-agent-long-article}.
+@end table
+
+The name of a category can not be changed once the category has been
+created.
+
+Each category maintains a list of groups that are exclusive members of
+that category. The exclusivity rule is automatically enforced, add a
+group to a new category and it is automatically removed from its old
+category.
A predicate in its simplest form can be a single predicate such as
@code{true} or @code{false}. These two will download every available
The following predicates are pre-defined, but if none of these fit what
you want to do, you can write your own.
+When evaluating each of these predicates, the named constant will be
+bound to the value determined by calling
+@code{gnus-agent-find-parameter} on the appropriate parameter. For
+example, gnus-agent-short-article will be bound to
+@code{(gnus-agent-find-parameter group 'agent-short-article)}. This
+means that you can specify a predicate in your category then tune that
+predicate to individual groups.
+
@table @code
@item short
True iff the article is shorter than @code{gnus-agent-short-article}
(agent-predicate . short)
@end lisp
-This is the group parameter equivalent of the agent category default.
+This is the group/topic parameter equivalent of the agent category default.
Note that when specifying a single word predicate like this, the
@code{agent-predicate} specification must be in dotted pair notation.
@end lisp
@item
-Group Parameter specification
+Group/Topic Parameter specification
@lisp
(agent-score ("from"
@findex gnus-category-exit
Return to the group buffer (@code{gnus-category-exit}).
+@item e
+@kindex e (Category)
+@findex gnus-category-customize-category
+Use a customization buffer to set all of the selected category's
+parameters at one time (@code{gnus-category-customize-category}).
+
@item k
@kindex k (Category)
@findex gnus-category-kill
Articles that have a score higher than this have a high score. Default
0.
+@item gnus-agent-expire-days
+@vindex gnus-agent-expire-days
+The number of days that a @samp{read} article must stay in the agent's
+local disk before becoming eligible for expiration (While the name is
+the same, this doesn't mean expiring the article on the server. It
+just means deleting the local copy of the article). What is also
+important to understand is that the counter starts with the time the
+article was written to the local disk and not the time the article was
+read.
+Default 7.
+
+@item gnus-agent-enable-expiration
+@vindex gnus-agent-enable-expiration
+Determines whether articles in a group are, by default, expired or
+retained indefinitely. The default is @code{ENABLE} which means that
+you'll have to disable expiration when desired. On the other hand,
+you could set this to @code{DISABLE}. In that case, you would then
+have to enable expiration in selected groups.
+
@end table
article into the Agent, Gnus will not download the article from the
server again but use the locally stored copy instead.
-This behaviour can be controlled by @code{gnus-agent-cache}
-(@pxref{Agent Variables}).
+If you so desire, you can configure the agent (see @code{gnus-agent-cache}
+@pxref{Agent Variables}) to always download headers and articles while
+plugged. Gnus will almost certainly be slower, but it will be kept
+synchronized with the server. That last point probably won't make any
+sense if you are using a nntp or nnimap backend.
@node Agent Expiry
@subsection Agent Expiry
@vindex gnus-agent-expire-days
@findex gnus-agent-expire
@kindex M-x gnus-agent-expire
+@kindex M-x gnus-agent-expire-group
+@findex gnus-agent-expire-group
@cindex Agent expiry
@cindex Gnus Agent expiry
@cindex expiry
-@code{nnagent} doesn't handle expiry. Instead, there's a special
-@code{gnus-agent-expire} command that will expire all read articles that
-are older than @code{gnus-agent-expire-days} days. It can be run
-whenever you feel that you're running out of space. It's not
-particularly fast or efficient, and it's not a particularly good idea to
-interrupt it (with @kbd{C-g} or anything else) once you've started it.
+The Agent backend, @code{nnagent}, doesn't handle expiry. Well, at
+least it doesn't handle it like other backends. Instead, there are
+special @code{gnus-agent-expire} and @code{gnus-agent-expire-group}
+commands that will expire all read articles that are older than
+@code{gnus-agent-expire-days} days. They can be run whenever you feel
+that you're running out of space. Neither are particularly fast or
+efficient, and it's not a particularly good idea to interrupt them (with
+@kbd{C-g} or anything else) once you've started one of them.
Note that other functions, e.g. @code{gnus-request-expire-articles},
might run @code{gnus-agent-expire} for you to keep the agent
synchronized with the group.
-@code{gnus-agent-expire-days} can also be a list of regexp/day pairs.
-The regexps will be matched against group names to allow differing
-expiry in different groups.
-
-@lisp
-(setq gnus-agent-expire-days
- '(("alt\\." 7)
- (".*binary" 1)
- ("." 21)))
-@end lisp
-
-If you use the list form, the last element must always be the default
-method---it must always match all groups. Also, for a regexp to match,
-it must match from the beginning of the group's name.
+The agent parameter @code{agent-enable-expiration} may be used to
+prevent expiration in selected groups.
@vindex gnus-agent-expire-all
-If @code{gnus-agent-expire-all} is non-@code{nil}, this command will
-expire all articles---unread, read, ticked and dormant. If @code{nil}
-(which is the default), only read articles are eligible for expiry, and
-unread, ticked and dormant articles will be kept indefinitely.
+If @code{gnus-agent-expire-all} is non-@code{nil}, the agent
+expiration commands will expire all articles---unread, read, ticked
+and dormant. If @code{nil} (which is the default), only read articles
+are eligible for expiry, and unread, ticked and dormant articles will
+be kept indefinitely.
If you find that some articles eligible for expiry are never expired,
-perhaps some Gnus Agent files are corrupted. There's a special
-@code{gnus-agent-regenerate} command to fix possible problems.
+perhaps some Gnus Agent files are corrupted. There's are special
+commands, @code{gnus-agent-regenerate} and
+@code{gnus-agent-regenerate-group}, to fix possible problems.
@node Agent Regeneration
@subsection Agent Regeneration
For example, if your connection to your server is lost while
downloaded articles into the agent, the local data structures will not
-know about articles downloaded prior to the connection failure.
-Running @code{gnus-agent-regenerate} or
+know about articles successfully downloaded prior to the connection
+failure. Running @code{gnus-agent-regenerate} or
@code{gnus-agent-regenerate-group} will update the data structures
such that you don't need to download these articles a second time.
@item gnus-agent-fetched-hook
@vindex gnus-agent-fetched-hook
-Hook run when after finishing fetching articles.
+Hook run when finished fetching articles.
@item gnus-agent-cache
@vindex gnus-agent-cache
Variable to control whether use the locally stored @sc{nov} and
articles when plugged, e.g. essentially using the Agent as a cache.
-The default is non-nil, which means to use the Agent as a cache.
+The default is non-@code{nil}, which means to use the Agent as a cache.
@item gnus-agent-go-online
@vindex gnus-agent-go-online
@item gnus-agent-mark-unread-after-downloaded
@vindex gnus-agent-mark-unread-after-downloaded
If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil},
-mark articles as unread after downloading. The default is t.
+mark articles as unread after downloading. This is usually a safe
+thing to do as the newly downloaded article has obviously not been
+read. The default is t.
@item gnus-agent-consider-all-articles
@vindex gnus-agent-consider-all-articles
connection be lost while fetching (You may need to run
@code{gnus-agent-regenerate-group} to update the group's state.
However, all articles parsed prior to loosing the connection will be
-available while unplugged).
+available while unplugged). The default is 10M so it is unusual to
+see any cycling.
@item gnus-server-unopen-status
@vindex gnus-server-unopen-status
for this variable include @code{denied} and @code{offline} the latter
is only valid if the Agent is used.
+@item gnus-auto-goto-ignores
+@vindex gnus-auto-goto-ignores
+Another variable that isn't a Agent variable, yet so closely related
+that most will look for it here, this variable tells the summary
+buffer how to maneuver around undownloaded (only headers stored in the
+agent) and unfetched (neither article nor headers stored) articles.
+
+The legal values are @code{nil} (maneuver to any article),
+@code{undownloaded} (maneuvering while unplugged ignores articles that
+have not been fetched), @code{always-undownloaded} (maneuvering always
+ignores articles that have not been fetched), @code{unfetched}
+(maneuvering ignores articles whose headers have not been fetched).
+
@end table
If you don't want to read this manual, and you have a fairly standard
setup, you may be able to use something like the following as your
-@file{.gnus.el} file to get started.
+@file{~/.gnus.el} file to get started.
@lisp
;;; Define how Gnus is to fetch news. We do this over @sc{nntp}
@code{gnus-agent-fetch-selected-article} to
@code{gnus-select-article-hook}.
-@item If I read an article while plugged, and the article already exists in the Agent, will it get downloaded once more?
+@item If I read an article while plugged, and the article already exists in
+the Agent, will it get downloaded once more?
@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
@kindex V t (Summary)
@findex gnus-score-find-trace
Display all score rules that have been used on the current article
-(@code{gnus-score-find-trace}).
+(@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.
@item V w
@kindex V w (Summary)
will be applied to each article.
To take @code{gnus-del-mark} as an example---this alist says that all
-articles that have that mark (i.e., are marked with @samp{D}) will have a
+articles that have that mark (i.e., are marked with @samp{e}) will have a
score entry added to lower based on the @code{From} header by -4, and
lowered by @code{Subject} by -1. Change this to fit your prejudices.
group name, the @var{file-name} will be used as the home score file.
@item
-A function. If the function returns non-nil, the result will be used as
-the home score file.
+A function. If the function returns non-@code{nil}, the result will
+be used as the home score file.
@item
A string. Use the string as the home score file.
this mechanism does, but here's a cookbook example for @code{nnml} on
how to allow scoring on the @samp{To} and @samp{Cc} headers.
-Put the following in your @file{.gnus.el} file.
+Put the following in your @file{~/.gnus.el} file.
@lisp
(setq gnus-extra-headers '(To Cc Newsgroups Keywords)
@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}.
Text inside the @samp{%<<} and @samp{%>>} specifiers will get the
-special @code{balloon-help} property set to @code{gnus-balloon-face-0}.
-If you say @samp{%1<<}, you'll get @code{gnus-balloon-face-1} and so on.
-The @code{gnus-balloon-face-*} variables should be either strings or
-symbols naming functions that return a string. When the mouse passes
-over text with this property set, a balloon window will appear and
-display the string. Please refer to @ref{(emacs)Help Echo} (in GNU
-Emacs) or the doc string of @code{balloon-help-mode} (in XEmacs) for
-more information on this. (For technical reasons, the guillemets have
-been approximated as @samp{<<} and @samp{>>} in this paragraph.)
+special @code{balloon-help} property set to
+@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get
+@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*}
+variables should be either strings or symbols naming functions that
+return a string. When the mouse passes over text with this property
+set, a balloon window will appear and display the string. Please
+refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual},
+(in GNU Emacs) or the doc string of @code{balloon-help-mode} (in
+XEmacs) for more information on this. (For technical reasons, the
+guillemets have been approximated as @samp{<<} and @samp{>>} in this
+paragraph.)
Here's an alternative recipe for the group buffer:
@end lisp
You'd typically stick these @code{gnus-add-configuration} calls in your
-@file{.gnus.el} file or in some startup hook---they should be run after
+@file{~/.gnus.el} file or in some startup hook---they should be run after
Gnus has been loaded.
@vindex gnus-always-force-window-configuration
you'll get top speed again. Gnus will save these compiled specs in the
@file{.newsrc.eld} file. (User-defined functions aren't compiled by
this function, though---you should compile them yourself by sticking
-them into the @file{.gnus.el} file and byte-compiling that file.)
+them into the @file{~/.gnus.el} file and byte-compiling that file.)
@node Mode Lines
all the timings in the handlers will be affected.)
So, if you want to add a handler, you could put something like this in
-your @file{.gnus.el} file:
+your @file{~/.gnus.el} file:
@findex gnus-demon-add-handler
@lisp
@code{gnus-demon-add-nntp-close-connection},
@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and
@code{gnus-demon-add-scanmail}. Just put those functions in your
-@file{.gnus.el} if you want those abilities.
+@file{~/.gnus.el} if you want those abilities.
@findex gnus-demon-init
@findex gnus-demon-cancel
(add-hook 'gnus-summary-mode-hook 'gnus-moderate)
@end lisp
-in your @file{.gnus.el} file.
+in your @file{~/.gnus.el} file.
If you are the moderator of @samp{rec.zoofle}, this is how it's
supposed to work:
currently the only package that uses Smiley, it is documented here.
In short---to use Smiley in Gnus, put the following in your
-@file{.gnus.el} file:
+@file{~/.gnus.el} file:
@lisp
(setq gnus-treat-display-smileys t)
@code{gnus-convert-image-to-x-face-command} shell command.
Here's how you would typically use the first function. Put something
-like the following in your @file{.gnus.el} file:
+like the following in your @file{~/.gnus.el} file:
@lisp
(setq message-required-news-headers
The blackhole check uses the @code{dig.el} package, but you can tell
@code{spam.el} to use @code{dns.el} instead for better performance if
-you set @code{spam-use-dig} to nil. It is not recommended at this
-time to set @code{spam-use-dig} to nil despite the possible
-performance improvements, because some users may be unable to use it,
-but you can try it and see if it works for you.
+you set @code{spam-use-dig} to @code{nil}. It is not recommended at
+this time to set @code{spam-use-dig} to @code{nil} despite the
+possible performance improvements, because some users may be unable to
+use it, but you can try it and see if it works for you.
@end defvar
@defvar spam-blackhole-good-server-regex
A regular expression for IPs that should not be checked against the
-blackhole server list. When set to nil, it has no effect.
+blackhole server list. When set to @code{nil}, it has no effect.
@end defvar
@subsubsection Splitting mail using spam-stat
In order to use @code{spam-stat} to split your mail, you need to add the
-following to your @file{~/.gnus} file:
+following to your @file{~/.gnus.el} file:
@lisp
(require 'spam-stat)
@end defun
Make sure you load the dictionary before using it. This requires the
-following in your @file{~/.gnus} file:
+following in your @file{~/.gnus.el} file:
@lisp
(require 'spam-stat)
this variable, which defaults to the @samp{SAVEDIR} environment
variable, or @file{~/News/} if that variable isn't set.
-Note that Gnus is mostly loaded when the @file{.gnus.el} file is read.
+Note that Gnus is mostly loaded when the @file{~/.gnus.el} file is read.
This means that other directory variables that are initialized from this
variable won't be set properly if you set this variable in
-@file{.gnus.el}. Set this variable in @file{.emacs} instead.
+@file{~/.gnus.el}. Set this variable in @file{.emacs} instead.
@item gnus-default-directory
@vindex gnus-default-directory
@cindex Pterodactyl Gnus
@cindex Oort Gnus
@cindex No Gnus
+@cindex Gnus versions
The first ``proper'' release of Gnus 5 was done in November 1995 when it
was included in the Emacs 19.30 distribution (132 (ding) Gnus releases
Christopher Davis,
Andrew Eskilsson,
Kai Grossjohann,
+Kevin Greiner,
+Jesper Harder,
+Paul Jarc,
+Simon Josefsson,
David Kågedal,
Richard Pieri,
Fabrice Popineau,
Daniel Quinlan,
+Michael Shields,
+Reiner Steib,
Jason L. Tibbitts, III,
+Jack Vinson,
+Katsumi Yamaoka, @c Yamaoka
and
-Jack Vinson.
+Teodor Zlatanov.
Also thanks to the following for patches and stuff:
Magnus Hammerin,
Kenichi Handa, @c Handa
Raja R. Harinath,
-Yoshiki Hayashi, @c ?
+Yoshiki Hayashi, @c Hayashi
P. E. Jareth Hein,
Hisashige Kenji, @c Hisashige
Scott Hofmann,
Brad Howes,
Miguel de Icaza,
François Felix Ingrand,
-Tatsuya Ichikawa, @c ?
+Tatsuya Ichikawa, @c Ichikawa
Ishikawa Ichiro, @c Ishikawa
Lee Iverson,
Iwamuro Motonori, @c Iwamuro
Randell Jesup,
Fred Johansen,
Gareth Jones,
-Simon Josefsson,
Greg Klanderman,
Karl Kleinpaste,
Michael Klingbeil,
Christoph Wedler,
Joe Wells,
Lee Willis,
-Katsumi Yamaoka @c Yamaoka
and
Lloyd Zusman.
read if your machine should go down (@pxref{Auto Save}).
@item
-Gnus now has its own startup file (@file{.gnus.el}) to avoid cluttering up
-the @file{.emacs} file.
+Gnus now has its own startup file (@file{~/.gnus.el}) to avoid
+cluttering up the @file{.emacs} file.
@item
You can set the process mark on both groups and articles and perform
@cindex slow
Sometimes, a problem do not directly generate a elisp error but
manifests itself by causing Gnus to be very slow. In these cases, you
-can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-j} when things are
+can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are
slow, and then try to analyze the backtrace (repeating the procedure
helps isolating the real problem areas). A fancier approach is to use
the elisp profiler, ELP. The profiler is (or should be) fully
header = <text> eol
@end example
+@cindex BNF
+(The version of BNF used here is the one used in RFC822.)
+
If the return value is @code{nov}, the data buffer should contain
@dfn{network overview database} lines. These are basically fields
separated by tabs.
@example
nov-buffer = *nov-line
-nov-line = 8*9 [ field <TAB> ] eol
+nov-line = field 7*8[ <TAB> field ] eol
field = <text except TAB>
@end example
@item (nnchoke-request-update-info GROUP INFO &optional SERVER)
A Gnus group info (@pxref{Group Info}) is handed to the back end for
-alterations. This comes in handy if the back end really carries all the
-information (as is the case with virtual and imap groups). This
+alterations. This comes in handy if the back end really carries all
+the information (as is the case with virtual and imap groups). This
function should destructively alter the info to suit its needs, and
-should return a non-nil value.
+should return a non-@code{nil} value.
There should be no result data from this function.
projects / gnus / blobdiff