\ifx\pdfoutput\undefined
\else
-\usepackage[pdftex,bookmarks]{hyperref}
+\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref}
+\usepackage{thumbpdf}
\pdfcompresslevel=9
\fi
\makeindex
\begin{document}
-\newcommand{\gnusversionname}{Oort Gnus v0.05}
+\newcommand{\gnusversionname}{Oort Gnus v0.06}
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}
\thispagestyle{empty}
-Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001
+Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
Free Software Foundation, Inc.
This file documents Gnus, the GNU Emacs newsreader.
-Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001
+Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001
+Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
spool or your mbox file. All at the same time, if you want to push your
luck.
-This manual corresponds to Oort Gnus v0.05
+This manual corresponds to Oort Gnus v0.06.
@end ifinfo
* Posting Styles:: An easier way to specify who you are.
* Drafts:: Postponing messages and rejected messages.
* Rejected Articles:: What happens if the server doesn't like your article?
-* Using GPG:: How to use GPG and MML to sign and encrypt messages
+* Signing and encrypting:: How to compose secure messages.
Select Methods
* XEmacs:: Requirements for installing under XEmacs.
* History:: How Gnus got where it is today.
-* The Manual::
* On Writing Manuals:: Why this is not a beginner's guide.
* Terminology:: We use really difficult, like, words here.
* Customization:: Tailoring Gnus to your needs.
* Troubleshooting:: What you might try if things do not work.
* Gnus Reference Guide:: Rilly, rilly technical stuff.
* Emacs for Heathens:: A short introduction to Emacsian terms.
+* Frequently Asked Questions::
History
gnus-group-clear-data-on-native-groups} command to clear out all data
that you have on your native groups. Use with caution.
+@kindex M-x gnus-group-clear-data
+@findex gnus-group-clear-data
+Clear the data from the current group only---nix out marks and the
+list of read articles (@code{gnus-group-clear-data}).
+
After changing servers, you @strong{must} move the cache hierarchy away,
since the cached articles will have wrong article numbers, which will
affect which articles Gnus thinks are read.
+@code{gnus-group-clear-data-on-native-groups} will ask you if you want
+to have it done automatically; for @code{gnus-group-clear-data}, you
+can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the
+cache for all groups).
@node Startup Files
@item unseen
Place point on the subject line of the first unseen article.
+@item unseen-or-unread
+Place point on the subject line of the first unseen article, and if
+there is no such article, place point on the subject line of the first
+unread article.
+
@item best
Place point on the subject line of the highest-scored unread article.
See also @code{gnus-parameter-to-list-alist}.
+@anchor{subscribed}
+@item subscribed
+@cindex subscribed
+If this parameter is set to @code{t}, Gnus will consider the
+to-address and to-list parameters for this group as addresses of
+mailing lists you are subscribed to. Giving Gnus this information
+will help it to generate correct Mail-Followup-To headers for your
+posts to these lists.
+
+See also @code{gnus-find-subscribed-addresses}, the function that
+directly uses this group parameter.
+
@item visible
@cindex visible
If the group parameter list has the element @code{(visible . t)},
@item gcc-self
@cindex gcc-self
If @code{(gcc-self . t)} is present in the group parameter list, newly
-composed messages will be @code{Gcc}'d to the current group. If
+composed messages will be @code{Gcc}'d to the current group If
@code{(gcc-self . none)} is present, no @code{Gcc:} header will be
generated, if @code{(gcc-self . "string")} is present, this string will
be inserted literally as a @code{gcc} header. This parameter takes
precedence over any default @code{Gcc} rules as described later
-(@pxref{Archived Messages}).
+(@pxref{Archived Messages}). CAVEAT:: It yields an error putting
+@code{(gcc-self . t)} in groups of a @code{nntp} server or so, because
+a @code{nntp} server doesn't accept artciles.
@item auto-expire
@cindex auto-expire
Here are some examples:
@table @code
-@item [read]
-Display only read articles.
+@item [unread]
+Display only unread articles.
@item [not expire]
Display everything except expirable articles.
The available operators are @code{not}, @code{and} and @code{or}.
Predicates include @code{tick}, @code{unsend}, @code{undownload},
-@code{read}, @code{dormant}, @code{expire}, @code{reply},
+@code{unread}, @code{dormant}, @code{expire}, @code{reply},
@code{killed}, @code{bookmark}, @code{score}, @code{save},
-@code{cache}, @code{forward}, @code{seen} and @code{recent}.
+@code{cache}, @code{forward}, @code{unseen} and @code{recent}.
@end table
Commands}) the following Sieve code is generated:
@example
- if address \"sender\" \"sieve-admin@@extundo.com\" @{
- fileinto \"INBOX.list.sieve\";
- @}
+if address \"sender\" \"sieve-admin@@extundo.com\" @{
+ fileinto \"INBOX.list.sieve\";
+@}
@end example
The Sieve language is described in RFC 3028. @xref{Top, , Top, sieve,
in the summary buffer you enter, and the form @code{nil} will be
@code{eval}ed there.
+@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
+@samp{nntp+news.gnus.org:gmane.text.docbook.apps} has the tag
+@samp{DOC-BOOK-APPS:} in the subject of all articles, this tag can be
+removed from the article subjects in the summary buffer for the group by
+putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")} into the group
+parameters for the group.
+
+
This can also be used as a group-specific hook function, if you'd like.
If you want to hear a beep when you enter a group, you could put
something like @code{(dummy-variable (ding))} in the parameters of that
"%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n")
@end lisp
+If you would like greater control of the time format, you can use a
+user-defined format spec. Something like the following should do the
+trick:
+
+@lisp
+(setq gnus-group-line-format
+ "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n")
+(defun gnus-user-format-function-d (headers)
+ (let ((time (gnus-group-timestamp gnus-tmp-group)))
+ (if time
+ (format-time-string "%b %d %H:%M" time)
+ "")))
+@end lisp
+
@node File Commands
@subsection File Commands
goes out to all people listed in the @code{To}, @code{From} (or
@code{Reply-to}) and @code{Cc} headers.
-@item S W
-@kindex S W (Summary)
+@item S V
+@kindex S V (Summary)
@findex gnus-summary-wide-reply-with-original
Mail a wide reply to the current article and include the original
message (@code{gnus-summary-wide-reply-with-original}). This command uses
* Unread Articles:: Marks for unread articles.
* Read Articles:: Marks for read articles.
* Other Marks:: Marks that do not affect readedness.
-* Setting Marks::
-* Generic Marking Commands::
-* Setting Process Marks::
@end menu
@ifinfo
If non-@code{nil}, all threads will be hidden when the summary buffer is
generated.
+This can also be a predicate specifier (@pxref{Predicate Specifiers}).
+Avaliable predicates are @code{gnus-article-unread-p} and
+@code{gnus-article-unseen-p}).
+
+Here's an example:
+
+@lisp
+(setq gnus-thread-hide-subtree
+ '(or gnus-article-unread-p
+ gnus-article-unseen-p))
+@end lisp
+
+(It's a pretty nonsensical example, since all unseen articles are also
+unread, but you get my drift.)
+
+
@item gnus-thread-expunge-below
@vindex gnus-thread-expunge-below
All threads that have a total score (as defined by
@findex gnus-thread-sort-by-author
@findex gnus-thread-sort-by-number
@vindex gnus-thread-sort-functions
+@findex gnus-thread-sort-by-most-recent-thread
If you are using a threaded summary display, you can sort the threads by
setting @code{gnus-thread-sort-functions}, which can be either a single
function, a list of functions, or a list containing functions and
By default, sorting is done on article numbers. Ready-made sorting
predicate functions include @code{gnus-thread-sort-by-number},
@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject},
-@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and
+@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score},
+@code{gnus-thread-sort-by-most-recent-number},
+@code{gnus-thread-sort-by-most-recent-date} and
@code{gnus-thread-sort-by-total-score}.
Each function takes two threads and returns non-@code{nil} if the first
files, and @kbd{gnus-cache-generate-active} will (re)generate the active
file.
+@findex gnus-cache-move-cache
+@code{gnus-cache-move-cache} will move your whole
+@code{gnus-cache-directory} to some other location. You get asked to
+where, isn't that cool?
@node Persistent Articles
@section Persistent Articles
common encoding employed when sending Chinese articles. It typically
makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}.
+@item W u
+@kindex W u (Summary)
+@findex gnus-article-unsplit-urls
+Remove newlines from within URLs. Some mailers insert newlines into
+outgoing email messages to keep lines short. This reformatting can
+split long URLs onto multiple lines. Repair those URLs by removing
+the newlines (@code{gnus-article-unsplit-urls}).
+
@item W h
@kindex W h (Summary)
@findex gnus-article-wash-html
-Treat HTML (@code{gnus-article-wash-html}).
-Note that the this is usually done automatically by Gnus if the message
-in question has a @code{Content-Type} header that says that this type
-has been done.
+Treat HTML (@code{gnus-article-wash-html}). Note that the this is
+usually done automatically by Gnus if the message in question has a
+@code{Content-Type} header that says that the message is HTML.
+
If a prefix is given, a charset will be asked for.
+@vindex gnus-article-wash-function
+The default is to use w3 to convert the HTML, but this is controlled
+by the @code{gnus-article-wash-function} variable. Pre-defined
+functions you can use include:
+
+@table @code
+@item gnus-article-wash-html-with-w3
+@findex gnus-article-wash-html-with-w3
+Use w3 (this is the default).
+
+@item gnus-article-wash-html-with-w3m
+@findex gnus-article-wash-html-with-w3m
+Use emacs-w3m (see @uref{http://emacs-w3m.namazu.org/} for more
+information).
+@end table
+
@item W b
@kindex W b (Summary)
@findex gnus-article-add-buttons
@kindex W s (Summary)
@findex gnus-summary-force-verify-and-decrypt
Verify a signed (PGP, PGP/MIME or S/MIME) message
-(@code{gnus-summary-force-verify-and-decrypt}).
+(@code{gnus-summary-force-verify-and-decrypt}). @xref{Security}.
@item W W H
@kindex W W H (Summary)
@section Security
Gnus is able to verify signed messages or decrypt encrypted messages.
-The formats that are supported are PGP (plain text, RFC 1991 format),
-PGP/MIME (RFC 2015/3156) and S/MIME, however you need some external
-programs to get things to work:
+The formats that are supported are PGP, PGP/MIME and S/MIME, however
+you need some external programs to get things to work:
@enumerate
@item
-To verify or decrypt PGP messages, you have to install mailcrypt or
-gpg.el as well as a OpenPGP implementation (such as GnuPG). @xref{Using GPG}.
+To handle PGP messages, you have to install mailcrypt or gpg.el as
+well as a OpenPGP implementation (such as GnuPG).
@item
-To verify or decrypt S/MIME message, you need to install OpenSSL.
-OpenSSL 0.9.6 or newer is recommended.
+To handle S/MIME message, you need to install OpenSSL. OpenSSL 0.9.6
+or newer is recommended.
@end enumerate
More information on how to set things up can be found in the message
-manual. @xref{Security, ,Security, message, The Message Manual}.
+manual (@pxref{Security, ,Security, message, Message Manual}).
@table @code
@item mm-verify-option
@item mm-decrypt-option
@vindex mm-decrypt-option
Option of decrypting encrypted parts. @code{never}, no decryption;
-@code{always}, always decrypt @code{known}, only decrypt known
+@code{always}, always decrypt; @code{known}, only decrypt known
protocols. Otherwise, ask user.
@end table
@table @code
@item gnus-treat-buttonize (t, integer)
@item gnus-treat-buttonize-head (head)
+
+@xref{Article Buttons}.
+
@item gnus-treat-capitalize-sentences (t, integer)
+@item gnus-treat-overstrike (t, integer)
+@item gnus-treat-strip-cr (t, integer)
+@item gnus-treat-strip-headers-in-body (t, integer)
+@item gnus-treat-strip-leading-blank-lines (t, integer)
+@item gnus-treat-strip-multiple-blank-lines (t, integer)
+@item gnus-treat-strip-pem (t, last, integer)
+@item gnus-treat-strip-pgp (t, last, integer)
+@item gnus-treat-strip-trailing-blank-lines (t, last, integer)
+@item gnus-treat-unsplit-urls (t, integer)
+
+@xref{Article Washing}.
+
@item gnus-treat-date-english (head)
@item gnus-treat-date-iso8601 (head)
@item gnus-treat-date-lapsed (head)
@item gnus-treat-date-original (head)
@item gnus-treat-date-user-defined (head)
@item gnus-treat-date-ut (head)
-@item gnus-treat-display-picons (head)
+
+@xref{Article Date}.
+
+@item gnus-treat-from-picon (head)
+@item gnus-treat-mail-picon (head)
+@item gnus-treat-newsgroups-picon (head)
+
+@xref{Picons}.
+
@item gnus-treat-display-smileys (t, integer)
+
+@item gnus-treat-body-boundary (head)
+
+@vindex gnus-body-boundary-delimiter
+Adds a delimiter between header and body, the string used as delimiter
+is controlled by @code{gnus-body-boundary-delimiter}.
+
+@xref{Smileys}.
+
@item gnus-treat-display-xface (head)
+
+@xref{X-Face}.
+
@item gnus-treat-emphasize (t, head, integer)
@item gnus-treat-fill-article (t, integer)
@item gnus-treat-fill-long-lines (t, integer)
@item gnus-treat-hide-citation-maybe (t, integer)
@item gnus-treat-hide-headers (head)
@item gnus-treat-hide-signature (t, last)
+
+@xref{Article Hiding}.
+
@item gnus-treat-highlight-citation (t, integer)
@item gnus-treat-highlight-headers (head)
@item gnus-treat-highlight-signature (t, last, integer)
-@item gnus-treat-overstrike (t, integer)
+
+@xref{Article Highlighting}.
+
@item gnus-treat-play-sounds
-@item gnus-treat-strip-cr (t, integer)
-@item gnus-treat-strip-headers-in-body (t, integer)
-@item gnus-treat-strip-leading-blank-lines (t, integer)
-@item gnus-treat-strip-multiple-blank-lines (t, integer)
-@item gnus-treat-strip-pem (t, last, integer)
-@item gnus-treat-strip-pgp (t, last, integer)
-@item gnus-treat-strip-trailing-blank-lines (t, last, integer)
@item gnus-treat-translate
@item gnus-treat-x-pgp-sig (head)
-@item gnus-treat-from-picon (head)
-@item gnus-treat-mail-picon (head)
-@item gnus-treat-newsgroups-picon (head)
+
@item gnus-treat-unfold-headers (head)
@item gnus-treat-fold-headers (head)
@item gnus-treat-fold-newsgroups (head)
-@item gnus-treat-body-boundary (head)
+
+
+
@end table
@vindex gnus-part-display-hook
@findex gnus-article-prev-button
Go to the previous button, if any (@code{gnus-article-prev-button}).
+@item R
+@kindex R (Article)
+@findex gnus-article-reply-with-original
+Send a reply to the current article and yank the current article
+(@code{gnus-article-reply-with-original}). If given a prefix, make a
+wide reply. If the region is active, only yank the text in the
+region.
+
+@item F
+@kindex F (Article)
+@findex gnus-article-followup-with-original
+Send a followup to the current article and yank the current article
+(@code{gnus-article-followup-with-original}). If given a prefix, make
+a wide reply. If the region is active, only yank the text in the
+region.
+
+
@end table
@cindex followup
@cindex post
@cindex using gpg
+@cindex using s/mime
+@cindex using smime
@kindex C-c C-c (Post)
All commands for posting and mailing will put you in a message buffer
where you can edit the article all you like, before you send the
-article by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The
+article by pressing @kbd{C-c C-c}. @xref{Top, , Overview, message,
Message Manual}. Where the message will be posted/mailed to depends
on your setup (@pxref{Posting Server}).
* Posting Styles:: An easier way to specify who you are.
* Drafts:: Postponing messages and rejected messages.
* Rejected Articles:: What happens if the server doesn't like your article?
-* Using GPG:: How to use GPG and MML to sign and encrypt messages
+* Signing and encrypting:: How to compose secure messages.
@end menu
Also see @pxref{Canceling and Superseding} for information on how to
This variable can be used instead of @code{gnus-message-archive-group},
but the latter is the preferred method.
-@item gnus-inews-mark-gcc-as-read
-@vindex gnus-inews-mark-gcc-as-read
+@item gnus-gcc-mark-as-read
+@vindex gnus-gcc-mark-as-read
If non-@code{nil}, automatically mark @code{Gcc} articles as read.
+@item gnus-gcc-externalize-attachments
+@vindex gnus-gcc-externalize-attachments
+If @code{nil}, attach files as normal parts in Gcc copies; if a regexp
+and matches the Gcc group name, attach files as external parts; if it is
+@code{all}, attach local files as external parts; if it is other
+non-@code{nil}, the behavior is the same as @code{all}, but it may be
+changed in the future.
+
@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 symbol @code{header}, then Gnus will look for header (the
-next element in the match) in the original article , and compare that to
-the last regexp in the match. If it's 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}.
-
-Each style may contain a arbitrary amount of @dfn{attributes}. Each
+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. If it's 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}.
+
+Each style may contain an arbitrary amount of @dfn{attributes}. Each
attribute consists of a @code{(@var{name} @var{value})} pair. The
attribute name can be one of @code{signature}, @code{signature-file},
-@code{organization}, @code{address}, @code{name} or @code{body}. The
-attribute name can also be a string. In that case, this will be used as
-a header name, and the value will be inserted in the headers of the
-article; if the value is @code{nil}, the header name will be removed.
-If the attribute name is @code{eval}, the form is evaluated, and the
-result is thrown away.
+@code{x-face-file}, @code{address} (overriding
+@code{user-mail-address}), @code{name} (overriding
+@code{(user-full-name)}) or @code{body}. The attribute name can also
+be a string or a symbol. In that case, this will be used as a header
+name, and the value will be inserted in the headers of the article; if
+the value is @code{nil}, the header name will be removed. If the
+attribute name is @code{eval}, the form is evaluated, and the result
+is thrown away.
The attribute value can be a string (used verbatim), a function with
zero arguments (the return value will be used), a variable (its value
will be used) or a list (it will be @code{eval}ed and the return value
will be used). The functions and sexps are called/@code{eval}ed in the
message buffer that is being set up. The headers of the current article
-are available through the @code{message-reply-headers} variable.
+are available through the @code{message-reply-headers} variable, which
+is a vector of the following headers: number subject from date id
+references chars lines xref extra.
+
+@vindex message-reply-headers
If you wish to check whether the message you are about to compose is
meant to be a news article or a mail message, you can check the values
(organization "People's Front Against MWM"))
("^rec.humor"
(signature my-funny-signature-randomizer))
- ((equal (system-name) "gnarly")
+ ((equal (system-name) "gnarly") ;; A form
(signature my-quote-randomizer))
- ((message-news-p)
+ (message-news-p ;; A function symbol
(signature my-news-signature))
- (header "to" "larsi.*org"
- (Organization "Somewhere, Inc."))
- ((posting-from-work-p)
+ (window-system ;; A value symbol
+ ("X-Window-System" (format "%s" window-system)))
+ ;; If I'm replying to Larsi, set the Organization header.
+ ((header "to" "larsi.*org")
+ (Organization "Somewhere, Inc."))
+ ((posting-from-work-p) ;; A user defined function
(signature-file "~/.work-signature")
(address "user@@bar.foo")
(body "You are fired.\n\nSincerely, your boss.")
(@pxref{Drafts}). When the server comes back up again, you'd then
typically enter that group and send all the articles off.
-@node Using GPG
-@section Using GPG
+@node Signing and encrypting
+@section Signing and encrypting
@cindex using gpg
+@cindex using s/mime
+@cindex using smime
-Gnus has an ALPHA support to GPG that's provided by @file{gpg.el}. See
-@code{mm-verify-option} and @code{mm-decrypt-option} to enable Gnus to
-verify or decrypt messages accordingly.
+Gnus can digitally sign and encrypt your messages, using vanilla PGP
+format or PGP/MIME or S/MIME. For decoding such messages, see the
+@code{mm-verify-option} and @code{mm-decrypt-option} options
+(@pxref{Security}).
-To use this correctly with GPG, you'll need the following lisp code in your
-@file{~/.emacs} or @file{~/.gnus}:
+For PGP, Gnus supports two external libraries, @sc{gpg.el} and
+@sc{Mailcrypt}, you need to install at least one of them. The S/MIME
+support in Gnus requires the external program OpenSSL.
-@lisp
-(require 'gpg)
-(setq mml2015-use 'gpg)
-(setq mml1991-use 'gpg)
-(setq gpg-temp-directory (expand-file-name "~/.gnupg/tmp"))
-@end lisp
+Instructing MML to perform security operations on a MIME part is done
+using the @code{C-c C-m s} key map for signing and the @code{C-c C-m
+c} key map for encryption, as follows.
+
+@table @kbd
+
+@item C-c C-m s s
+@kindex C-c C-m s s
+@findex mml-secure-sign-smime
+
+Digitally sign current MIME part using S/MIME.
+
+@item C-c C-m s o
+@kindex C-c C-m s o
+@findex mml-secure-sign-pgp
+
+Digitally sign current MIME part using PGP.
-The @code{gpg-temp-directory} need to point to a directory with permissions set
-to 700, for your own safety.
+@item C-c C-m s p
+@kindex C-c C-m s p
+@findex mml-secure-sign-pgp
-To sign or encrypt your message you may choose to use the MML Security
-menu or @kbd{C-c C-m s p} to sign your message using PGP/MIME,
-@kbd{C-c C-m s s} to sign your message using S/MIME. There's also
-@kbd{C-c C-m c p} to encrypt your message with PGP/MIME and @kbd{C-c
-C-m c s} to encrypt using S/MIME. @xref{Security, ,Security, message,
-The Message Manual}.
+Digitally sign current MIME part using PGP/MIME.
-Gnus will ask for your passphrase and then it will send your message, if
-you've typed it correctly.
+@item C-c C-m c s
+@kindex C-c C-m c s
+@findex mml-secure-encrypt-smime
+
+Digitally encrypt current MIME part using S/MIME.
+
+@item C-c C-m c o
+@kindex C-c C-m c o
+@findex mml-secure-encrypt-pgp
+
+Digitally encrypt current MIME part using PGP.
+
+@item C-c C-m c p
+@kindex C-c C-m c p
+@findex mml-secure-encrypt-pgpmime
+
+Digitally encrypt current MIME part using PGP/MIME.
+
+@end table
+
+Also @xref{Security, ,Security, message, Message Manual}.
@node Select Methods
@chapter Select Methods
file is first copied to your home directory. What happens after that
depends on what format you want to store your mail in.
-There are five different mail back ends in the standard Gnus, and more
+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 the fastest and most flexible) is @code{nnml}
-(@pxref{Mail Spool}).
+(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/}.
@menu
* Unix Mail Box:: Using the (quite) standard Un*x mbox.
to restore the group (after restoring the backup into the nnml
directory).
+If for some reason you believe your @file{.marks} files are screwed
+up, you can just delete them all. Gnus will then correctly regenerate
+them next time it starts.
+
Virtual server settings:
@table @code
@item nnml-marks-file-name
@vindex nnml-marks-file-name
-The name of the @sc{marks} files. The default is @file{.marks}.
+The name of the @dfn{marks} files. The default is @file{.marks}.
+
+@item nnml-use-compressed-files
+@vindex nnml-use-compressed-files
+If non-@code{nil}, @code{nnml} will allow using compressed message
+files.
@end table
only a moderate amount of mail, @code{nnfolder} is probably the most
friendly mail back end all over.
+@item nnmaildir
+
+@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}
+also stores the equivalent of @code{nnml}'s overview files in one file
+per article, so it uses about twice as many inodes as @code{nnml}. (Use
+@code{df -i} to see how plentiful your inode supply is.) If this slows
+you down or takes up very much space, consider switching to ReiserFS
+(@uref{http://www.namesys.com/}) or another non-block-structured
+filesystem.
+
+Since maildirs don't require locking for delivery, the maildirs you use
+as groups can also be the maildirs your mail is directly delivered to.
+This means you can skip Gnus's mail splitting if your mail is already
+organized into different mailboxes during delivery. A @code{directory}
+entry in @code{mail-sources} would have a similar effect, but would
+require one set of mailboxes for spooling deliveries (in mbox format,
+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{nnmaildir} stores article marks for a given group in the
+corresponding maildir, in a way designed so that it's easy to manipulate
+them from outside Gnus. You can tar up a maildir, unpack it somewhere
+else, and still have your marks. @code{nnml} also stores marks, but
+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 backends.
+
+@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 somthing small (0 would probably not work, but 1 probably
+would) to make it use less memory.
+
+Startup and shutdown are likely to be slower with @code{nnmaildir} than
+with other backends. Everything in between is likely to be faster,
+depending in part on your filesystem.
+
+@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo}
+to write an @code{nnmaildir}-derived backend.
+
@end table
specify the network address of the server.
@sc{imap} has two properties. First, @sc{imap} can do everything that
-POP can, it can hence be viewed as POP++. Secondly, @sc{imap} is a
+POP can, it can hence be viewed as a POP++. Secondly, @sc{imap} is a
mail storage protocol, similar to @sc{nntp} being a news storage
-protocol. (@sc{imap} offers more features than @sc{nntp} because news
-is more or less read-only whereas mail is read-write.)
+protocol -- however, @sc{imap} offers more features than @sc{nntp}
+because news is more or less read-only whereas mail is read-write.
-If you want to use @sc{imap} as POP++, use an imap entry in
-mail-sources. With this, Gnus will fetch mails from the @sc{imap}
-server and store them on the local disk. This is not the usage
-described in this section. @xref{Mail Sources}.
+If you want to use @sc{imap} as a POP++, use an imap entry in
+@code{mail-sources}. With this, Gnus will fetch mails from the
+@sc{imap} server and store them on the local disk. This is not the
+usage described in this section--@xref{Mail Sources}.
If you want to use @sc{imap} as a mail storage protocol, use an nnimap
-entry in gnus-secondary-select-methods. With this, Gnus will
+entry in @code{gnus-secondary-select-methods}. With this, Gnus will
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 this:
+might look something like the following. (Note that for SSL/TLS, you
+need external programs and libraries, see below.)
@lisp
(setq gnus-secondary-select-methods
(nnimap-stream ssl))))
@end lisp
-(Note that for SSL/TLS to work, you need the external library
-@samp{ssl.el}, see below.)
-
The following variables can be used to create a virtual @code{nnimap}
server:
@itemize @bullet
@item
-@dfn{gssapi:} Connect with GSSAPI (usually kerberos 5). Requires the
+@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the
@samp{imtest} program.
@item
-@dfn{kerberos4:} Connect with kerberos 4. Requires the @samp{imtest} program.
+@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
@itemize @bullet
@item
-@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Require
+@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires
external program @code{imtest}.
@item
-@dfn{kerberos4:} Kerberos authentication. Require external program
+@dfn{kerberos4:} Kerberos 4 authentication. Requires external program
@code{imtest}.
@item
-@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Require
+@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires
external library @code{digest-md5.el}.
@item
@dfn{cram-md5:} Encrypted username/password via CRAM-MD5.
@item standard-digest
The standard (RFC 1153) digest format.
+@item mime-digest
+A MIME digest of messages.
+
+@item lanl-gov-announce
+Announcement messages from LANL Gov Announce.
+
+@item rfc822-forward
+A message forwarded according to RFC822.
+
+@item outlook
+The Outlook mail box.
+
+@item oe-dbx
+The Outlook Express dbx mail box.
+
+@item exim-bounce
+A bounce message from the Exim MTA.
+
+@item forward
+A message forwarded according to informal rules.
+
+@item rfc934
+An RFC934-forwarded message.
+
+@item mailman
+A mailman digest.
+
+@item clari-briefs
+A digest of Clarinet brief news items.
+
@item slack-digest
Non-standard digest format---matches most things, but does it badly.
@end table
All marks in the virtual group will stick to the articles in the
component groups. So if you tick an article in a virtual group, the
-article will also be ticked in the component group from whence it came.
-(And vice versa---marks from the component groups will also be shown in
-the virtual group.)
+article will also be ticked in the component group from whence it
+came. (And vice versa---marks from the component groups will also be
+shown in the virtual group.). To create an empty virtual group, run
+@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer
+and edit the method regexp with @kbd{M-e}
+(@code{gnus-group-edit-group-method})
Here's an example @code{nnvirtual} method that collects all Andrea Dworkin
newsgroups into one, big, happy newsgroup:
@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups}
line from the article you respond to in these cases.
+@code{nnvirtual} groups do not inherit anything but articles and marks
+from component groups---group parameters, for instance, are not
+inherited.
@node Kibozed Groups
here.
@item
-Then, put the following magical incantation at the end of your
-@file{.gnus.el} file:
+Then, put the following magical incantation in your @file{.gnus.el}
+file:
@lisp
-(gnus-agentize)
+(setq gnus-agent t)
@end lisp
@end itemize
or you could append your predicate to the predefined
@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or
-wherever. (Note: this would have to be at a point *after*
-@code{gnus-agent} has been loaded via @code{(gnus-agentize)})
+wherever.
@lisp
+(require 'gnus-agent)
(setq gnus-category-predicate-alist
(append gnus-category-predicate-alist
'((old . my-article-old-p))))
* Server Agent Commands::
@end menu
-You can run a complete batch fetch from the command line with the
+You can run a complete batch command from the command line with the
following incantation:
-@cindex gnus-agent-batch-fetch
+@cindex gnus-agent-batch
@example
-$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch
+$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch
@end example
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.
+@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.
+
@vindex gnus-agent-expire-all
-if @code{gnus-agent-expire-all} is non-@code{nil}, this command will
+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.
+@findex gnus-agent-regenerate
+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.
@node Agent and IMAP
@subsection Agent and IMAP
@vindex gnus-agent-unplugged-hook
Hook run when disconnecting from the network.
+@item gnus-agent-fetched-hook
+@vindex gnus-agent-fetched-hook
+Hook run when after finishing fetching articles.
+
+@item gnus-agent-cache
+@vindex gnus-agent-cache
+Variable to control whether use the locally stored NOV and articles when
+plugged.
+
+@item gnus-agent-go-online
+@vindex gnus-agent-go-online
+If @code{gnus-agent-go-online} is @code{nil}, the Agent will never
+automatically switch offline servers into online status. If it is
+@code{ask}, the default, the Agent will ask if you wish to switch
+offline servers into online status when you re-connect. If it has any
+other value, all offline servers will be automatically switched into
+online status.
+
@end table
(setq gnus-secondary-select-methods '((nnml "")))
;;; Make Gnus into an offline newsreader.
-(gnus-agentize)
+;;; (gnus-agentize) ; The obsolete setting.
+(setq gnus-agent t)
@end lisp
That should be it, basically. Put that in your @file{~/.gnus.el} file,
may ask:
@table @dfn
-@item If I read an article while plugged, do they get entered into the
-Agent?
+@item If I read an article while plugged, do they get entered into the Agent?
-@strong{No.}
+@strong{No}.
-@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{Yes.}
+@strong{No}, unless @code{gnus-agent-cache} is `nil'.
@end table
In short, when Gnus is unplugged, it only looks into the locally stored
-articles; when it's plugged, it only talks to your ISP.
+articles; when it's plugged, it only talks to your ISP and also uses the
+locally stored articles.
@node Scoring
@item i
Score on the @code{Message-ID} header.
+@item e
+Score on an "extra" header, that is, one of those in gnus-extra-headers,
+if your NNTP server tracks additional header data in overviews.
+
@item f
Score on followups---this matches the author name, and adds scores to
the followups to this author. (Using this key leads to the creation of
@end table
@item
-The fourth and final key says whether this is a temporary (i.e., expiring)
-score entry, or a permanent (i.e., non-expiring) score entry, or whether
-it is to be done immediately, without adding to the score file.
+The fourth and usually final key says whether this is a temporary (i.e.,
+expiring) score entry, or a permanent (i.e., non-expiring) score entry,
+or whether it is to be done immediately, without adding to the score
+file.
@table @kbd
@item t
Immediately scoring.
@end table
+@item
+If you are scoring on `e' (extra) headers, you will then be prompted for
+the header name on which you wish to score. This must be a header named
+in gnus-extra-headers, and @samp{TAB} completion is available.
+
@end enumerate
So, let's say you want to increase the score on the current author with
@item gnus-update-score-entry-dates
@vindex gnus-update-score-entry-dates
-If this variable is non-@code{nil}, matching score entries will have
-their dates updated. (This is how Gnus controls expiry---all
-non-matching entries will become too old while matching entries will
-stay fresh and young.) However, if you set this variable to @code{nil},
-even matching entries will grow old and will have to face that oh-so
-grim reaper.
+If this variable is non-@code{nil}, temporary score entries that have
+been triggered (matched) will have their dates updated. (This is how Gnus
+controls expiry---all non-matched-entries will become too old while
+matched entries will stay fresh and young.) However, if you set this
+variable to @code{nil}, even matched entries will grow old and will
+have to face that oh-so grim reaper.
@item gnus-score-after-write-file-function
@vindex gnus-score-after-write-file-function
@code{string}, @code{exact}, and @code{word} types, which you can use
instead, if you feel like.
+@item Extra
+Just as for the standard string overview headers, if you are using
+gnus-extra-headers, you can score on these headers' values. In this
+case, there is a 5th element in the score entry, being the name of the
+header to be scored. The following entry is useful in your
+@file{all.SCORE} file in case of spam attacks from a single origin host,
+if your NNTP server tracks NNTP-Posting-Host in overviews:
+
+@lisp
+("111.222.333.444" -1000 nil s "NNTP-Posting-Host")
+@end lisp
+
@item Lines, Chars
These two headers use different match types: @code{<}, @code{>},
@code{=}, @code{>=} and @code{<=}.
@item form
Use the specified form as the field value when the @samp{@@} spec is
used.
+
+Here's an example:
+
+@lisp
+"~(form (current-time-string))@@"
+@end lisp
+
@end table
Let's take an example. The @samp{%o} spec in the summary mode lines
@subsection X-Face
@cindex x-face
-@code{X-Face} headers describe a 48x48 pixel black-and-white image
-that's supposed to represent the author of the message. It seems to
-be supported by an ever-growing number of mail and news readers.
+@code{X-Face} headers describe a 48x48 pixel black-and-white (1 bit
+depth) image that's supposed to represent the author of the message.
+It seems to be supported by an ever-growing number of mail and news
+readers.
@cindex x-face
@findex gnus-article-display-x-face
(NOTE: @code{x-face} is used in the variable/function names, not
@code{xface}).
+Gnus provides a few convenience functions and variables to allow
+easier insertion of X-Face headers in outgoing messages.
+
+@findex gnus-random-x-face
+@code{gnus-random-x-face} goes through all the @samp{pbm} files
+in @code{gnus-x-face-directory} and picks one at random, and then
+converts it to the X-Face format by using the
+@code{gnus-convert-pbm-to-x-face-command} shell command. The
+@samp{pbm} files should be 48x48 pixels big.
+
+@code{gnus-x-face-from-file} takes a file as the parameter, and then
+converts the file to X-Face format by using the
+@code{gnus-convert-image-to-x-face-command} shell command.
+
+Here's how you would typically use the former function. Put something
+like the folllowing in your @file{.gnus.el} file:
+
+@lisp
+(setq message-required-news-headers
+ (nconc message-required-news-headers
+ (list '(X-Face . gnus-random-x-face))))
+@end lisp
+
+Using the latter function would be something like this:
+
+@lisp
+(setq message-required-news-headers
+ (nconc message-required-news-headers
+ (list '(X-Face . (lambda ()
+ (gnus-x-face-from-file
+ "~/My-face.gif"))))))
+@end lisp
+
@node Toolbar
@subsection Toolbar
@menu
* XEmacs:: Requirements for installing under XEmacs.
* History:: How Gnus got where it is today.
-* The Manual::
* On Writing Manuals:: Why this is not a beginner's guide.
* Terminology:: We use really difficult, like, words here.
* Customization:: Tailoring Gnus to your needs.
* Troubleshooting:: What you might try if things do not work.
* Gnus Reference Guide:: Rilly, rilly technical stuff.
* Emacs for Heathens:: A short introduction to Emacsian terms.
+* Frequently Asked Questions::
@end menu
@table @strong
-@item RFC 822
+@item RFC (2)822
@cindex RFC 822
+@cindex RFC 2822
There are no known breaches of this standard.
@item RFC 1036
various changes to the format of news articles. The Gnus towers will
look into implementing the changes when the draft is accepted as an RFC.
+@item MIME - RFC 2045-2049 etc
+@cindex MIME
+All the various MIME RFCs are supported.
+
+@item Disposition Notifications - RFC 2298
+Message Mode is able to request notifications from the receiver.
+
+@item PGP - RFC 1991 and RFC 2440
+@cindex RFC 1991
+@cindex RFC 2440
+RFC 1991 is the original PGP message specification, published as a
+Information RFC. RFC 2440 was the follow-up, now called Open PGP, and
+put on the Standards Track. Both document a non-MIME aware PGP
+format. Gnus supports both encoding (signing and encryption) and
+decoding (verification and decryption).
+
+@item PGP/MIME - RFC 2015/3156
+RFC 2015 (superceded by 3156 which references RFC 2440 instead of RFC
+1991) describes the MIME-wrapping around the RF 1991/2440 format.
+Gnus supports both encoding and decoding.
+
+@item S/MIME - RFC 2633
+RFC 2633 describes the S/MIME format.
+
+@item IMAP - RFC 1730/2060, RFC 2195, RFC 2086, RFC 2359, RFC 2595, RFC 1731
+RFC 1730 is IMAP version 4, updated somewhat by RFC 2060 (IMAP 4
+revision 1). RFC 2195 describes CRAM-MD5 authentication for IMAP. RFC
+2086 describes access control lists (ACLs) for IMAP. RFC 2359
+describes a IMAP protocol enhancement. RFC 2595 describes the proper
+TLS integration (STARTTLS) with IMAP. RFC 1731 describes the
+GSSAPI/Kerberos4 mechanisms for IMAP.
+
@end table
If you ever notice Gnus acting non-compliant with regards to the texts
If this is non-@code{nil}, all threads in the summary buffer will be
hidden initially.
-This can also be a predicate specifier (@pxref{Predicate Specifiers}).
-Avaliable predicates are @code{gnus-article-unread-p} and
-@code{gnus-article-unseen-p}).
-
-Here's an example:
-
-@lisp
-(setq gnus-thread-hide-subtree
- '(or gnus-article-unread-p
- gnus-article-unseen-p))
-@end lisp
-
-(It's a pretty nonsensical example, since all unseen articles are also
-unread, but you get my drift.)
-
@item gnus-updated-mode-lines
If this is @code{nil}, Gnus will not put information in the buffer mode
projects / gnus / blobdiff