@setfilename ../../info/gnus.info
@settitle Gnus Manual
+@include docstyle.texi
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex pg cp
-@documentencoding UTF-8
-
@copying
-Copyright @copyright{} 1995--2015 Free Software Foundation, Inc.
+Copyright @copyright{} 1995--2016 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email.
* Spam Package:: A package for filtering and processing spam.
* The Gnus Registry:: A package for tracking messages by Message-ID.
+* The Gnus Cloud:: A package for synchronizing Gnus marks.
* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
@item
@vindex gnus-ignored-from-addresses
-The @code{gnus-ignored-from-addresses} variable says when the @samp{%f}
-summary line spec returns the @code{To}, @code{Newsreader} or
-@code{From} header. If this regexp matches the contents of the
-@code{From} header, the value of the @code{To} or @code{Newsreader}
-headers are used instead.
+The @code{gnus-ignored-from-addresses} variable says when the
+@samp{%f} summary line spec returns the @code{To}, @code{Newsreader}
+or @code{From} header. The variable may be a regexp or a predicate
+function. If this matches the contents of the @code{From}
+header, the value of the @code{To} or @code{Newsreader} headers are
+used instead.
To distinguish regular articles from those where the @code{From} field
has been swapped, a string is prefixed to the @code{To} or
Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}).
Quoted-Printable is one common @acronym{MIME} encoding employed when
sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically
-makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu},
+makes strings like @samp{déjà vu} look like @samp{d=E9j=E0 vu},
which doesn't look very readable to me. Note that this is usually
done automatically by Gnus if the message in question has a
@code{Content-Transfer-Encoding} header that says that this encoding
article. That's well and nice, but there's also lots of information
most people do not want to see---what systems the article has passed
through before reaching you, the @code{Message-ID}, the
-@code{References}, etc. ad nauseam---and you'll probably want to get rid
+@code{References}, etc.@: ad nauseam---and you'll probably want to get rid
of some of those lines. If you want to keep all those lines in the
article buffer, you can set @code{gnus-show-all-headers} to @code{t}.
@item gnus-blocked-images
@vindex gnus-blocked-images
External images that have @acronym{URL}s that match this regexp won't
-be fetched and displayed. For instance, do block all @acronym{URL}s
+be fetched and displayed. For instance, to block all @acronym{URL}s
that have the string ``ads'' in them, do the following:
@lisp
this, and Emacs supports it, then the images will be rescaled down to
fit these criteria.
+@item gnus-article-show-cursor
+@vindex gnus-article-show-cursor
+If non-@code{nil}, display the cursor in the article buffer even when
+the article buffer isn't the current buffer.
@end table
To use this, make sure that you have @code{w3m} and @code{curl}
@ifinfo
@c Avoid sort of redundant entries in the same section for the printed
-@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or
-@c `i foo-bar'.
+@c manual, but add them in info to allow 'i gnus-treat-foo-bar RET' or
+@c 'i foo-bar'.
@vindex gnus-treat-buttonize
@vindex gnus-treat-buttonize-head
@vindex gnus-treat-capitalize-sentences
send. The default method is to use the @dfn{archive virtual server} to
store the messages. If you want to disable this completely, the
@code{gnus-message-archive-group} variable should be @code{nil}. The
-default is "sent.%Y-%m", which gives you one archive group per month.
+default is @code{"sent.%Y-%m"}, which gives you one archive group per month.
For archiving interesting messages in a group you read, see the
@kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail
* Connecting to an IMAP Server:: Getting started with @acronym{IMAP}.
* Customizing the IMAP Connection:: Variables for @acronym{IMAP} connection.
* Client-Side IMAP Splitting:: Put mail in the correct mail box.
+* Support for IMAP Extensions:: Getting extensions and labels from servers.
@end menu
can use this option, and customize @code{nnimap-shell-program} to be
what you need.
+@item plain
+Non-encrypted and unsafe straight socket connection.
+@acronym{STARTTLS} will not be used even if it is available.
+
@end table
@item nnimap-authenticator
@example
(nnimap "imap.example.com"
(nnimap-inbox "INBOX")
- (nnimap-split-methods
+ (nnimap-split-fancy
(| ("MailScanner-SpamCheck" "spam" "spam.detected")
(to "foo@@bar.com" "foo")
"undecided")))
@end example
+@node Support for IMAP Extensions
+@subsection Support for IMAP Extensions
+
+@cindex Gmail
+@cindex X-GM-LABELS
+@cindex IMAP labels
+
+If you're using Google's Gmail, you may want to see your Gmail labels
+when reading your mail. Gnus can give you this information if you ask
+for @samp{X-GM-LABELS} in the variable @code{gnus-extra-headers}. For
+example:
+
+@example
+(setq gnus-extra-headers
+ '(To Newsgroups X-GM-LABELS))
+@end example
+
+This will result in Gnus storing your labels in message header
+structures for later use. The content is always a parenthesized
+(possible empty) list.
+
+
+
@node Getting Mail
@section Getting Mail
@cindex reading mail
@samp{cram-md5}, @samp{anonymous} or the default @samp{login}.
@item :program
-When using the `shell' :stream, the contents of this variable is
+When using the @samp{shell} :stream, the contents of this variable is
mapped into the @code{imap-shell-program} variable. This should be a
@code{format}-like string (or list of strings). Here's an example:
@item :mailbox
The name of the mailbox to get mail from. The default is @samp{INBOX}
-which normally is the mailbox which receives incoming mail.
+which normally is the mailbox which receives incoming mail. Instead of
+a single mailbox, this can be a list of mailboxes to fetch mail from.
@item :predicate
The predicate used to find articles to fetch. The default, @samp{UNSEEN
If the search engine changes its output substantially, @code{nnweb}
won't be able to parse it and will fail. One could hardly fault the Web
-providers if they were to do this---their @emph{raison d'@^etre} is to
+providers if they were to do this---their @emph{raison d'être} is to
make money off of advertisements, not to provide services to the
community. Since @code{nnweb} washes the ads off all the articles, one
might think that the providers might be somewhat miffed. We'll see.
(gnus-summary-mark-as-read-forward 1))
(gnus-summary-scroll-up arg))))
-(eval-after-load "gnus"
- #'(define-key gnus-summary-mode-map
- (kbd "<RET>") 'browse-nnrss-url))
+(with-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
@lisp
;; @r{Set the default value of @code{mm-discouraged-alternatives}.}
-(eval-after-load "gnus-sum"
- '(add-to-list
- 'gnus-newsgroup-variables
- '(mm-discouraged-alternatives
- . '("text/html" "image/.*"))))
+(with-eval-after-load "gnus-sum"
+ (add-to-list
+ 'gnus-newsgroup-variables
+ '(mm-discouraged-alternatives
+ . '("text/html" "image/.*"))))
;; @r{Display @samp{text/html} parts in @code{nnrss} groups.}
(add-to-list
@item
You forget all about it and keep on getting and reading new mail, as usual.
@item
-From time to time, as you type `g' in the group buffer and as the date
+From time to time, as you type @kbd{g} in the group buffer and as the date
is getting closer, the message will pop up again to remind you of your
appointment, just as if it were new and unread.
@item
@end table
@item
-If you are scoring on `e' (extra) headers, you will then be prompted for
+If you are scoring on @samp{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.
To work correctly the @code{nnir-namazu-remove-prefix} variable must
also be correct. This is the prefix to remove from each file name
-returned by Namazu in order to get a proper group name (albeit with `/'
-instead of `.').
+returned by Namazu in order to get a proper group name (albeit with @samp{/}
+instead of @samp{.}).
For example, suppose that Namazu returns file names such as
@samp{/home/john/Mail/mail/misc/42}. For this example, use the
Extra switches may be passed to the namazu search command by setting the
variable @code{nnir-namazu-additional-switches}. It is particularly
important not to pass any any switches to namazu that will change the
-output format. Good switches to use include `--sort', `--ascending',
-`--early' and `--late'. Refer to the Namazu documentation for further
+output format. Good switches to use include @option{--sort},
+@option{--ascending}, @option{--early} and @option{--late}.
+Refer to the Namazu documentation for further
information on valid switches.
-Mail must first be indexed with the `mknmz' program. Read the documentation
-for namazu to create a configuration file. Here is an example:
+Mail must first be indexed with the @command{mknmz} program. Read the
+documentation for namazu to create a configuration file. Here is an
+example:
@cartouche
@example
package conf; # Don't remove this line!
- # Paths which will not be indexed. Don't use `^' or `$' anchors.
+ # Paths which will not be indexed. Don't use '^' or '$' anchors.
$EXCLUDE_PATH = "spam|sent";
# Header fields which should be searchable. case-insensitive
@item nnir-summary-line-format
The format specification to be used for lines in an nnir summary buffer.
-All the items from `gnus-summary-line-format' are available, along with
+All the items from @code{gnus-summary-line-format} are available, along with
three items unique to nnir summary buffers:
@example
@item nnir-retrieve-headers-override-function
If non-@code{nil}, a function that retrieves article headers rather than using
the gnus built-in function. This function takes an article list and
-group as arguments and populates the `nntp-server-buffer' with the
+group as arguments and populates the @code{nntp-server-buffer} with the
retrieved headers. It should then return either 'nov or 'headers
indicating the retrieved header format. Failure to retrieve headers
should return @code{nil}.
* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email.
* Spam Package:: A package for filtering and processing spam.
* The Gnus Registry:: A package for tracking messages by Message-ID.
+* The Gnus Cloud:: A package for synchronizing Gnus marks.
* Other modes:: Interaction with other modes.
* Various Various:: Things that are really various.
@end menu
The registry can store custom flags and keywords for a message. For
instance, you can mark a message ``To-Do'' this way and the flag will
persist whether the message is in the nnimap, nnml, nnmaildir,
-etc. backends.
+etc.@: backends.
@item
Store arbitrary data
@code{gnus-registry-max-entries}. This option controls exactly how
much less: the target is calculated as the maximum number of entries
minus the maximum number times this factor. The default is 0.1:
-i.e. if your registry is limited to 50000 entries, pruning will try to
+i.e., if your registry is limited to 50000 entries, pruning will try to
cut back to 45000 entries. Entries with keys marked as precious will
not be pruned.
@end defvar
@lisp
;; show the marks as single characters (see the :char property in
-;; `gnus-registry-marks'):
+;; 'gnus-registry-marks'):
;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-chars)
-;; show the marks by name (see `gnus-registry-marks'):
+;; show the marks by name (see 'gnus-registry-marks'):
;; (defalias 'gnus-user-format-function-M 'gnus-registry-article-marks-to-names)
@end lisp
precious.
@end defvar
+@node The Gnus Cloud
+@section The Gnus Cloud
+@cindex cloud
+@cindex gnus-cloud
+@cindex synchronization
+@cindex sync
+@cindex synch
+
+The Gnus Cloud is a way to synchronize marks and general files and
+data across multiple machines.
+
+Very often, you want all your marks (what articles you've read, which
+ones were important, and so on) to be synchronized between several
+machines. With IMAP, that's built into the protocol, so you can read
+nnimap groups from many machines and they are automatically
+synchronized. But NNTP, nnrss, and many other backends do not store
+marks, so you have to do it locally.
+
+The Gnus Cloud package stores the marks, plus any files you choose, on
+an IMAP server in a special folder. It's like a
+DropTorrentSyncBoxOakTree(TM).
+
+@menu
+* Gnus Cloud Setup::
+* Gnus Cloud Usage::
+@end menu
+
+@node Gnus Cloud Setup
+@subsection Gnus Cloud Setup
+
+Setting up the Gnus Cloud takes less than a minute. From the Group
+buffer:
+
+Press @kbd{^} to go to the Server buffer. Here you'll see all the
+servers that Gnus knows. @xref{Server Buffer}.
+
+Then press @kbd{i} to mark any servers as cloud-synchronized (their marks are synchronized).
+
+Then press @kbd{I} to mark a single server as the cloud host (it must
+be an IMAP server, and will host a special IMAP folder with all the
+synchronization data). This will set the variable
+@code{gnus-cloud-method} (using the Customize facilities), then ask
+you to optionally upload your first CloudSynchronizationDataPack(TM).
+
+@node Gnus Cloud Usage
+@subsection Gnus Cloud Usage
+
+After setting up, you can use these shortcuts from the Group buffer:
+
+@table @kbd
+@item ~ RET
+@item ~ d
+@findex gnus-cloud-download-all-data
+@cindex cloud, download
+Download the latest Gnus Cloud data.
+
+@item ~ u
+@item ~ ~
+@findex gnus-cloud-upload-all-data
+@cindex cloud, download
+Upload the local Gnus Cloud data. Creates a new
+CloudSynchronizationDataPack(TM).
+
+@end table
+
+But wait, there's more. Of course there's more. So much more. You can
+customize all of the following.
+
+@defvar gnus-cloud-synced-files
+These are the files that will be part of every
+CloudSynchronizationDataPack(TM). They are included in every upload,
+so don't synchronize a lot of large files. Files under 100Kb are best.
+@end defvar
+
+@defvar gnus-cloud-storage-method
+This is a choice from several storage methods. It's highly recommended
+to use the EPG facilities. It will be automatic if have GnuPG
+installed and EPG loaded. Otherwise, you could use Base64+gzip,
+Base64, or no encoding.
+@end defvar
+
+@defvar gnus-cloud-interactive
+When this is set, and by default it is, the Gnus Cloud package will
+ask you for confirmation here and there. Leave it on until you're
+comfortable with the package.
+@end defvar
+
+
+@defvar gnus-cloud-method
+The name of the IMAP server to store the
+CloudSynchronizationDataPack(TM)s. It's easiest to set this from the
+Server buffer (@pxref{Gnus Cloud Setup}).
+@end defvar
+
@node Other modes
@section Interaction with other modes
Kevin Davidson---came up with the name @dfn{ding}, so blame him.
@item
-Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as
+François Pinard---many, many interesting and thorough bug reports, as
well as autoconf support.
@end itemize
Richard Hoskins,
Brad Howes,
Miguel de Icaza,
-Fran@,{c}ois Felix Ingrand,
+François Felix Ingrand,
Tatsuya Ichikawa, @c Ichikawa
Ishikawa Ichiro, @c Ishikawa
Lee Iverson,
directory is not used any more. You can safely delete the entire
hierarchy.
-@c FIXME: `gnus-load' is mentioned in README, which is not included in
+@c FIXME: 'gnus-load' is mentioned in README, which is not included in
@c the repository. We should find a better place for this item.
@item
@code{(require 'gnus-load)}