\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Oort Gnus v0.14}
+\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.14.
+This manual corresponds to Oort Gnus v0.18.
@end ifinfo
* Loose Threads:: How Gnus gathers loose threads into bigger threads.
* Filling In Threads:: Making the threads displayed look fuller.
* More Threading:: Even more variables for fiddling with threads.
-* Low-Level Threading:: You thought it was over... but you were wrong!
+* Low-Level Threading:: You thought it was over@dots{} but you were wrong!
Decoding Articles
* 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.
* Splitting in IMAP:: Splitting mail with nnimap.
* Expiring in IMAP:: Expiring mail with nnimap.
* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
-* Expunging mailboxes:: Equivalent of a "compress mailbox" button.
+* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
* A note on namespaces:: How to (not) use IMAP namespace in Gnus.
Other Sources
* 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 the @file{.newsrc*} files have not been saved in the master when the
slave starts, you may be prompted as to whether to read an auto-save
-file. If you answer "yes", the unsaved changes to the master will be
-incorporated into the slave. If you answer "no", the slave may see some
+file. If you answer ``yes'', the unsaved changes to the master will be
+incorporated into the slave. If you answer ``no'', the slave may see some
messages as unread that have been read in the master.
@node Fetching a Group
several servers where not all servers support @code{ask-server}.
@vindex gnus-startup-file
+@vindex gnus-backup-startup-file
+@vindex version-control
The @code{gnus-startup-file} variable says where the startup files are.
The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup
file being whatever that one is, with a @samp{.eld} appended.
+If you want version control for this file, set
+@code{gnus-backup-startup-file}. It respects the same values as the
+@code{version-control} variable.
@vindex gnus-save-newsrc-hook
@vindex gnus-save-quick-newsrc-hook
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.
@item ticked
The number of ticked articles in the group.
@item total
-The total number of articles in the group. Or rather, MAX-NUMBER minus
-MIN-NUMBER plus one.
+The total number of articles in the group. Or rather,
+@var{max-number} minus @var{min-number} plus one.
@item topic
When using the topic minor mode, this variable is bound to the current
topic being inserted.
first unread article (@code{gnus-group-read-group}). If there are no
unread articles in the group, or if you give a non-numerical prefix to
this command, Gnus will offer to fetch all the old articles in this
-group from the server. If you give a numerical prefix @var{N}, @var{N}
-determines the number of articles Gnus will fetch. If @var{N} is
-positive, Gnus fetches the @var{N} newest articles, if @var{N} is
-negative, Gnus fetches the @code{abs(@var{N})} oldest articles.
+group from the server. If you give a numerical prefix @var{n}, @var{n}
+determines the number of articles Gnus will fetch. If @var{n} is
+positive, Gnus fetches the @var{n} newest articles, if @var{n} is
+negative, Gnus fetches the @code{abs(@var{n})} oldest articles.
Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old
articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u
(auto-expire . t))
@end example
-We see that each element consists of a "dotted pair"---the thing before
+We see that each element consists of a ``dotted pair''---the thing before
the dot is the key, while the thing after the dot is the value. All the
parameters have this form @emph{except} local variable specs, which are
not dotted pairs, but proper lists.
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
Display all articles, both read and unread.
@item an integer
-Display the last INTEGER articles in the group. This is the same as
-entering the group with C-u INTEGER.
+Display the last @var{integer} articles in the group. This is the same as
+entering the group with C-u @var{integer}.
@item default
Display the default visible articles, which normally includes unread and
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
But some variables, such as @code{visible}, have no effect. For
example:
-@example
+@lisp
(setq gnus-parameters
'(("mail\\..*"
(gnus-show-threads nil)
("list\\..*"
(total-expire . t)
(broken-reply-to . t))))
-@end example
+@end lisp
String value of parameters will be subjected to regexp substitution, as
the @code{to-group} example shows.
@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
is a toggling command.)
Go ahead, just try it. I'll still be here when you get back. La de
-dum... Nice tune, that... la la la... What, you're back? Yes, and
-now press @kbd{l}. There. All your groups are now listed under
-@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and
-bothered?
+dum@dots{} Nice tune, that@dots{} la la la@dots{} What, you're back?
+Yes, and now press @kbd{l}. There. All your groups are now listed
+under @samp{misc}. Doesn't that make you feel all warm and fuzzy?
+Hot and bothered?
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)
@kindex T # (Topic)
@findex gnus-topic-mark-topic
Mark all groups in the current topic with the process mark
-(@code{gnus-topic-mark-topic}).
+(@code{gnus-topic-mark-topic}). This command works recursively on
+sub-topics unless given a prefix.
@item T M-#
@kindex T M-# (Topic)
@findex gnus-topic-unmark-topic
Remove the process mark from all groups in the current topic
-(@code{gnus-topic-unmark-topic}).
+(@code{gnus-topic-unmark-topic}). This command works recursively on
+sub-topics unless given a prefix.
@item C-c C-x
@kindex C-c C-x (Topic)
for group to post to. @xref{Composing Messages}.
This function actually prepares a news even when using mail groups.
-This is useful for "posting" messages to mail groups without actually
+This is useful for ``posting'' messages to mail groups without actually
sending them over the network: they're just saved directly to the group
in question. The corresponding back end must have a request-post method
for this to work though.
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
@vindex nnmail-extra-headers
A related variable is @code{nnmail-extra-headers}, which controls when
-to include extra headers when generating overview (@sc{nov}) files. If
-you have old overview files, you should regenerate them after changing
-this variable, by entering the server buffer using `^', and then `g' on
-the appropriate mail server (e.g. nnml) to cause regeneration.
+to include extra headers when generating overview (@sc{nov}) files.
+If you have old overview files, you should regenerate them after
+changing this variable, by entering the server buffer using @kbd{^},
+and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause
+regeneration.
@vindex gnus-summary-line-format
You also have to instruct Gnus to display the data by changing the
@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
Select the current article, or, if that one's read already, the next
unread article (@code{gnus-summary-next-page}).
+If you have an article window open already and you press @kbd{SPACE}
+again, the article will be scrolled. This lets you conveniently
+@kbd{SPACE} through an entire newsgroup. @pxref{Paging the Article}.
+
@item G n
@itemx n
@kindex n (Summary)
or, if you have come to the end of the current article, will choose the
next article (@code{gnus-summary-next-page}).
+@vindex gnus-article-boring-faces
+@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-prev-page
@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)
prefix is 1, prompt for a group to post to.
This function actually prepares a news even when using mail groups.
-This is useful for "posting" messages to mail groups without actually
+This is useful for ``posting'' messages to mail groups without actually
sending them over the network: they're just saved directly to the group
in question. The corresponding back end must have a request-post method
for this to work though.
* Loose Threads:: How Gnus gathers loose threads into bigger threads.
* Filling In Threads:: Making the threads displayed look fuller.
* More Threading:: Even more variables for fiddling with threads.
-* Low-Level Threading:: You thought it was over... but you were wrong!
+* Low-Level Threading:: You thought it was over@dots{} but you were wrong!
@end menu
@vindex gnus-thread-operation-ignore-subject
If you ignore subject while threading, you'll naturally end up with
threads that have several different subjects in them. If you then issue
-a command like `T k' (@code{gnus-summary-kill-thread}) you might not
+a command like @kbd{T k} (@code{gnus-summary-kill-thread}) you might not
wish to kill the entire thread, but just those parts of the thread that
have the same subject as the current article. If you like this idea,
you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it
also become more loaded---both with the extra article requests, and the
extra connection.
-Ok, so now you know that you shouldn't really use this thing... unless
+Ok, so now you know that you shouldn't really use this thing@dots{} unless
you really want to.
@vindex gnus-asynchronous
@vindex gnus-async-prefetch-article-p
@findex gnus-async-read-p
There are probably some articles that you don't want to pre-fetch---read
-articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should
-return non-@code{nil} when the article in question is to be
-pre-fetched. The default is @code{gnus-async-read-p}, which returns
-@code{nil} on read articles. The function is called with an article
-data structure as the only parameter.
+articles, for instance. The @code{gnus-async-prefetch-article-p}
+variable controls whether an article is to be pre-fetched. This
+function should return non-@code{nil} when the article in question is
+to be pre-fetched. The default is @code{gnus-async-read-p}, which
+returns @code{nil} on read articles. The function is called with an
+article data structure as the only parameter.
-If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like:
+If, for instance, you wish to pre-fetch only unread articles shorter
+than 100 lines, you could say something like:
@lisp
(defun my-async-short-unread-p (data)
@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}.
You can have Gnus suggest where to save articles by plonking a regexp into
the @code{gnus-split-methods} alist. For instance, if you would like to
save articles related to Gnus in the file @file{gnus-stuff}, and articles
-related to VM in @code{vm-stuff}, you could set this variable to something
+related to VM in @file{vm-stuff}, you could set this variable to something
like:
@lisp
@vindex gnus-uu-user-view-rules
@cindex sox
This variable is consulted first when viewing files. If you wish to use,
-for instance, @code{sox} to convert an @samp{.au} sound file, you could
+for instance, @code{sox} to convert an @file{.au} sound file, you could
say something like:
@lisp
(setq gnus-uu-user-view-rules
thread. This may not be smart, as no other decoder I have seen is able
to follow threads when collecting uuencoded articles. (Well, I have
seen one package that does that---@code{gnus-uu}, but somehow, I don't
-think that counts...) Default is @code{nil}.
+think that counts@dots{}) Default is @code{nil}.
@item gnus-uu-post-separate-description
@vindex gnus-uu-post-separate-description
* 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?
@item gnus-article-address-banner-alist
@vindex gnus-article-address-banner-alist
Alist of mail addresses and banners. Each element has the form
-@code{(ADDRESS . BANNER)}, where ADDRESS is a regexp matching a mail
-address in the From header, BANNER is one of a symbol @code{signature},
-an item in @code{gnus-article-banner-alist}, a regexp and @code{nil}.
-If ADDRESS matches author's mail address, it will remove things like
-advertisements. For example, if a sender has the mail address
-@samp{hail@@yoo-hoo.co.jp} and there is a banner something like
-@samp{Do You Yoo-hoo!?} in all articles he sends, you can use the
-following element to remove them:
+@code{(@var{address} . @var{banner})}, where @var{address} is a regexp
+matching a mail address in the From header, @var{banner} is one of a
+symbol @code{signature}, an item in @code{gnus-article-banner-alist},
+a regexp and @code{nil}. If @var{address} matches author's mail
+address, it will remove things like advertisements. For example, if a
+sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a
+banner something like @samp{Do You Yoo-hoo!?} in all articles he
+sends, you can use the following element to remove them:
@lisp
("@@yoo-hoo\\.co\\.jp\\'" . "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n")
you type this, you see the article exactly as it exists on disk or on
the server.
+@item g
+Force redisplaying of the current article
+(@code{gnus-summary-show-article}). This is also not really washing.
+If you type this, you see the article without any previously applied
+interactive Washing functions but with all default treatments
+(@pxref{Customizing Articles}).
+
@item W l
@kindex W l (Summary)
@findex gnus-summary-stop-page-breaking
@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 B p
@kindex B p (Summary)
@findex gnus-summary-article-posted-p
-Some people have a tendency to send you "courtesy" copies when they
+Some people have a tendency to send you ``courtesy'' copies when they
follow up to articles you have posted. These usually have a
@code{Newsgroups} header in them, but not always. This command
(@code{gnus-summary-article-posted-p}) will try to fetch the current
@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
@kindex A M (summary)
@findex gnus-mailing-list-insinuate
Gnus understands some mailing list fields of RFC 2369. To enable it,
-either add a `to-list' group parameter (@pxref{Group Parameters}),
+add a @code{to-list} group parameter (@pxref{Group Parameters}),
possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the
-summary buffer, or say:
-
-@lisp
-(add-hook 'gnus-summary-mode-hook 'turn-on-gnus-mailing-list-mode)
-@end lisp
+summary buffer.
That enables the following commands to the summary buffer:
@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.
@item to-address
Remove the @code{To} header if it only contains the address identical to
the current groups's @code{to-address} parameter.
+@item to-list
+Remove the @code{To} header if it only contains the address identical to
+the current groups's @code{to-list} parameter.
+@item cc-list
+Remove the @code{CC} header if it only contains the address identical to
+the current groups's @code{to-list} parameter.
@item date
Remove the @code{Date} header if the article is less than three days
old.
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)
@cindex article customization
A slew of functions for customizing how the articles are to look like
-exist. You can call these functions interactively, or you can have them
+exist. You can call these functions interactively
+(@pxref{Article Washing}), or you can have them
called automatically when you select the articles.
To have them called automatically, you should set the corresponding
@item gnus-treat-hide-citation-maybe (t, integer)
@item gnus-treat-hide-headers (head)
@item gnus-treat-hide-signature (t, last)
+@item gnus-treat-strip-banner (t, last)
+@item gnus-treat-strip-list-identifiers (head)
@xref{Article Hiding}.
@kindex SPACE (Article)
@findex gnus-article-next-page
Scroll forwards one page (@code{gnus-article-next-page}).
+This is exactly the same as @kbd{h SPACE h}.
@item DEL
@kindex DEL (Article)
@findex gnus-article-prev-page
Scroll backwards one page (@code{gnus-article-prev-page}).
+This is exactly the same as @kbd{h DEL h}.
@item C-c ^
@kindex C-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
lists will work most of the time. Posting to these groups (@kbd{a}) is
still a pain, though.
-@item gnus-version-expose-system
-@vindex gnus-version-expose-system
+@item gnus-user-agent
+@vindex gnus-user-agent
+@cindex User-Agent
-Your system type (@code{system-configuration} variable, such as
-@samp{i686-pc-linux}) is exposed in the auto-generated by default
-User-Agent header. Sometimes, it may be desireable (mostly because of
-aesthetic reasons) to turn it off. In this case, set it to @code{nil}.
+This variable controls which information should be exposed in the
+User-Agent header. It can be one of the symbols @code{gnus} (show only
+Gnus version), @code{emacs-gnus} (show only Emacs and Gnus versions),
+@code{emacs-gnus-config} (same as @code{emacs-gnus} plus system
+configuration), @code{emacs-gnus-type} (same as @code{emacs-gnus} plus
+system type) or a custom string. If you set it to a string, be sure to
+use a valid format, see RFC 2616."
@end table
The first element in each style is called the @code{match}. If it's a
string, then Gnus will try to regexp match it against the group name.
-If it is the form @code{(header MATCH REGEXP)}, then Gnus will look in
-the original article for a header whose name is MATCH and compare that
-REGEXP. MATCH and REGEXP are strings. (There original article is the
-one you are replying or following up to. If you are not composing a
-reply or a followup, then there is nothing to match against.) If the
-@code{match} is a function symbol, that function will be called with no
-arguments. If it's a variable symbol, then the variable will be
+If it is the form @code{(header @var{match} @var{regexp})}, then Gnus
+will look in the original article for a header whose name is
+@var{match} and compare that @var{regexp}. @var{match} and
+@var{regexp} are strings. (There original article is the one you are
+replying or following up to. If you are not composing a reply or a
+followup, then there is nothing to match against.) If the
+@code{match} is a function symbol, that function will be called with
+no arguments. If it's a variable symbol, then the variable will be
referenced. If it's a list, then that list will be @code{eval}ed. In
-any case, if this returns a non-@code{nil} value, then the style is said
-to @dfn{match}.
+any case, if this returns a non-@code{nil} value, then the style is
+said to @dfn{match}.
Each style may contain an arbitrary amount of @dfn{attributes}. Each
attribute consists of a @code{(@var{name} @var{value})} pair. The
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
variables when the definition of the variables is being loaded. If you
-change the "base" variable after the variables have been loaded, you
-won't change the "derived" variables.
+change the ``base'' variable after the variables have been loaded, you
+won't change the ``derived'' variables.
This typically affects directory and file variables. For instance,
@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml}
(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 you must have OpenSSL (@uref{http://www.openssl.org}) or SSLeay
-installed (@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}, and you also
-need @file{ssl.el} (from the W3 distribution, for instance). You then
+Opens a connection to a server over a @dfn{secure} channel. To use this
+you must have OpenSSL (@uref{http://www.openssl.org}) or SSLeay
+installed (@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}. You then
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)
These functions are called indirect because they connect to an
intermediate host before actually connecting to the @sc{nntp} server.
All of these functions and related variables are also said to belong to
-the "via" family of connection: they're all prefixed with "via" to make
+the ``via'' family of connection: they're all prefixed with ``via'' to make
things cleaner. The behavior of these functions is also affected by
commonly understood variables (@pxref{Common Variables}).
@vindex nntp-via-rlogin-command-switches
List of strings to be used as the switches to
@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use
-@samp{ssh} for `nntp-via-rlogin-command', you may set this to
+@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
mail back end of your choice into @code{gnus-secondary-select-methods},
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:
+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:
@lisp
(setq gnus-secondary-select-methods '((nnml "")))
Now, the next time you start Gnus, this back end will be queried for new
articles, and it will move all the messages in your spool file to its
-directory, which is @code{~/Mail/} by default. The new group that will
+directory, which is @file{~/Mail/} by default. The new group that will
be created (@samp{mail.misc}) will be subscribed, and you can read it
like any other group.
mail belongs in that group.
The last of these groups should always be a general one, and the regular
-expression should @emph{always} be @samp{} so that it matches any mails
+expression should @emph{always} be @samp{*} so that it matches any mails
that haven't been matched by any of the other regexps. (These rules are
processed from the beginning of the alist toward the end. The first
-rule to make a match will "win", unless you have crossposting enabled.
-In that case, all matching rules will "win".)
+rule to make a match will ``win'', unless you have crossposting enabled.
+In that case, all matching rules will ``win''.)
If you like to tinker with this yourself, you can set this variable to a
function of your choice. This function will be called without any
The mail back ends all support cross-posting. If several regexps match,
the mail will be ``cross-posted'' to all those groups.
@code{nnmail-crosspost} says whether to use this mechanism or not. Note
-that no articles are crossposted to the general (@samp{}) group.
+that no articles are crossposted to the general (@samp{*}) group.
@vindex nnmail-crosspost-link-function
@cindex crosspost
@vindex nnmail-mail-splitting-charset
@vindex nnmail-mail-splitting-decodes
-By default the splitting codes 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
The file name. Defaults to the value of the @code{MAIL}
environment variable or the value of @code{rmail-spool-directory}
(usually something like @file{/usr/mail/spool/user-name}).
+
+@item :prescript
+@itemx :postscript
+Script run before/after fetching mail.
@end table
An example file mail source:
@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:
@item :path
The name of the directory where the mails are stored. The default is
taken from the @code{MAILDIR} environment variable or
-@samp{~/Maildir/}.
+@file{~/Maildir/}.
@item :subdirs
The subdirectories of the Maildir. The default is
@samp{("new" "cur")}.
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
@item :program
When using the `shell' :stream, the contents of this variable is
-mapped into the `imap-shell-program' variable. This should be a
+mapped into the @code{imap-shell-program} variable. This should be a
@code{format}-like string (or list of strings). Here's an example:
@example
The name of the server.
@item l
-User name from `imap-default-user'.
+User name from @code{imap-default-user}.
@item p
The port number of the server.
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-incoming
@vindex mail-source-delete-incoming
-If non-@code{nil}, delete incoming files after handling them.
+If non-@code{nil}, delete incoming files after handling them. If
+@code{t}, delete the files immediately, if @code{nil}, never delete any
+files. If a positive number, delete files older than number of days
+(This will only happen, when reveiving new mail). You may also set
+@code{mail-source-delete-incoming} to @code{nil} and call
+@code{mail-source-delete-old-incoming} from a hook or interactively.
+
+@item mail-source-delete-old-incoming-confirm
+@vindex mail-source-delete-old-incoming-confirm
+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-ignore-errors
@vindex mail-source-ignore-errors
@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
when the @code{:} function is run.
@item
-@code{(! @var{func} @var{split})}: If the split is a list, and the first
-element is @code{!}, then SPLIT will be processed, and FUNC will be
-called as a function with the result of SPLIT as argument. FUNC should
-return a split.
+@code{(! @var{func} @var{split})}: If the split is a list, and the
+first element is @code{!}, then @var{split} will be processed, and
+@var{func} will be called as a function with the result of @var{split}
+as argument. @var{func} should return a split.
@item
@code{nil}: If the split is @code{nil}, it is ignored.
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
There are six different mail back ends in the standard Gnus, and more
back ends are available separately. The mail back end most people use
(because it is possibly the fastest) is @code{nnml} (@pxref{Mail
-Spool}). You might notice that only five back ends are listed below;
-@code{nnmaildir}'s documentation has not yet been completely
-incorporated into this manual. Until it is, you can find it at
-@uref{http://multivac.cwru.edu./nnmaildir/}.
+Spool}).
@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.
* Mail Folders:: Having one file for each group.
* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
@end menu
@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
@table @code
@item nnml-directory
@vindex nnml-directory
-All @code{nnml} directories will be placed under this directory.
-The default is the value of `message-directory' (whose default value is
-@file{~/Mail}).
+All @code{nnml} directories will be placed under this directory. The
+default is the value of @code{message-directory} (whose default value
+is @file{~/Mail}).
@item nnml-active-file
@vindex nnml-active-file
The active file for the @code{nnml} server. The default is
-@file{~/Mail/active"}.
+@file{~/Mail/active}.
@item nnml-newsgroups-file
@vindex nnml-newsgroups-file
The @code{nnml} group descriptions file. @xref{Newsgroups File
-Format}. The default is @file{~/Mail/newsgroups"}.
+Format}. The default is @file{~/Mail/newsgroups}.
@item nnml-get-new-mail
@vindex nnml-get-new-mail
@end table
+@node Maildir
+@subsubsection Maildir
+@cindex nnmaildir
+@cindex maildir
+
+@code{nnmaildir} stores mail in the maildir format, with each maildir
+corresponding to a group in Gnus. This format is documented here:
+@uref{http://cr.yp.to/proto/maildir.html} and here:
+@uref{http://www.qmail.org/man/man5/maildir.html}. nnmaildir also
+stores extra information in the @file{.nnmaildir/} directory within a
+maildir.
+
+Maildir format was designed to allow concurrent deliveries and
+reading, without needing locks. With other backends, you would have
+your mail delivered to a spool of some kind, and then you would
+configure Gnus to split mail from that spool into your groups. You
+can still do that with nnmaildir, but the more common configuration is
+to have your mail delivered directly to the maildirs that appear as
+group in Gnus.
+
+nnmaildir is designed to be perfectly reliable: @kbd{C-g} will never
+corrupt its data in memory, and @code{SIGKILL} will never corrupt its
+data in the filesystem.
+
+nnmaildir stores article marks and NOV data in each maildir. So you
+can copy a whole maildir from one Gnus setup to another, and you will
+keep your marks.
+
+Virtual server settings:
+
+@table @code
+@item directory
+For each of your nnmaildir servers (it's very unlikely that you'd need
+more than one), you need to create a directory and populate it with
+maildirs or symlinks to maildirs (and nothing else; do not choose a
+directory already used for other purposes). Each maildir will be
+represented in Gnus as a newsgroup on that server; the filename of the
+symlink will be the name of the group. Any filenames in the directory
+starting with `.' 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
+the path of the directory for this server. The form is @code{eval}ed
+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
+@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 target-prefix
+This should be a Lisp form which is processed by @code{eval} and
+@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
+@code{directory-files} (such as @code{directory-files} itself). It is
+used to scan the server's @code{directory} for maildirs. This
+parameter is optional; the default is
+@code{nnheader-directory-files-safe} if
+@code{nnheader-directory-files-is-safe} is @code{nil}, and
+@code{directory-files} otherwise.
+(@code{nnheader-directory-files-is-safe} is checked only once when the
+server is opened; if you want to check it each time the directory is
+scanned, you'll have to provide your own function that does that.)
+
+@item get-new-mail
+If non-@code{nil}, then after scanning for new mail in the group
+maildirs themselves as usual, this server will also incorporate mail
+the conventional Gnus way, from @code{mail-sources} according to
+@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default
+value is @code{nil}.
+
+Do @emph{not} use the same maildir both in @code{mail-sources} and as
+an nnmaildir group. The results might happen to be useful, but that
+would be by chance, not by design, and the results might be different
+in the future. If your split rules create new groups, remember to
+supply a @code{create-directory} server parameter.
+@end table
+
+@subsubsection Group parameters
+
+nnmaildir uses several group parameters. It's safe to ignore all
+this; the default behavior for nnmaildir is the same as the default
+behavior for other mail backends: articles are deleted after one week,
+etc. Except for the expiry parameters, all this functionality is
+unique to nnmaildir, so you can ignore it if you're just trying to
+duplicate the behavior you already have with another backend.
+
+If the value of any of these parameters is a vector, the first element
+is evaluated as a Lisp form and the result is used, rather than the
+original value. If the value is not a vector, the value itself is
+evaluated as a Lisp form. (This is why these parameters use names
+different from those of other, similar parameters supported by other
+backends: they have different, though similar, meanings.) (For
+numbers, strings, @code{nil}, and @code{t}, you can ignore the
+@code{eval} business again; for other values, remember to use an extra
+quote and wrap the value in a vector when appropriate.)
+
+@table @code
+@item expire-age
+An integer specifying the minimum age, in seconds, of an article before
+it will be expired, or the symbol @code{never} to specify that
+articles should never be expired. If this parameter is not set,
+nnmaildir falls back to the usual
+@code{nnmail-expiry-wait}(@code{-function}) variables (overridable by
+the @code{expiry-wait}(@code{-function}) group parameters. If you
+wanted a value of 3 days, you could use something like @code{[(* 3 24
+60 60)]}; nnmaildir will evaluate the form and use the result. An
+article's age is measured starting from the article file's
+modification time. Normally, this is the same as the article's
+delivery time, but editing an article makes it younger. Moving an
+article (other than via expiry) may also make an article younger.
+
+@item expire-group
+If this is set to a string (a full Gnus group name, like
+@code{"backend+server.address.string:group.name"}), and if it is not
+the name of the same group that the parameter belongs to, then
+articles will be moved to the specified group during expiry before
+being deleted. @emph{If this is set to an nnmaildir group, the
+article will be just as old in the destination group as it was in the
+source group.} So be careful with @code{expire-age} in the
+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
+maildir as read-only. This means: articles are not renamed from
+@file{new/} into @file{cur/}; articles are only found in @file{new/},
+not @file{cur/}; articles are never deleted; articles cannot be
+edited. @file{new/} is expected to be a symlink to the @file{new/}
+directory of another maildir - e.g., a system-wide mailbox containing
+a mailing list of common interest. Everything in the maildir outside
+@file{new/} is @emph{not} treated as read-only, so for a shared
+mailbox, you do still need to set up your own maildir (or have write
+permission to the shared mailbox); your maildir just won't contain
+extra copies of the articles.
+
+@item directory-files
+A function with the same interface as @code{directory-files}. It is
+used to scan the directories in the maildir corresponding to 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
+article marks, nnmaildir will say that all articles have these
+marks, regardless of whether the marks stored in the filesystem
+say so. This is a proof-of-concept feature that will probably be
+removed eventually; it ought to be done in Gnus proper, or
+abandoned if it's not worthwhile.
+
+@item never-marks
+A list of mark symbols, such as @code{['(tick expire)]}. Whenever
+Gnus asks nnmaildir for article marks, nnmaildir will say that no
+articles have these marks, regardless of whether the marks stored in
+the filesystem say so. @code{never-marks} overrides
+@code{always-marks}. This is a proof-of-concept feature that will
+probably be removed eventually; it ought to be done in Gnus proper, or
+abandoned if it's not worthwhile.
+
+@item nov-cache-size
+An integer specifying the size of the NOV memory cache. To speed
+things up, nnmaildir keeps NOV data in memory for a limited number of
+articles in each group. (This is probably not worthwhile, and will
+probably be removed in the future.) This parameter's value is noticed
+only the first time a group is seen after the server is opened - i.e.,
+when you first start Gnus, typically. The NOV cache is never resized
+until the server is closed and reopened. The default is an estimate
+of the number of articles that would be displayed in the summary
+buffer: a count of articles that are either marked with @code{tick} or
+not marked with @code{read}, plus a little extra.
+@end table
+
+@subsubsection Article identification
+Articles are stored in the @file{cur/} subdirectory of each maildir.
+Each article file is named like @code{uniq:info}, where @code{uniq}
+contains no colons. nnmaildir ignores, but preserves, the
+@code{:info} part. (Other maildir readers typically use this part of
+the filename to store marks.) The @code{uniq} part uniquely
+identifies the article, and is used in various places in the
+@file{.nnmaildir/} subdirectory of the maildir to store information
+about the corresponding article. The full pathname of an article is
+available in the variable @code{nnmaildir-article-file-name} after you
+request the article in the summary buffer.
+
+@subsubsection NOV data
+An article identified by @code{uniq} has its NOV data (used to
+generate lines in the summary buffer) stored in
+@code{.nnmaildir/nov/uniq}. There is no
+@code{nnmaildir-generate-nov-databases} function. (There isn't much
+need for it - an article's NOV data is updated automatically when the
+article or @code{nnmail-extra-headers} has changed.) You can force
+nnmaildir to regenerate the NOV data for a single article simply by
+deleting the corresponding NOV file, but @emph{beware}: this will also
+cause nnmaildir to assign a new article number for this article, which
+may cause trouble with @code{seen} marks, the Agent, and the cache.
+
+@subsubsection Article marks
+An article identified by @code{uniq} is considered to have the mark
+@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists.
+When Gnus asks nnmaildir for a group's marks, nnmaildir looks for such
+files and reports the set of marks it finds. When Gnus asks nnmaildir
+to store a new set of marks, nnmaildir creates and deletes the
+corresponding files as needed. (Actually, rather than create a new
+file for each mark, it just creates hard links to
+@file{.nnmaildir/markfile}, to save inodes.)
+
+You can invent new marks by creating a new directory in
+@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from
+your server, untar it later, and keep your marks. You can add and
+remove marks yourself by creating and deleting mark files. If you do
+this while Gnus is running and your nnmaildir server is open, it's
+best to exit all summary buffers for nnmaildir groups and type @kbd{s}
+in the group buffer first, and to type @kbd{g} or @kbd{M-g} in the
+group buffer afterwards. Otherwise, Gnus might not pick up the
+changes, and might undo them.
+
+
@node Mail Folders
@subsubsection Mail Folders
@cindex nnfolder
@item nnfolder-newsgroups-file
@vindex nnfolder-newsgroups-file
The name of the group descriptions file. @xref{Newsgroups File
-Format}. The default is @file{~/Mail/newsgroups"}
+Format}. The default is @file{~/Mail/newsgroups}
@item nnfolder-get-new-mail
@vindex nnfolder-get-new-mail
@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
Basically the effect of @code{nnfolder} is @code{nnmbox} (the first
method described above) on a per-group basis. That is, @code{nnmbox}
-itself puts *all* one's mail in one file; @code{nnfolder} provides a
+itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a
little bit of optimization to this so that each of one's mail groups has
a Unix mail box file. It's faster than @code{nnmbox} because each group
can be parsed separately, and still provides the simple Unix mail box
@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
@item nnslashdot-directory
@vindex nnslashdot-directory
Where @code{nnslashdot} will store its files. The default is
-@samp{~/News/slashdot/}.
+@file{~/News/slashdot/}.
@item nnslashdot-active-url
@vindex nnslashdot-active-url
@item nnultimate-directory
@vindex nnultimate-directory
The directory where @code{nnultimate} stores its files. The default is
-@samp{~/News/ultimate/}.
+@file{~/News/ultimate/}.
@end table
@item nnwarchive-directory
@vindex nnwarchive-directory
The directory where @code{nnwarchive} stores its files. The default is
-@samp{~/News/warchive/}.
+@file{~/News/warchive/}.
@item nnwarchive-login
@vindex nnwarchive-login
@item nnrss-directory
@vindex nnrss-directory
The directory where @code{nnrss} stores its files. The default is
-@samp{~/News/rss/}.
+@file{~/News/rss/}.
@end table
@cindex nnimap
@cindex @sc{imap}
-@sc{imap} is a network protocol for reading mail (or news, or ...),
+@sc{imap} is a network protocol for reading mail (or news, or @dots{}),
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.
manipulate mails stored on the @sc{imap} server. This is the kind of
usage explained in this section.
-A server configuration in @code{~/.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}) as well as the external
-library @samp{ssl.el}.
+@samp{openssl}) or SSLeay (@samp{s_client}).
@item
@dfn{shell:} Use a shell command to start @sc{imap} connection.
@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,
SSLeay, 0.9.x, are known to have serious bugs making it
useless. Earlier versions, especially 0.8.x, of SSLeay are known to
work. The variable @code{imap-ssl-program} contain parameters to pass
-to OpenSSL/SSLeay. You also need @samp{ssl.el} (from the W3
-distribution, for instance).
+to OpenSSL/SSLeay.
@vindex imap-shell-program
@vindex imap-shell-host
@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}.
@table @code
@item always
-The default behavior, delete all articles marked as "Deleted" when
+The default behavior, delete all articles marked as ``Deleted'' when
closing a mailbox.
@item never
Never actually delete articles. Currently there is no way of showing
@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}
* Splitting in IMAP:: Splitting mail with nnimap.
* Expiring in IMAP:: Expiring mail with nnimap.
* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox.
-* Expunging mailboxes:: Equivalent of a "compress mailbox" button.
+* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button.
* A note on namespaces:: How to (not) use IMAP namespace in Gnus.
@end menu
@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
them every time you fetch new mail.)
These rules are processed from the beginning of the alist toward the
-end. The first rule to make a match will "win", unless you have
-crossposting enabled. In that case, all matching rules will "win".
+end. The first rule to make a match will ``win'', unless you have
+crossposting enabled. In that case, all matching rules will ``win''.
This variable can also have a function as its value, the function will
be called with the headers narrowed and should return a group where it
@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
@item nnmail-expiry-wait-function
These variables are fully supported. The expire value can be a
-number, the symbol @var{immediate} or @var{never}.
+number, the symbol @code{immediate} or @code{never}.
@item nnmail-expiry-target
@itemize @bullet
@item
-Giving "anyone" the "lrs" rights (lookup, read, keep seen/unseen flags)
+Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags)
on your mailing list mailboxes enables other users on the same server to
follow the list without subscribing to it.
@item
At least with the Cyrus server, you are required to give the user
-"anyone" posting ("p") capabilities to have "plussing" work (that is,
+``anyone'' posting ("p") capabilities to have ``plussing'' work (that is,
mail sent to user+mailbox@@domain ending up in the @sc{imap} mailbox
INBOX.mailbox).
@end itemize
names like @code{#driver.mbx/read-mail} which are valid only in the
@sc{create} and @sc{append} commands. After the mailbox is created
(or a messages is appended to a mailbox), it must be accessed without
-the namespace prefix, i.e @code{read-mail}. Since Gnus do not make it
+the namespace prefix, i.e. @code{read-mail}. Since Gnus do not make it
possible for the user to guarantee that user entered mailbox names
will only be used with the CREATE and APPEND commands, you should
simply not use the namespace prefixed mailbox names in Gnus.
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
run through @code{nndoc-unquote-dashes} before being delivered.
To hook your own document definition into @code{nndoc}, use the
-@code{nndoc-add-type} function. It takes two parameters---the first is
-the definition itself and the second (optional) parameter says where in
-the document type definition alist to put this definition. The alist is
-traversed sequentially, and @code{nndoc-TYPE-type-p} is called for a given type @code{TYPE}. So @code{nndoc-mmdf-type-p} is called to see whether a document
-is of @code{mmdf} type, and so on. These type predicates should return
-@code{nil} if the document is not of the correct type; @code{t} if it is
-of the correct type; and a number if the document might be of the
-correct type. A high number means high probability; a low number means
-low probability with @samp{0} being the lowest valid number.
+@code{nndoc-add-type} function. It takes two parameters---the first
+is the definition itself and the second (optional) parameter says
+where in the document type definition alist to put this definition.
+The alist is traversed sequentially, and @code{nndoc-TYPE-type-p} is
+called for a given type @code{TYPE}. So @code{nndoc-mmdf-type-p} is
+called to see whether a document is of @code{mmdf} type, and so on.
+These type predicates should return @code{nil} if the document is not
+of the correct type; @code{t} if it is of the correct type; and a
+number if the document might be of the correct type. A high number
+means high probability; a low number means low probability with
+@samp{0} being the lowest valid number.
@node SOUP
@item nnsoup-replies-directory
@vindex nnsoup-replies-directory
All replies will be stored in this directory before being packed into a
-reply packet. The default is @file{~/SOUP/replies/"}.
+reply packet. The default is @file{~/SOUP/replies/}.
@item nnsoup-replies-format-type
@vindex nnsoup-replies-format-type
* 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... that's it.
+Uhm@dots{} that's it.
@end itemize
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}
always a reliable indication of when it was posted. Hell, some people
just don't give a damn.
-The above predicates apply to *all* the groups which belong to the
+The above predicates apply to @emph{all} the groups which belong to the
category. However, if you wish to have a specific predicate for an
individual group within a category, or you're just too lazy to set up a
new category, you can enter a group's individual predicate in it's group
(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"
@item
Agent score file
-These score files must *only* contain the permitted scoring keywords
-stated above.
+These score files must @emph{only} contain the permitted scoring
+keywords stated above.
example:
These directives in either the category definition or a group's
parameters will cause the agent to read in all the applicable score
-files for a group, *filtering out* those sections that do not
+files for a group, @emph{filtering out} those sections that do not
relate to one of the permitted subset of scoring keywords.
@itemize @bullet
@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.
@end itemize
-Technical note: the synchronization algorithm does not work by "pushing"
+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
+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.
@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 `nil'.
+@strong{No}, unless @code{gnus-agent-cache} is @code{nil}.
@end table
@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)
Score on the @code{Message-ID} header.
@item e
-Score on an "extra" header, that is, one of those in gnus-extra-headers,
+Score on an ``extra'' header, that is, one of those in gnus-extra-headers,
if your @sc{nntp} server tracks additional header data in overviews.
@item f
@item gnus-score-file-suffix
@vindex gnus-score-file-suffix
Suffix to add to the group name to arrive at the score file name
-(@samp{SCORE} by default.)
+(@file{SCORE} by default.)
@item gnus-score-uncacheable-files
@vindex gnus-score-uncacheable-files
@cindex score cache
All score files are normally cached to avoid excessive re-loading of
score files. However, if this might make your Emacs grow big and
-bloated, so this regexp can be used to weed out score files unlikely to be needed again. It would be a bad idea to deny caching of
+bloated, so this regexp can be used to weed out score files unlikely
+to be needed again. It would be a bad idea to deny caching of
@file{all.SCORE}, while it might be a good idea to not cache
@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this
variable is @samp{ADAPT$} by default, so no adaptive score files will
@item local
@cindex local variables
-The value of this entry should be a list of @code{(VAR VALUE)} pairs.
-Each @var{var} will be made buffer-local to the current summary buffer,
-and set to the value specified. This is a convenient, if somewhat
-strange, way of setting variables in some groups if you don't like hooks
-much. Note that the @var{value} won't be evaluated.
+The value of this entry should be a list of @code{(@var{var}
+@var{value})} pairs. Each @var{var} will be made buffer-local to the
+current summary buffer, and set to the value specified. This is a
+convenient, if somewhat strange, way of setting variables in some
+groups if you don't like hooks much. Note that the @var{value} won't
+be evaluated.
@end table
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.
@vindex gnus-adaptive-file-suffix
The adaptive score entries will be put into a file where the name is the
group name with @code{gnus-adaptive-file-suffix} appended. The default
-is @samp{ADAPT}.
+is @file{ADAPT}.
@vindex gnus-score-exact-adapt-limit
When doing adaptive scoring, substring or fuzzy matching would probably
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)
old articles for a long time.
@end itemize
-... I wonder whether other newsreaders will support global score files
+@dots{} I wonder whether other newsreaders will support global score files
in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue
Wave, xrn and 1stReader are bound to implement scoring. Should we start
holding our breath yet?
In GroupLens, an article is rated on a scale from 1 to 5, inclusive.
Where 1 means something like this article is a waste of bandwidth and 5
means that the article was really good. The basic question to ask
-yourself is, "on a scale from 1 to 5 would I like to see more articles
-like this one?"
+yourself is, ``on a scale from 1 to 5 would I like to see more articles
+like this one?''
There are four ways to enter a rating for an article in GroupLens.
that do explicitly say so in this manual. To apply the process/prefix
convention to commands that do not use it, you can use the @kbd{M-&}
command. For instance, to mark all the articles in the group as
-expirable, you could say `M P b M-& E'.
+expirable, you could say @kbd{M P b M-& E}.
@node Interactive
@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)
friends.@footnote{On a GNU/Linux system look for packages with names
like @code{netpbm}, @code{libgr-progs} and @code{compface}.})
-(NOTE: @code{x-face} is used in the variable/function names, not
+(Note: @code{x-face} is used in the variable/function names, not
@code{xface}).
Gnus provides a few convenience functions and variables to allow
@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
@item hashcash-payment-alist
@vindex hashcash-payment-alist
Some receivers may require you to spend burn more CPU time than the
-default. This variable contains a list of @samp{(ADDR AMOUNT)} cells,
-where ADDR is the receiver (email address or newsgroup) and AMOUNT is
-the number of bits in the collision that is needed. It can also
-contain @samp{(ADDR STRING AMOUNT)} cells, where the STRING is the
-string to use (normally the email address or newsgroup name is used).
+default. This variable contains a list of @samp{(@var{addr}
+@var{amount})} cells, where @var{addr} is the receiver (email address
+or newsgroup) and @var{amount} is the number of bits in the collision
+that is needed. It can also contain @samp{(@var{addr} @var{string}
+@var{amount})} cells, where the @var{string} is the string to use
+(normally the email address or newsgroup name is used).
@item hashcash
@vindex hashcash
they get the @samp{$} mark when you enter the group. You must review
these messages from time to time and remove the @samp{$} mark for
every message that is not spam after all. To remove the @samp{$}
-mark, you can use @kbd{M-u} to "unread" the article, or @kbd{d} for
+mark, you can use @kbd{M-u} to ``unread'' the article, or @kbd{d} for
declaring it read the non-spam way. When you leave a group, all
spam-marked (@samp{$}) articles are sent to a spam processor which
will study them as spam samples.
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
@item
code
-@example
+@lisp
(defvar spam-use-blackbox nil
"True if blackbox should be used.")
-@end example
+@end lisp
Add
@example
Write the @code{spam-check-blackbox} function. It should return
@samp{nil} or @code{spam-split-group}. See the existing
@code{spam-check-*} functions for examples of what you can do.
+
+Make sure to add @code{spam-use-blackbox} to
+@code{spam-list-of-statistical-checks} if Blackbox is a statistical
+mail analyzer that needs the full message body to operate.
+
@end enumerate
For processing spam and ham messages, provide the following:
Note you don't have to provide a spam or a ham processor. Only
provide them if Blackbox supports spam or ham processing.
-@example
+@lisp
(defvar gnus-group-spam-exit-processor-blackbox "blackbox"
"The Blackbox summary exit spam processor.
Only applicable to spam groups.")
"The whitelist summary exit ham processor.
Only applicable to non-spam (unclassified and ham) groups.")
-@end example
+@end lisp
@item
functionality
-@example
+@lisp
(defun spam-blackbox-register-spam-routine ()
(spam-generic-register-routine
;; the spam function
(let ((from (spam-fetch-field-from-fast article)))
(when (stringp from)
(blackbox-do-something-with-this-ham-sender from))))))
-@end example
+@end lisp
Write the @code{blackbox-do-something-with-this-ham-sender} and
@code{blackbox-do-something-with-this-spammer} functions. You can add
@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:
-@example
+@lisp
(require 'spam-stat)
(spam-stat-load)
-@end example
+@end lisp
This will load the necessary Gnus code, and the dictionary you
created.
spam or it should go into @samp{mail.misc}. If it is spam, then
@code{spam-stat-split-fancy} will return @samp{mail.spam}.
-@example
+@lisp
(setq nnmail-split-fancy
`(| (: spam-stat-split-fancy)
"mail.misc"))
-@end example
+@end lisp
@defvar spam-stat-split-fancy-spam-group
The group to use for spam. Default is @samp{mail.spam}.
the following expression. Only mails not matching the regular
expression are considered potential spam.
-@example
+@lisp
(setq nnmail-split-fancy
`(| ("Subject" "\\bspam-stat\\b" "mail.emacs")
(: spam-stat-split-fancy)
"mail.misc"))
-@end example
+@end lisp
If you want to filter for spam first, then you must be careful when
creating the dictionary. Note that @code{spam-stat-split-fancy} must
non-spam, therefore both should be in your collection of non-spam
mails, when creating the dictionary!
-@example
+@lisp
(setq nnmail-split-fancy
`(| (: spam-stat-split-fancy)
("Subject" "\\bspam-stat\\b" "mail.emacs")
"mail.misc"))
-@end example
+@end lisp
You can combine this with traditional filtering. Here, we move all
HTML-only mails into the @samp{mail.spam.filtered} group. Note that since
nor in your collection of non-spam mails, when creating the
dictionary!
-@example
+@lisp
(setq nnmail-split-fancy
`(| ("Content-Type" "text/html" "mail.spam.filtered")
(: spam-stat-split-fancy)
("Subject" "\\bspam-stat\\b" "mail.emacs")
"mail.misc"))
-@end example
+@end lisp
@node Low-level interface to the spam-stat dictionary
@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:
-@example
+@lisp
(require 'spam-stat)
(spam-stat-load)
-@end example
+@end lisp
Typical test will involve calls to the following functions:
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
Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that
``worser''? ``much worser''? ``worsest''?)
-I would like to take this opportunity to thank the Academy for... oops,
+I would like to take this opportunity to thank the Academy for@dots{} oops,
wrong show.
@itemize @bullet
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
New element in @code{gnus-boring-article-headers}---@code{long-to}.
@item
- @kbd{M-i} symbolic prefix command. See the section "Symbolic
-Prefixes" in the Gnus manual for details.
+ @kbd{M-i} symbolic prefix command. See the section ``Symbolic
+Prefixes'' in the Gnus manual for details.
@item
@kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix
-@kbd{a} to add the score rule to the "all.SCORE" file.
+@kbd{a} to add the score rule to the @file{all.SCORE} file.
@item
@code{gnus-simplify-subject-functions} variable to allow greater
@code{gnus-adaptive-word-minimum} variable.
@item
- The "lapsed date" article header can be kept continually
+ The ``lapsed date'' article header can be kept continually
updated by the @code{gnus-start-date-timer} command.
@item
@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 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
documented elsewhere, but to get you started there are a few steps
that need to be followed. First, instrument the part of Gnus you are
interested in for profiling, e.g. @kbd{M-x elp-instrument-package RET
-gnus} or @kbd{M-x elp-instrument-packagre RET message}. Then perform
+gnus} or @kbd{M-x elp-instrument-package RET message}. Then perform
the operation that is slow and press @kbd{M-x elp-results}. You will
then see which operations that takes time, and can debug them further.
If the entire operation takes much longer than the time spent in the
@cindex gnu.emacs.gnus
@cindex ding mailing list
-You can also ask on the ding mailing list---@samp{ding@@gnus.org}.
-Write to @samp{ding-request@@gnus.org} to subscribe.
+You can also ask on the ding mailing list---@email{ding@@gnus.org}.
+Write to @email{ding-request@@gnus.org} to subscribe.
@page
This might later be expanded to @code{various}, which will be a mixture
of HEADs and @sc{nov} lines, but this is currently not supported by Gnus.
-If @var{fetch-old} is non-@code{nil} it says to try fetching "extra
-headers", in some meaning of the word. This is generally done by
+If @var{fetch-old} is non-@code{nil} it says to try fetching ``extra
+headers'', in some meaning of the word. This is generally done by
fetching (at most) @var{fetch-old} extra headers less than the smallest
article number in @code{articles}, and filling the gaps as well. The
presence of this parameter can be ignored if the back end finds it
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.
There should be no result data returned.
-@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM
-&optional LAST)
+@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST)
This function should move @var{article} (which is a number) from
@var{group} by calling @var{accept-form}.
This macro defines some common functions that almost all back ends should
have.
-@example
+@lisp
(nnoo-define-basics nndir)
-@end example
+@end lisp
@item deffoo
This macro is just like @code{defun} and takes the same parameters. In
This macro allows mapping of functions from the current back end to
functions from the parent back ends.
-@example
+@lisp
(nnoo-map-functions nndir
(nnml-retrieve-headers 0 nndir-current-group 0 0)
(nnmh-request-article 0 nndir-current-group 0 0))
-@end example
+@end lisp
This means that when @code{nndir-retrieve-headers} is called, the first,
third, and fourth parameters will be passed on to
last thing in the source file, since it will only define functions that
haven't already been defined.
-@example
+@lisp
(nnoo-import nndir
(nnmh
nnmh-request-list
nnmh-request-newgroups)
(nnml))
-@end example
+@end lisp
This means that calls to @code{nndir-request-list} should just be passed
on to @code{nnmh-request-list}, while all public functions from
projects / gnus / blobdiff