\thispagestyle{empty}
-Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000
+Copyright \copyright{} 1995, 1996, 1997, 1998, 1999, 2000
Free Software Foundation, Inc.
Getting Mail
-* Mail in a Newsreader:: Important introductory notes.
+* Mail in a Newsreader:: Important introductory notes.
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail:: How to create mail groups.
* Mail Sources:: How to tell Gnus where to get mail from.
@item gnus-subscribe-topics
@vindex gnus-subscribe-topics
-Put the groups into the topic that has a matching @code{subscribe} topic
+Put the groups into the topic that has a matching @code{subscribe} topic
parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe}
topic parameter that looks like
"nnslashdot"
@end example
-will mean that all groups that match that regex will be subscribed under
+will mean that all groups that match that regex will be subscribed under
that topic.
If no topics match the groups, the groups will be subscribed in the
Estimated total number of articles. (This is really @var{max-number}
minus @var{min-number} plus 1.)
+Gnus uses this estimation because the NNTP protocol provides efficient
+access to @var{max-number} and @var{min-number} but getting the true
+unread message count is not possible efficiently. For hysterical
+raisins, even the mail backends, where the true number of unread
+messages might be available efficiently, use the same limited
+interface. To remove this restriction from Gnus means that the
+backend interface has to be changed, which is not an easy job. If you
+want to work on this, please contact the Gnus mailing list.
+
@item y
Number of unread, unticked, non-dormant articles.
silly Lisp errors.) You might also be interested in reading about topic
parameters (@pxref{Topic Parameters}).
+Group parameters can be set in @code{gnus-parameters} too. But some
+variables, such as @code{visible}, have no effect. For example,
+
+@example
+(setq gnus-parameters
+ '(("mail\\..*" (gnus-show-threads nil)
+ (gnus-use-scoring nil)
+ (gnus-summary-line-format
+ "%U%R%z%I%(%[%d:%ub%-20,20f%]%) %s\n")
+ (gcc-self . t)
+ (display . all))
+ ("mail\\.me" (gnus-use-scoring t))
+ ("list\\..*" (total-expire . t)
+ (broken-reply-to . t)))
+@end example
@node Listing Groups
@section Listing Groups
@table @code
@item subscribe
-When subscribing new groups by topic (@pxref{Subscription Methods}), the
-@code{subscribe} topic parameter says what groups go in what topic. Its
+When subscribing new groups by topic (@pxref{Subscription Methods}), the
+@code{subscribe} topic parameter says what groups go in what topic. Its
value should be a regexp to match the groups that should go in that
-topic.
+topic.
@end table
@item gnus-group-name-charset-group-alist
@vindex gnus-group-name-charset-group-alist
-An alist of regexp of group name and the charset for group names.
+An alist of regexp of group name and the charset for group names.
It is used to show non-ASCII group names.
For example:
(@pxref{Formatting Variables}).
There should always be a colon on the line; the cursor always moves to
-the colon after performing an operation.
+the colon after performing an operation.
The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}.
encoded in the @code{cn-gb-2312} charset. If you have
@lisp
-(setq gnus-summary-show-article-charset-alist
- '((1 . cn-gb-2312)
+(setq gnus-summary-show-article-charset-alist
+ '((1 . cn-gb-2312)
(2 . big5)))
@end lisp
@item M H
@kindex M H (Summary)
@findex gnus-summary-catchup-to-here
-Catchup the current group to point
+Catchup the current group to point (before the point)
(@code{gnus-summary-catchup-to-here}).
+@item M h
+@kindex M h (Summary)
+@findex gnus-summary-catchup-from-here
+Catchup the current group from point (after the point)
+(@code{gnus-summary-catchup-from-here}).
+
@item C-w
@kindex C-w (Summary)
@findex gnus-summary-mark-region-as-read
(@code{gnus-summary-save-article-vm}).
@item O p
+@itemx |
@kindex O p (Summary)
+@kindex | (Summary)
@findex gnus-summary-pipe-output
Save the current article in a pipe. Uhm, like, what I mean is---Pipe
the current article to a process (@code{gnus-summary-pipe-output}).
@lisp
(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy
-(setq gnus-default-article-saver 'gnus-summary-save-in-file) ; no encoding
+(setq gnus-default-article-saver
+ 'gnus-summary-save-in-file) ; no encoding
@end lisp
Then just save with @kbd{o}. You'd then read this hierarchy with
@item W Q
@kindex W Q (Summary)
-@findex gnus-article-fill-long-lines
+@findex gnus-article-fill-long-lines
Fill long lines (@code{gnus-article-fill-long-lines}).
@item W C
automatically by Gnus if the message in question has a
@code{Content-Transfer-Encoding} header that says that this encoding has
been done.
+If a prefix is given, a charset will be asked for.
@item W Z
@kindex W Z (Summary)
@item W h
@kindex W h (Summary)
@findex gnus-article-wash-html
-Treat HTML (@code{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.
+If a prefix is given, a charset will be asked for.
@item W f
@kindex W f (Summary)
@kindex W p (Summary)
@findex gnus-article-verify-x-pgp-sig
Verify a signed control message (@code{gnus-article-verify-x-pgp-sig}).
-Control messages such as @code{newgroup} and @code{checkgroups} are
-usually signed by the hierarchy maintainer. You need to add the PGP
+Control messages such as @code{newgroup} and @code{checkgroups} are
+usually signed by the hierarchy maintainer. You need to add the PGP
public key of the maintainer to your keyring to verify the
message.@footnote{PGP keys for many hierarchies are available at
@uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}}
(@code{gnus-article-date-lapsed}). It looks something like:
@example
-X-Sent: 9 years, 6 weeks, 4 days, 9 hours, 3 minutes, 28 seconds ago
+X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago
@end example
The value of @code{gnus-article-date-lapsed-new-header} determines
@item gnus-mime-multipart-functions
Alist of @sc{mime} multipart types and functions to handle them.
+@vindex mm-file-name-rewrite-functions
+@item mm-file-name-rewrite-functions
+List of functions used for rewriting file names of @sc{mime} parts.
+Each function takes a file name as input and returns a file name.
+
+Ready-made functions include@*
+@code{mm-file-name-delete-whitespace},
+@code{mm-file-name-trim-whitespace},
+@code{mm-file-name-collapse-whitespace}, and
+@code{mm-file-name-replace-whitespace}. The later uses the value of
+the variable @code{mm-file-name-replace-whitespace} to replace each
+whitespace character in a file name with that string; default value
+is @code{"_"} (a single underscore).
+@findex mm-file-name-delete-whitespace
+@findex mm-file-name-trim-whitespace
+@findex mm-file-name-collapse-whitespace
+@findex mm-file-name-replace-whitespace
+@vindex mm-file-name-replace-whitespace
+
+The standard functions @code{capitalize}, @code{downcase},
+@code{upcase}, and @code{upcase-initials} may be useful, too.
+
+Everybody knows that whitespace characters in file names are evil,
+except those who don't know. If you receive lots of attachments from
+such unenlightened users, you can make live easier by adding
+
+@lisp
+(setq mm-file-name-rewrite-functions
+ '(mm-file-name-trim-whitespace
+ mm-file-name-collapse-whitespace
+ mm-file-name-replace-whitespace))
+@end lisp
+
+@noindent
+to your @file{.gnus} file.
+
@end table
@vindex gnus-preserve-marks
Move the article from one mail group to another
(@code{gnus-summary-move-article}). Marks will be preserved if
-@var{gnus-preserve-marks} is non-@code{nil} (which is the default).
+@var{gnus-preserve-marks} is non-@code{nil} (which is the default).
@item B c
@kindex B c (Summary)
@item M-s
@kindex M-s (Summary)
@findex gnus-summary-search-article-forward
-Search through all subsequent articles for a regexp
+Search through all subsequent (raw) articles for a regexp
(@code{gnus-summary-search-article-forward}).
@item M-r
@kindex M-r (Summary)
@findex gnus-summary-search-article-backward
-Search through all previous articles for a regexp
+Search through all previous (raw) articles for a regexp
(@code{gnus-summary-search-article-backward}).
@item &
encrypted messages.
@enumerate
-@item
+@item
To verify or decrypt PGP messages, you have to install mailcrypt or
gpg.el.
@code{gnus-part-display-hook}. The functions are called narrowed to the
part, and you can do anything you like, pretty much. There is no
information that you have to keep in the buffer---you can change
-everything.
+everything.
@node Article Keymap
Now, if you've done this, and then this server rejects your article, or
this server is down, what do you do then? To override this variable you
can use a non-zero prefix to the @kbd{C-c C-c} command to force using
-the ``current'' server, to get back the default behaviour, for posting.
+the ``current'' server, to get back the default behavior, for posting.
If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command,
gnus will prompt you for what method to use for posting.
@lisp
(nntp "firewall"
- (nntp-address "the.firewall.machine")
- (nntp-open-connection-function nntp-open-rlogin)
- (nntp-end-of-line "\n")
- (nntp-rlogin-parameters
- ("telnet" "the.real.nntp.host" "nntp")))
+ (nntp-open-connection-function nntp-open-via-rlogin-and-telnet)
+ (nntp-via-address "the.firewall.machine")
+ (nntp-address "the.real.nntp.host")
+ (nntp-end-of-line "\n"))
@end lisp
If you want to use the wonderful @code{ssh} program to provide a
-compressed connection over the modem line, you could create a virtual
-server that would look something like this:
+compressed connection over the modem line, you could add the following
+configuration to the example above:
+
+@lisp
+ (nntp-via-rlogin-command "ssh")
+@end lisp
+
+If you're behind a firewall, but have direct access to the outside world
+through a wrapper command like "runsocks", you could open a socksified
+telnet connection to the news server as follows:
@lisp
-(nntp "news"
- (nntp-address "copper.uio.no")
- (nntp-rlogin-program "ssh")
- (nntp-open-connection-function nntp-open-rlogin)
- (nntp-end-of-line "\n")
- (nntp-rlogin-parameters
- ("telnet" "news.uio.no" "nntp")))
+(nntp "outside"
+ (nntp-pre-command "runsocks")
+ (nntp-open-connection-function nntp-open-via-telnet)
+ (nntp-address "the.news.server")
+ (nntp-end-of-line "\n"))
@end lisp
This means that you have to have set up @code{ssh-agent} correctly to
The file contains one or more line, each of which define one server.
@item
-Each line may contain an arbitrary number of token/value pairs.
+Each line may contain an arbitrary number of token/value pairs.
The valid tokens include @samp{machine}, @samp{login}, @samp{password},
@samp{default}. In addition Gnus introduces two new tokens, not present
@lisp
'(("nntpd 1\\.5\\.11t"
- (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader)))
+ (remove-hook 'nntp-server-opened-hook
+ 'nntp-send-mode-reader)))
@end lisp
This ensures that Gnus doesn't send the @code{MODE READER} command to
This hook is run as the last step when connecting to an @sc{nntp}
server.
-@findex nntp-open-rlogin
-@findex nntp-open-telnet
-@findex nntp-open-network-stream
-@item nntp-open-connection-function
-@vindex nntp-open-connection-function
-This function is used to connect to the remote system. Four pre-made
-functions are supplied:
-
-@table @code
-@item nntp-open-network-stream
-This is the default, and simply connects to some port or other on the
-remote system.
-
-@item nntp-open-rlogin
-Does an @samp{rlogin} on the
-remote system, and then does a @samp{telnet} to the @sc{nntp} server
-available there.
-
-@code{nntp-open-rlogin}-related variables:
-
-@table @code
-
-@item nntp-rlogin-program
-@vindex nntp-rlogin-program
-Program used to log in on remote machines. The default is @samp{rsh},
-but @samp{ssh} is a popular alternative.
-
-@item nntp-rlogin-parameters
-@vindex nntp-rlogin-parameters
-This list will be used as the parameter list given to @code{rsh}.
-
-@item nntp-rlogin-user-name
-@vindex nntp-rlogin-user-name
-User name on the remote system.
-
-@end table
-
-@item nntp-open-telnet
-Does a @samp{telnet} to the remote system and then another @samp{telnet}
-to get to the @sc{nntp} server.
-
-@code{nntp-open-telnet}-related variables:
-
-@table @code
-@item nntp-telnet-command
-@vindex nntp-telnet-command
-Command used to start @code{telnet}.
-
-@item nntp-telnet-switches
-@vindex nntp-telnet-switches
-List of strings to be used as the switches to the @code{telnet} command.
-
-@item nntp-telnet-user-name
-@vindex nntp-telnet-user-name
-User name for log in on the remote system.
-
-@item nntp-telnet-passwd
-@vindex nntp-telnet-passwd
-Password to use when logging in.
-
-@item nntp-telnet-parameters
-@vindex nntp-telnet-parameters
-A list of strings executed as a command after logging in
-via @code{telnet}.
-
-@item nntp-telnet-shell-prompt
-@vindex nntp-telnet-shell-prompt
-Regexp matching the shell prompt on the remote machine. The default is
-@samp{bash\\|\$ *\r?$\\|> *\r?}.
-
-@item nntp-open-telnet-envuser
-@vindex nntp-open-telnet-envuser
-If non-@code{nil}, the @code{telnet} session (client and server both)
-will support the @code{ENVIRON} option and not prompt for login name.
-This works for Solaris @code{telnet}, for instance.
-
-@end table
+@item nntp-buggy-select
+@vindex nntp-buggy-select
+Set this to non-@code{nil} if your select routine is buggy.
-@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 SSLay 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
-define a server as follows:
+@item nntp-nov-is-evil
+@vindex nntp-nov-is-evil
+If the @sc{nntp} server does not support @sc{nov}, you could set this
+variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov}
+can be used.
-@lisp
-;; Type `C-c C-c' after you've finished editing.
-;;
-;; "snews" is port 563 and is predefined in our /etc/services
-;;
-(nntp "snews.bar.com"
- (nntp-open-connection-function nntp-open-ssl-stream)
- (nntp-port-number "snews")
- (nntp-address "snews.bar.com"))
-@end lisp
+@item nntp-xover-commands
+@vindex nntp-xover-commands
+@cindex nov
+@cindex XOVER
+List of strings used as commands to fetch @sc{nov} lines from a
+server. The default value of this variable is @code{("XOVER"
+"XOVERVIEW")}.
-@end table
+@item nntp-nov-gap
+@vindex nntp-nov-gap
+@code{nntp} normally sends just one big request for @sc{nov} lines to
+the server. The server responds with one huge list of lines. However,
+if you have read articles 2-5000 in the group, and only want to read
+article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
+lines that you will not need. This variable says how
+big a gap between two consecutive articles is allowed to be before the
+@code{XOVER} request is split into several request. Note that if your
+network is fast, setting this variable to a really small number means
+that fetching will probably be slower. If this variable is @code{nil},
+@code{nntp} will never split requests. The default is 5.
-@item nntp-end-of-line
-@vindex nntp-end-of-line
-String to use as end-of-line marker when talking to the @sc{nntp}
-server. This is @samp{\r\n} by default, but should be @samp{\n} when
-using @code{rlogin} to talk to the server.
+@item nntp-prepare-server-hook
+@vindex nntp-prepare-server-hook
+A hook run before attempting to connect to an @sc{nntp} server.
-@item nntp-rlogin-user-name
-@vindex nntp-rlogin-user-name
-User name on the remote system when using the @code{rlogin} connect
-function.
+@item nntp-warn-about-losing-connection
+@vindex nntp-warn-about-losing-connection
+If this variable is non-@code{nil}, some noise will be made when a
+server closes connection.
-@item nntp-address
-@vindex nntp-address
-The address of the remote system running the @sc{nntp} server.
+@item nntp-record-commands
+@vindex nntp-record-commands
+If non-@code{nil}, @code{nntp} will log all commands it sends to the
+@sc{nntp} server (along with a timestamp) in the @samp{*nntp-log*}
+buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection
+that doesn't seem to work.
-@item nntp-port-number
-@vindex nntp-port-number
-Port number to connect to when using the @code{nntp-open-network-stream}
-connect function.
+@item nntp-open-connection-function
+@vindex nntp-open-connection-function
+It is possible to customize how the connection to the nntp server will
+be opened. If you specify an @code{nntp-open-connection-function}
+parameter, Gnus will use that function to establish the connection.
+Five pre-made functions are supplied. These functions can be grouped in
+two categories: direct connection functions (three pre-made), and
+indirect ones (two pre-made).
@item nntp-list-options
@vindex nntp-list-options
'(nntp "news.somewhere.edu"
(nntp-options-not-subscribe "\\.binaries\\.")))
@end lisp
+@end table
-@item nntp-buggy-select
-@vindex nntp-buggy-select
-Set this to non-@code{nil} if your select routine is buggy.
+@menu
+* Direct Functions:: Connecting directly to the server.
+* Indirect Functions:: Connecting indirectly to the server.
+* Common Variables:: Understood by several connection functions.
+@end menu
-@item nntp-nov-is-evil
-@vindex nntp-nov-is-evil
-If the @sc{nntp} server does not support @sc{nov}, you could set this
-variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov}
-can be used.
-@item nntp-xover-commands
-@vindex nntp-xover-commands
-@cindex nov
-@cindex XOVER
-List of strings used as commands to fetch @sc{nov} lines from a
-server. The default value of this variable is @code{("XOVER"
-"XOVERVIEW")}.
+@node Direct Functions
+@subsubsection Direct Functions
+@cindex direct connection functions
-@item nntp-nov-gap
-@vindex nntp-nov-gap
-@code{nntp} normally sends just one big request for @sc{nov} lines to
-the server. The server responds with one huge list of lines. However,
-if you have read articles 2-5000 in the group, and only want to read
-article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov}
-lines that you will not need. This variable says how
-big a gap between two consecutive articles is allowed to be before the
-@code{XOVER} request is split into several request. Note that if your
-network is fast, setting this variable to a really small number means
-that fetching will probably be slower. If this variable is @code{nil},
-@code{nntp} will never split requests. The default is 5.
+These functions are called direct because they open a direct connection
+between your machine and the @sc{nntp} server. The behavior of these
+functions is also affected by commonly understood variables
+(@pxref{Common Variables}).
-@item nntp-prepare-server-hook
-@vindex nntp-prepare-server-hook
-A hook run before attempting to connect to an @sc{nntp} server.
+@table @code
+@findex nntp-open-network-stream
+@item nntp-open-network-stream
+This is the default, and simply connects to some port or other on the
+remote system.
-@item nntp-warn-about-losing-connection
-@vindex nntp-warn-about-losing-connection
-If this variable is non-@code{nil}, some noise will be made when a
-server closes connection.
+@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 SSLay 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
+define a server as follows:
-@item nntp-record-commands
-@vindex nntp-record-commands
-If non-@code{nil}, @code{nntp} will log all commands it sends to the
-@sc{nntp} server (along with a timestamp) in the @samp{*nntp-log*}
-buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection
-that doesn't seem to work.
+@lisp
+;; Type `C-c C-c' after you've finished editing.
+;;
+;; "snews" is port 563 and is predefined in our /etc/services
+;;
+(nntp "snews.bar.com"
+ (nntp-open-connection-function nntp-open-ssl-stream)
+ (nntp-port-number "snews")
+ (nntp-address "snews.bar.com"))
+@end lisp
+
+@findex nntp-open-telnet-stream
+@item nntp-open-telnet-stream
+Opens a connection to an @sc{nntp} server by simply @samp{telnet}'ing
+it. You might wonder why this function exists, since we have the
+default @code{nntp-open-network-stream} which would do the job. (One
+of) the reason(s) is that if you are behind a firewall but have direct
+connections to the outside world thanks to a command wrapper like
+@code{runsocks}, you can use it like this:
+
+@lisp
+(nntp "socksified"
+ (nntp-pre-command "runsocks")
+ (nntp-open-connection-function nntp-open-telnet-stream)
+ (nntp-address "the.news.server"))
+@end lisp
+
+With the default method, you would need to wrap your whole Emacs
+session, which is not a good idea.
+@end table
+
+
+@node Indirect Functions
+@subsubsection Indirect Functions
+@cindex indirect connection functions
+
+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
+things cleaner. The behavior of these functions is also affected by
+commonly understood variables (@pxref{Common Variables}).
+
+@table @code
+@item nntp-open-via-rlogin-and-telnet
+@findex nntp-open-via-rlogin-and-telnet
+Does an @samp{rlogin} on a remote system, and then does a @samp{telnet}
+to the real @sc{nntp} server from there. This is useful for instance if
+you need to connect to a firewall machine first.
+
+@code{nntp-open-via-rlogin-and-telnet}-specific variables:
+
+@table @code
+@item nntp-via-rlogin-command
+@vindex nntp-via-rlogin-command
+Command used to log in on the intermediate host. The default is
+@samp{rsh}, but @samp{ssh} is a popular alternative.
+@end table
+
+@item nntp-open-via-telnet-and-telnet
+@findex nntp-open-via-telnet-and-telnet
+Does essentially the same, but uses @samp{telnet} instead of
+@samp{rlogin} to connect to the intermediate host.
+
+@code{nntp-open-via-telnet-and-telnet}-specific variables:
+
+@table @code
+@item nntp-via-telnet-command
+@vindex nntp-via-telnet-command
+Command used to @code{telnet} the intermediate host. The default is
+@samp{telnet}.
+
+@item nntp-via-telnet-switches
+@vindex nntp-via-telnet-switches
+List of strings to be used as the switches to the
+@code{nntp-via-telnet-command} command. The default is @samp{("-8")}.
+
+@item nntp-via-user-password
+@vindex nntp-via-user-password
+Password to use when logging in on the intermediate host.
+
+@item nntp-via-envuser
+@vindex nntp-via-envuser
+If non-@code{nil}, the intermediate @code{telnet} session (client and
+server both) will support the @code{ENVIRON} option and not prompt for
+login name. This works for Solaris @code{telnet}, for instance.
+
+@item nntp-via-shell-prompt
+@vindex nntp-via-shell-prompt
+Regexp matching the shell prompt on the intermediate host. The default
+is @samp{bash\\|\$ *\r?$\\|> *\r?}.
+
+@end table
+
+@end table
+
+
+Here are some additional variables that are understood by all the above
+functions:
+
+@table @code
+
+@item nntp-via-user-name
+@vindex nntp-via-user-name
+User name to use when connecting to the intermediate host.
+
+@item nntp-via-address
+@vindex nntp-via-address
+Address of the intermediate host to connect to.
+
+@end table
+
+
+@node Common Variables
+@subsubsection Common Variables
+
+The following variables affect the behavior of all, or several of the
+pre-made connection functions. When not specified, all functions are
+affected.
+
+@table @code
+
+@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.
+
+@item nntp-address
+@vindex nntp-address
+The address of the @sc{nntp} server.
+
+@item nntp-port-number
+@vindex nntp-port-number
+Port number to connect to the @sc{nntp} server. The default is @samp{nntp}.
+
+@item nntp-end-of-line
+@vindex nntp-end-of-line
+String to use as end-of-line marker when talking to the @sc{nntp}
+server. This is @samp{\r\n} by default, but should be @samp{\n} when
+using a non native connection function.
+
+@item nntp-telnet-command
+@vindex nntp-telnet-command
+Command to use when connecting to the @sc{nntp} server through
+@samp{telnet}. This is NOT for an intermediate host. This is just for
+the real @sc{nntp} server. The default is @samp{telnet}.
+
+@item nntp-telnet-switches
+@vindex nntp-telnet-switches
+A list of switches to pass to @code{nntp-telnet-command}. The default
+is @samp{("-8")}.
@end table
course.
@menu
-* Mail in a Newsreader:: Important introductory notes.
+* Mail in a Newsreader:: Important introductory notes.
* Getting Started Reading Mail:: A simple cookbook example.
* Splitting Mail:: How to create mail groups.
* Mail Sources:: How to tell Gnus where to get mail from.
can use the @kbd{M-x nnmail-split-history} command. If you wish to see
where re-spooling messages would put the messages, you can use
@code{gnus-summary-respool-trace} and related commands (@pxref{Mail
-Group Commands}).
+Group Commands}).
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
(file)
@end lisp
-If the mail spool file is not located on the local machine, it's best to
-use POP or @sc{imap} or the like to fetch the mail. You can not use ange-ftp
+If the mail spool file is not located on the local machine, it's best to
+use POP or @sc{imap} or the like to fetch the mail. You can not use ange-ftp
file names here---it has no way to lock the mail spool while moving the
mail.
Two example maildir mail sources:
@lisp
-(maildir :path "/home/user-name/Maildir/" :subdirs ("cur" "new"))
+(maildir :path "/home/user-name/Maildir/"
+ :subdirs ("cur" "new"))
@end lisp
@lisp
-(maildir :path "/user@@remotehost.org:~/Maildir/" :subdirs ("new"))
+(maildir :path "/user@@remotehost.org:~/Maildir/"
+ :subdirs ("new"))
@end lisp
@item imap
An example @sc{imap} mail source:
@lisp
-(imap :server "mail.mycorp.com" :stream kerberos4 :fetchflag "\\Seen")
+(imap :server "mail.mycorp.com"
+ :stream kerberos4
+ :fetchflag "\\Seen")
@end lisp
@item webmail
An example webmail source:
@lisp
-(webmail :subtype 'hotmail :user "user-name" :password "secret")
+(webmail :subtype 'hotmail
+ :user "user-name"
+ :password "secret")
@end lisp
@end table
@lisp
(setq mail-sources
- '((directory :path "/home/pavel/.Spool/"
+ '((directory :path "/home/pavel/.Spool/"
:suffix ""
:plugged t)))
@end lisp
@node Incorporating Old Mail
@subsection Incorporating Old Mail
+@cindex incorporating old mail
+@cindex import old mail
Most people have lots of old mail stored in various file formats. If
you have set up Gnus to read mail using one of the spiffy Gnus mail
@lisp
(setq nnmail-split-fancy
'(| ;; Messages duplicates go to a separate group.
- ("gnus-warning" "duplication of message" "duplicate")
+ ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate")
;; Message from daemons, postmaster, and the like to another.
(any mail "mail.misc")
;; Other rules.
@item nnmbox-active-file
@vindex nnmbox-active-file
The name of the active file for the mail box. Default is
-@file{~/.mbox-active}.
+@file{~/.mbox-active}.
@item nnmbox-get-new-mail
@vindex nnmbox-get-new-mail
go through a cumbersome subscription procedure, and most people don't
even know what a news group is.
-The problem with this scenario is that web browsers are not very good at
-being newsreaders. They do not keep track of what articles you've read;
-they do not allow you to score on subjects you're interested in; they do
+The problem with this scenario is that web browsers are not very good at
+being newsreaders. They do not keep track of what articles you've read;
+they do not allow you to score on subjects you're interested in; they do
not allow off-line browsing; they require you to click around and drive
you mad in the end.
-So---if web browsers suck at reading discussion forums, why not use Gnus
+So---if web browsers suck at reading discussion forums, why not use Gnus
to do it instead?
Gnus has been getting a bit of a collection of backends for providing
All the web sources require Emacs/w3 and the url library to work.
The main caveat with all these web sources is that they probably won't
-work for a very long time. Gleaning information from the @sc{html} data
+work for a very long time. Gleaning information from the @sc{html} data
is guesswork at best, and when the layout is altered, the Gnus backend
will fail. If you have reasonably new versions of these backends,
though, you should be ok.
@item nnslashdot-directory
@vindex nnslashdot-directory
-Where @code{nnslashdot} will store its files. The default value is
+Where @code{nnslashdot} will store its files. The default is
@samp{~/News/slashdot/}.
@item nnslashdot-active-url
@vindex nnslashdot-active-url
-The @sc{url} format string that will be used to fetch the information on
+The @sc{url} format string that will be used to fetch the information on
news articles and comments. The default is
@samp{http://slashdot.org/search.pl?section=&min=%d}.
information Gnus needs to keep groups updated.
The easiest way to get started with @code{nnultimate} is to say
-something like the following in the group buffer: @kbd{B nnultimate RET
+something like the following in the group buffer: @kbd{B nnultimate RET
http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @sc{url}
(not including @samp{Ultimate.cgi} or the like at the end) for a forum
you're interested in; there's quite a list of them on the Ultimate web
@end table
+The following code may be helpful, if you want to show the description in
+the summary buffer.
+
+@lisp
+(add-to-list 'nnmail-extra-headers nnrss-description-field)
+(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n")
+
+(defun gnus-user-format-function-X (header)
+ (let ((descr
+ (assq nnrss-description-field (mail-header-extra header))))
+ (if descr (concat "\n\t" (cdr descr)) "")))
+@end lisp
+
+The following code may be useful to open an nnrss url directly from the
+summary buffer.
+@lisp
+(require 'browse-url)
+
+(defun browse-nnrss-url( arg )
+ (interactive "p")
+ (let ((url (assq nnrss-url-field
+ (mail-header-extra
+ (gnus-data-header
+ (assq (gnus-summary-article-number)
+ gnus-newsgroup-data))))))
+ (if url
+ (browse-url (cdr url))
+ (gnus-summary-scroll-up arg))))
+
+(eval-after-load "gnus"
+ #'(define-key gnus-summary-mode-map
+ (kbd "<RET>") 'browse-nnrss-url))
+(add-to-list 'nnmail-extra-headers nnrss-url-field)
+@end lisp
+
@node Customizing w3
@subsection Customizing w3
@cindex w3
@cindex url
@cindex Netscape
-Gnus uses the url library to fetch web pages and Emacs/w3 to display web
+Gnus uses the url library to fetch web pages and Emacs/w3 to display web
pages. Emacs/w3 is documented in its own manual, but there are some
things that may be more relevant for Gnus users.
For instance, a common question is how to make Emacs/w3 follow links
-using the @code{browse-url} functions (which will call some external web
+using the @code{browse-url} functions (which will call some external web
browser like Netscape). Here's one way:
@lisp
@lisp
(setq gnus-post-method
- '(nngateway "mail2news@@replay.com"
- (nngateway-header-transformation
- nngateway-mail2news-header-transformation)))
+ '(nngateway
+ "mail2news@@replay.com"
+ (nngateway-header-transformation
+ nngateway-mail2news-header-transformation)))
@end lisp
@end table
might look something like this:
@lisp
-(setq gnus-secondary-select-methods
+(setq gnus-secondary-select-methods
'((nnimap "simpleserver") ; no special configuration
; perhaps a ssh port forwarded server:
(nnimap "dolk"
@lisp
(nnimap "mail.server.com"
- (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
+ (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*"
("~friend/Mail/" . "list/*"))))
@end lisp
@itemize @bullet
@item
-@dfn{gssapi:} Connect with GSSAPI (usually kerberos 5). Require the
+@dfn{gssapi:} Connect with GSSAPI (usually kerberos 5). Requires the
@samp{imtest} program.
@item
-@dfn{kerberos4:} Connect with kerberos 4. Require 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). Require the external library @samp{starttls.el} and program
+SSL). Requires the external library @samp{starttls.el} and program
@samp{starttls}.
@item
-@dfn{ssl:} Connect through SSL. Require OpenSSL (the
+@dfn{ssl:} Connect through SSL. Requires OpenSSL (the
program @samp{openssl}) or SSLeay (@samp{s_client}).
@item
@dfn{shell:} Use a shell command to start @sc{imap} connection.
@end itemize
@vindex imap-kerberos4-program
-The @samp{imtest} program is shipped with Cyrus IMAPD, nnimap support
-both @samp{imtest} version 1.5.x and version 1.6.x. The variable
+The @samp{imtest} program is shipped with Cyrus IMAPD. If you're
+using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version
+1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type}
+to make @code{imap.el} use a pty instead of a pipe when communicating
+with @samp{imtest}. You will then suffer from a line length
+restrictions on IMAP commands, which might make Gnus seem to hang
+indefinitely if you have many articles in a mailbox. The variable
@code{imap-kerberos4-program} contain parameters to pass to the imtest
-program.
+program.
@vindex imap-ssl-program
For SSL connections, the OpenSSL program is available from
@end table
+@item nnimap-importantize-dormant
+@vindex nnimap-importantize-dormant
+
+If non-nil, marks dormant articles as ticked (as well), for other IMAP
+clients. Within Gnus, dormant articles will naturally still (only) be
+marked as ticked. This is to make dormant articles stand out, just
+like ticked articles, in other IMAP clients. (In other words, Gnus has
+two ``Tick'' marks and IMAP has only one.)
+
+Probably the only reason for frobing this would be if you're trying
+enable per-user persistant dormant flags, using something like:
+
+@lisp
+(setcdr (assq 'dormant nnimap-mark-to-flag-alist)
+ (format "gnus-dormant-%s" (user-login-name)))
+(setcdr (assq 'dormant nnimap-mark-to-predicate-alist)
+ (format "KEYWORD gnus-dormant-%s" (user-login-name)))
+@end lisp
+
+In this case, you would not want the per-user dormant flag showing up
+as ticked for other users.
+
+@item nnimap-expunge-search-string
+@cindex Expunging
+@vindex nnimap-expunge-search-string
+
+This variable contain the IMAP search command sent to server when
+searching for articles eligible for expiring. The default is
+@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by
+UID set and the second @code{%s} is replaced by a date.
+
+Probably the only useful value to change this to is
+@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in
+messages instead of the internal article date. See section 6.4.4 of
+RFC 2060 for more information on valid strings.
+
@item nnimap-authinfo-file
@vindex nnimap-authinfo-file
@lisp
(setq nnimap-split-rule
- '(("INBOX.nnimap" "^Sender: owner-nnimap@@vic20.globalcom.se")
+ '(("INBOX.nnimap"
+ "^Sender: owner-nnimap@@vic20.globalcom.se")
("INBOX.junk" "^Subject:.*MAKE MONEY")
("INBOX.private" "")))
@end lisp
@item f
Score on followups---this matches the author name, and adds scores to
-the followups to this author.
+the followups to this author. (Using this key leads to the creation of
+@file{ADAPT} files.)
@item b
Score on the body.
Score on the head.
@item t
-Score on thread.
+Score on thread. (Using this key leads to the creation of @file{ADAPT}
+files.)
@end table
For example, to do hierarchical scoring but use a non-server-specific
overall score file, you could use the value
@example
-(list (lambda (group) ("all.SCORE")) 'gnus-score-find-hierarchical)
+(list (lambda (group) ("all.SCORE"))
+ 'gnus-score-find-hierarchical)
@end example
@item gnus-score-expiry-days
If you want to lower the score of articles that have been crossposted to
more than, say, 3 groups:
@lisp
-("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r))
+("xref"
+ ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+"
+ -1000 nil r))
@end lisp
@item Matching on the body
or each score file directory. Gnus will decide by itself what score
files are applicable to which group.
-Say you want to use the score file
+To use the score file
@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and
-all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory:
+all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory,
+say this:
@lisp
(setq gnus-global-score-files
@end lisp
@findex gnus-score-search-global-directories
+@noindent
Simple, eh? Directory names must end with a @samp{/}. These
directories are typically scanned only once during each Gnus session.
If you feel the need to manually re-scan the remote directories, you can
may look like:
@example
-split = frame | horizontal | vertical | buffer | form
-frame = "(frame " size *split ")"
-horizontal = "(horizontal " size *split ")"
-vertical = "(vertical " size *split ")"
-buffer = "(" buffer-name " " size *[ "point" ] *[ "frame-focus"] ")"
-size = number | frame-params
-buffer-name = group | article | summary ...
+split = frame | horizontal | vertical | buffer | form
+frame = "(frame " size *split ")"
+horizontal = "(horizontal " size *split ")"
+vertical = "(vertical " size *split ")"
+buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")"
+size = number | frame-params
+buf-name = group | article | summary ...
@end example
The limitations are that the @code{frame} split can only appear as the
accomplish that, something like the following can be done:
@lisp
-(message (frame 1.0
- (if (not (buffer-live-p gnus-summary-buffer))
- (car (cdr (assoc 'group gnus-buffer-configuration)))
- (car (cdr (assoc 'summary gnus-buffer-configuration))))
- (vertical ((user-position . t) (top . 1) (left . 1)
- (name . "Message"))
- (message 1.0 point))))
+(message
+ (frame 1.0
+ (if (not (buffer-live-p gnus-summary-buffer))
+ (car (cdr (assoc 'group gnus-buffer-configuration)))
+ (car (cdr (assoc 'summary gnus-buffer-configuration))))
+ (vertical ((user-position . t) (top . 1) (left . 1)
+ (name . "Message"))
+ (message 1.0 point))))
@end lisp
@findex gnus-add-configuration
@subsection Example Window Configurations
@itemize @bullet
-@item
+@item
Narrow left hand side occupied by group buffer. Right hand side split
between summary buffer (top one-sixth) and article buffer (bottom).
@findex gnus-undo
The undoability is provided by the @code{gnus-undo-mode} minor mode. It
is used if @code{gnus-use-undo} is non-@code{nil}, which is the
-default. The @kbd{M-C-_} key performs the @code{gnus-undo}
+default. The @kbd{M-C-_} key performs the @code{gnus-undo}
command, which should feel kinda like the normal Emacs @code{undo}
command.
@subsubsection Pterodactyl Gnus
New features in Gnus 5.8:
-
+
@itemize @bullet
@item The mail-fetching functions have changed. See the manual for the
(setq nnmail-procmail-suffix "\\.in")
@end lisp
-this now has changed to
+this now has changed to
@lisp
(setq mail-sources
@item The Gnus posting styles have been redone again and now works in a
subtly different manner.
-@item New web-based backends have been added: @code{nnslashdot},
+@item New web-based backends have been added: @code{nnslashdot},
@code{nnwarchive} and @code{nnultimate}. nnweb has been revamped,
again, to keep up with ever-changing layouts.
that's already there. This is not how this manual is written. When
implementing something, I write the manual entry for that something
straight away. I then see that it's difficult to explain the
-functionality, so I write how it's supposed to be, and then I change the
+functionality, so I write how it's supposed to be, and then I change the
implementation. Writing the documentation and writing the code goes
hand in hand.
This, of course, means that this manual has no, or little, flow. It
documents absolutely everything in Gnus, but often not where you're
-looking for it. It is a reference manual, and not a guide to how to get
+looking for it. It is a reference manual, and not a guide to how to get
started with Gnus.
-That would be a totally different book, that should be written using the
+That would be a totally different book, that should be written using the
reference manual as source material. It would look quite differently.
"*Non-nil means that nndir will never retrieve NOV headers."
nnml-nov-is-evil)
-(defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
+(defvoo nndir-current-group ""
+ nil
+ nnml-current-group nnmh-current-group)
(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
(unless (assq 'nndir-directory defs)
(push `(nndir-directory ,server) defs))
(push `(nndir-current-group
- ,(file-name-nondirectory (directory-file-name nndir-directory)))
+ ,(file-name-nondirectory
+ (directory-file-name nndir-directory)))
defs)
(push `(nndir-top-directory
,(file-name-directory (directory-file-name nndir-directory)))
BNF definition of a score file:
@example
-score-file = "" / "(" *element ")"
-element = rule / atom
-rule = string-rule / number-rule / date-rule
-string-rule = "(" quote string-header quote space *string-match ")"
-number-rule = "(" quote number-header quote space *number-match ")"
-date-rule = "(" quote date-header quote space *date-match ")"
-quote = <ascii 34>
-string-header = "subject" / "from" / "references" / "message-id" /
- "xref" / "body" / "head" / "all" / "followup"
-number-header = "lines" / "chars"
-date-header = "date"
-string-match = "(" quote <string> quote [ "" / [ space score [ "" /
- space date [ "" / [ space string-match-t ] ] ] ] ] ")"
-score = "nil" / <integer>
-date = "nil" / <natural number>
-string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
- "r" / "regex" / "R" / "Regex" /
- "e" / "exact" / "E" / "Exact" /
- "f" / "fuzzy" / "F" / "Fuzzy"
-number-match = "(" <integer> [ "" / [ space score [ "" /
- space date [ "" / [ space number-match-t ] ] ] ] ] ")"
-number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
-date-match = "(" quote <string> quote [ "" / [ space score [ "" /
- space date [ "" / [ space date-match-t ] ] ] ] ")"
-date-match-t = "nil" / "at" / "before" / "after"
-atom = "(" [ required-atom / optional-atom ] ")"
-required-atom = mark / expunge / mark-and-expunge / files /
- exclude-files / read-only / touched
-optional-atom = adapt / local / eval
-mark = "mark" space nil-or-number
-nil-or-number = "nil" / <integer>
-expunge = "expunge" space nil-or-number
+score-file = "" / "(" *element ")"
+element = rule / atom
+rule = string-rule / number-rule / date-rule
+string-rule = "(" quote string-header quote space *string-match ")"
+number-rule = "(" quote number-header quote space *number-match ")"
+date-rule = "(" quote date-header quote space *date-match ")"
+quote = <ascii 34>
+string-header = "subject" / "from" / "references" / "message-id" /
+ "xref" / "body" / "head" / "all" / "followup"
+number-header = "lines" / "chars"
+date-header = "date"
+string-match = "(" quote <string> quote [ "" / [ space score [ "" /
+ space date [ "" / [ space string-match-t ] ] ] ] ] ")"
+score = "nil" / <integer>
+date = "nil" / <natural number>
+string-match-t = "nil" / "s" / "substring" / "S" / "Substring" /
+ "r" / "regex" / "R" / "Regex" /
+ "e" / "exact" / "E" / "Exact" /
+ "f" / "fuzzy" / "F" / "Fuzzy"
+number-match = "(" <integer> [ "" / [ space score [ "" /
+ space date [ "" / [ space number-match-t ] ] ] ] ] ")"
+number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<="
+date-match = "(" quote <string> quote [ "" / [ space score [ "" /
+ space date [ "" / [ space date-match-t ] ] ] ] ")"
+date-match-t = "nil" / "at" / "before" / "after"
+atom = "(" [ required-atom / optional-atom ] ")"
+required-atom = mark / expunge / mark-and-expunge / files /
+ exclude-files / read-only / touched
+optional-atom = adapt / local / eval
+mark = "mark" space nil-or-number
+nil-or-number = "nil" / <integer>
+expunge = "expunge" space nil-or-number
mark-and-expunge = "mark-and-expunge" space nil-or-number
-files = "files" *[ space <string> ]
-exclude-files = "exclude-files" *[ space <string> ]
-read-only = "read-only" [ space "nil" / space "t" ]
-adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ]
-adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
-local = "local" *[ space "(" <string> space <form> ")" ]
-eval = "eval" space <form>
-space = *[ " " / <TAB> / <NEWLINE> ]
+files = "files" *[ space <string> ]
+exclude-files = "exclude-files" *[ space <string> ]
+read-only = "read-only" [ space "nil" / space "t" ]
+adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ]
+adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")"
+local = "local" *[ space "(" <string> space <form> ")" ]
+eval = "eval" space <form>
+space = *[ " " / <TAB> / <NEWLINE> ]
@end example
Any unrecognized elements in a score file should be ignored, but not
@example
active = *group-line
-group-line = group space high-number space low-number space flag <NEWLINE>
+group-line = group spc high-number spc low-number spc flag <NEWLINE>
group = <non-white-space string>
-space = " "
+spc = " "
high-number = <non-negative integer>
low-number = <positive integer>
flag = "y" / "n" / "m" / "j" / "x" / "=" group
projects / elisp / gnus.git- / blobdiff