@documentencoding UTF-8
@copying
-Copyright @copyright{} 1995-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1995--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
\begin{document}
% Adjust ../Makefile.in if you change the following line:
-\newcommand{\gnusversionname}{Ma Gnus v0.6}
+\newcommand{\gnusversionname}{Ma Gnus v0.11}
\newcommand{\gnuschaptername}{}
\newcommand{\gnussectionname}{}
luck.
@c Adjust ../Makefile.in if you change the following line:
-This manual corresponds to Ma Gnus v0.6
+This manual corresponds to Ma Gnus v0.11
@ifnottex
@insertcopying
the program.
@c Adjust ../Makefile.in if you change the following line:
-This manual corresponds to Ma Gnus v0.6
+This manual corresponds to Ma Gnus v0.11
@heading Other related manuals
@itemize
* Index:: Variable, function and concept index.
* Key Index:: Key Index.
+@c Doesn't work right in html.
+@c FIXME Do this in a more standard way.
+@ifinfo
Other related manuals
* Message:(message). Composing messages.
* Sieve:(sieve). Managing Sieve scripts in Emacs.
* EasyPG:(epa). @acronym{PGP/MIME} with Gnus.
* SASL:(sasl). @acronym{SASL} authentication in Emacs.
+@end ifinfo
@detailmenu
--- The Detailed Node Listing ---
* Selecting a Group:: Actually reading news.
* Subscription Commands:: Unsubscribing, killing, subscribing.
* Group Data:: Changing the info for a group.
-* Group Levels:: Levels? What are those, then?
+* Group Levels:: Levels? What are those, then?
* Group Score:: A mechanism for finding out what groups you like.
* Marking Groups:: You can mark groups for later processing.
* Foreign Groups:: Creating and editing groups.
* Charsets:: Character set issues.
* Article Commands:: Doing various things with the article buffer.
* Summary Sorting:: Sorting the summary buffer in various ways.
-* Finding the Parent:: No child support? Get the parent.
+* Finding the Parent:: No child support? Get the parent.
* Alternative Approaches:: Reading using non-default summaries.
* Tree Display:: A more visual display of threads.
* Mail Group Commands:: Some commands can only be used in mail groups.
* Archiving Mail::
* Web Searches:: Creating groups from articles that match a string.
* RSS:: Reading RDF site summary.
-* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
Other Sources
@cindex finding news
First of all, you should know that there is a special buffer called
-@code{*Server*} that lists all the servers Gnus knows about. You can
+@file{*Server*} that lists all the servers Gnus knows about. You can
press @kbd{^} from the Group buffer to see it. In the Server buffer,
you can press @kbd{RET} on a defined server to see all the groups it
serves (subscribed or not!). You can also add or delete servers, edit
if you're in a hurry as well. This command will not attempt to contact
your primary server---instead, it will just activate all groups on level
1 and 2. (You should preferably keep no native groups on those two
-levels.) Also @pxref{Group Levels}.
+levels.) Also @pxref{Group Levels}.
@node Slave Gnusae
variable defaults to @code{gnus-subscribe-alphabetically}.
The ``options -n'' format is very simplistic. The syntax above is all
-that is supports -- you can force-subscribe hierarchies, or you can
+that is supports: you can force-subscribe hierarchies, or you can
deny hierarchies, and that's it.
@vindex gnus-options-not-subscribe
@vindex gnus-before-startup-hook
A hook called as the first thing when Gnus is started.
+@item gnus-before-resume-hook
+@vindex gnus-before-resume-hook
+A hook called as the first thing when Gnus is resumed after a suspend.
+
@item gnus-startup-hook
@vindex gnus-startup-hook
A hook run as the very last thing after starting up Gnus
* Selecting a Group:: Actually reading news.
* Subscription Commands:: Unsubscribing, killing, subscribing.
* Group Data:: Changing the info for a group.
-* Group Levels:: Levels? What are those, then?
+* Group Levels:: Levels? What are those, then?
* Group Score:: A mechanism for finding out what groups you like.
* Marking Groups:: You can mark groups for later processing.
* Foreign Groups:: Creating and editing groups.
You can change that format to whatever you want by fiddling with the
@code{gnus-group-line-format} variable. This variable works along the
lines of a @code{format} specification, which is pretty much the same as
-a @code{printf} specifications, for those of you who use (feh!) C.
+a @code{printf} specifications, for those of you who use (feh!) C@.
@xref{Formatting Variables}.
@samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above.
very old articles that will never be expired and the recent ones. In
such a case, the server will return the data like @code{(1 . 30000000)}
for the @code{LIST ACTIVE group} command, for example. Even if there
-are actually only the articles 1-10 and 29999900-30000000, Gnus doesn't
+are actually only the articles 1--10 and 29999900--30000000, Gnus doesn't
know it at first and prepares for getting 30000000 articles. However,
it will consume hundreds megabytes of memories and might make Emacs get
stuck as the case may be. If you use such news servers, set the
variable @code{gnus-newsgroup-maximum-articles} to a positive number.
The value means that Gnus ignores articles other than this number of the
latest ones in every group. For instance, the value 10000 makes Gnus
-get only the articles 29990001-30000000 (if the latest article number is
+get only the articles 29990001--30000000 (if the latest article number is
30000000 in a group). Note that setting this variable to a number might
prevent you from reading very old articles. The default value of the
variable @code{gnus-newsgroup-maximum-articles} is @code{nil}, which
unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead)
(default 8) and @code{gnus-level-killed} to be killed (completely dead)
(default 9). Gnus treats subscribed and unsubscribed groups exactly the
-same, but zombie and killed groups have no information on what articles
-you have read, etc, stored. This distinction between dead and living
+same, but zombie and killed groups store no information on what articles
+you have read, etc. This distinction between dead and living
groups isn't done because it is nice or clever, it is done purely for
reasons of efficiency.
It is recommended that you keep all your mail groups (if any) on quite
-low levels (e.g. 1 or 2).
+low levels (e.g., 1 or 2).
Maybe the following description of the default behavior of Gnus helps to
understand what these levels are all about. By default, Gnus shows you
use this level as the ``work'' level.
@vindex gnus-activate-level
-Gnus will normally just activate (i. e., query the server about) groups
+Gnus will normally just activate (i.e., query the server about) groups
on level @code{gnus-activate-level} or less. If you don't want to
activate unsubscribed groups, for instance, you might set this variable
to 5. The default is 6.
@kindex G R (Group)
@findex gnus-group-make-rss-group
Make a group based on an @acronym{RSS} feed
-(@code{gnus-group-make-rss-group}). You will be prompted for an URL.
+(@code{gnus-group-make-rss-group}). You will be prompted for an URL@.
@xref{RSS}.
@item G DEL
@findex gnus-read-ephemeral-gmane-group-url
This command is similar to @code{gnus-read-ephemeral-gmane-group}, but
the group name and the article number and range are constructed from a
-given @acronym{URL}. Supported @acronym{URL} formats include e.g.
-@url{http://thread.gmane.org/gmane.foo.bar/12300/focus=12399},
-@url{http://thread.gmane.org/gmane.foo.bar/12345/},
-@url{http://article.gmane.org/gmane.foo.bar/12345/},
-@url{http://permalink.gmane.org/gmane.foo.bar/12345/}, and
-@url{http://news.gmane.org/group/gmane.foo.bar/thread=12345}.
+given @acronym{URL}. Supported @acronym{URL} formats include:
+@indicateurl{http://thread.gmane.org/gmane.foo.bar/12300/focus=12399},
+@indicateurl{http://thread.gmane.org/gmane.foo.bar/12345/},
+@indicateurl{http://article.gmane.org/gmane.foo.bar/12345/},
+@indicateurl{http://permalink.gmane.org/gmane.foo.bar/12345/}, and
+@indicateurl{http://news.gmane.org/group/gmane.foo.bar/thread=12345}.
@item gnus-read-ephemeral-emacs-bug-group
@findex gnus-read-ephemeral-emacs-bug-group
that group will always be visible in the Group buffer, regardless
of whether it has any unread articles.
-This parameter cannot be set via @code{gnus-parameters}. See
+This parameter cannot be set via @code{gnus-parameters}. See
@code{gnus-permanently-visible-groups} as an alternative.
@item broken-reply-to
If you're using topics to organize your group buffer
(@pxref{Group Topics}), note that posting styles can also be set in
-the topics parameters. Posting styles in topic parameters apply to all
-groups in this topic. More precisely, the posting-style settings for a
+the topics parameters. Posting styles in topic parameters apply to all
+groups in this topic. More precisely, the posting-style settings for a
group result from the hierarchical merging of all posting-style
entries in the parameters of this group and all the topics it belongs
to.
@}
@end example
+You can also use regexp expansions in the rules:
+
+@example
+(sieve header :regex "list-id" "<c++std-\\1.accu.org>")
+@end example
+
See @pxref{Sieve Commands} for commands and variables that might be of
interest in relation to the sieve parameter.
@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
+the subject fields of articles. E.g., if the news group
@example
nntp+news.gnus.org:gmane.text.docbook.apps
@lisp
(gnus-summary-prepared-hook
- '(lambda nil (local-set-key "d" (local-key-binding "n"))))
+ (lambda nil (local-set-key "d" (local-key-binding "n"))))
@end lisp
when the group is entered, the 'd' key will not mark the article as
@findex gnus-browse-describe-briefly
Describe browse mode briefly (well, there's not much to describe, is
there) (@code{gnus-browse-describe-briefly}).
+
+@item DEL
+@kindex DEL (Browse)
+@findex gnus-browse-delete-group
+This function will delete the current group
+(@code{gnus-browse-delete-group}). If given a prefix, this function
+will actually delete all the articles in the group, and forcibly
+remove the group itself from the face of the Earth. Use a prefix only
+if you are absolutely sure of what you are doing.
@end table
@kbd{C-k} on it. This is like the ``cut'' part of cut and paste. Then,
move the cursor to the beginning of the buffer (just below the ``Gnus''
topic) and hit @kbd{C-y}. This is like the ``paste'' part of cut and
-paste. Like I said -- E-Z.
+paste. Like I said---E-Z.
You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics. So
you can move topics around as well as groups.
"")))
@end lisp
+To see what variables are dynamically bound (like
+@code{gnus-tmp-group}), you have to look at the source code. The
+variable names aren't guaranteed to be stable over Gnus versions,
+either.
+
@node File Commands
@subsection File Commands
* Charsets:: Character set issues.
* Article Commands:: Doing various things with the article buffer.
* Summary Sorting:: Sorting the summary buffer in various ways.
-* Finding the Parent:: No child support? Get the parent.
+* Finding the Parent:: No child support? Get the parent.
* Alternative Approaches:: Reading using non-default summaries.
* Tree Display:: A more visual display of threads.
* Mail Group Commands:: Some commands can only be used in mail groups.
to include extra headers when generating overview (@acronym{NOV}) files.
If you have old overview files, you should regenerate them after
changing this variable, by entering the server buffer using @kbd{^},
-and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause
+and then @kbd{g} on the appropriate mail server (e.g., nnml) to cause
regeneration.
@vindex gnus-summary-line-format
If you have just posted the article, and change your mind right away,
there is a trick you can use to cancel/supersede the article without
waiting for the article to appear on your site first. You simply return
-to the post buffer (which is called @code{*sent ...*}). There you will
+to the post buffer (which is called @file{*sent ...*}). There you will
find the article you just posted, with all the headers intact. Change
the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes}
header by substituting one of those words for the word
@node Generic Marking Commands
@subsection Generic Marking Commands
-Some people would like the command that ticks an article (@kbd{!}) go to
-the next article. Others would like it to go to the next unread
-article. Yet others would like it to stay on the current article. And
-even though I haven't heard of anybody wanting it to go to the
+Some people would like the command that ticks an article (@kbd{!}) to
+go to the next article. Others would like it to go to the next unread
+article. Yet others would like it to stay on the current article.
+And even though I haven't heard of anybody wanting it to go to the
previous (unread) article, I'm sure there are people that want that as
well.
using the default @code{gnus-thread-sort-by-number}, responses can end
up appearing before the article to which they are responding to.
Setting this variable to an alternate value
-(e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an
-appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a
+(e.g., @code{gnus-thread-sort-by-date}), in a group's parameters or in an
+appropriate hook (e.g., @code{gnus-summary-generate-hook}) can produce a
more logical sub-thread ordering in such instances.
@end table
gnus-thread-sort-by-score))
@end lisp
+By default, threads including their subthreads are sorted according to
+the value of @code{gnus-thread-sort-functions}. By customizing
+@code{gnus-subthread-sort-functions} you can define a custom sorting
+order for subthreads. This allows for example to sort threads from
+high score to low score in the summary buffer, but to have subthreads
+still sorted chronologically from old to new without taking their
+score into account.
+
@vindex gnus-thread-score-function
The function in the @code{gnus-thread-score-function} variable (default
@code{+}) is used for calculating the total score of a thread. Useful
@item gnus-summary-save-in-pipe
@findex gnus-summary-save-in-pipe
Pipe the article to a shell command. This function takes optional two
-arguments COMMAND and RAW. Valid values for COMMAND include:
+arguments COMMAND and RAW@. Valid values for COMMAND include:
@itemize @bullet
@item a string@*
So; there you are, reading your @emph{pseudo-articles} in your
@emph{virtual newsgroup} from the @emph{virtual server}; and you think:
-Why isn't anything real anymore? How did we get here?
+Why isn't anything real anymore? How did we get here?
@node Article Treatment
(Typically offensive jokes and such.)
It's commonly called ``rot13'' because each letter is rotated 13
-positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter
+positions in the alphabet, e.g., @samp{B} (letter #2) -> @samp{O} (letter
#15). It is sometimes referred to as ``Caesar rotate'' because Caesar
is rumored to have employed this form of, uh, somewhat weak encryption.
@acronym{ASCII} equivalents (@code{gnus-article-treat-non-ascii}).
This is mostly useful if you're on a terminal that has a limited font
and doesn't show accented characters, ``advanced'' punctuation, and the
-like. For instance, @samp{»} is translated into @samp{>>}, and so on.
+like. For instance, @samp{»} is translated into @samp{>>}, and so on.
@item W Y f
@kindex W Y f (Summary)
@item W c
@kindex W c (Summary)
@findex gnus-article-remove-cr
-Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF
+Translate CRLF pairs (i.e., @samp{^M}s on the end of the lines) into LF
(this takes care of DOS line endings), and then translate any remaining
CRs into LF (this takes care of Mac line endings)
(@code{gnus-article-remove-cr}).
@item gnus-w3m
Use Gnus rendered based on w3m.
-@item w3
-Use Emacs/W3.
-
@item w3m
Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}.
Date: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago
@end example
-This line is updated continually by default. The frequency (in
-seconds) is controlled by the @code{gnus-article-update-date-headers}
-variable.
-
-If you wish to switch updating off, say:
-
-@vindex gnus-article-update-date-headers
-@lisp
-(setq gnus-article-update-date-headers nil)
-@end lisp
-
-in your @file{~/.gnus.el} file.
+To make this line updated continually, set the
+@code{gnus-article-update-date-headers} variable to the frequency in
+seconds (the default is @code{nil}).
@item W T o
@kindex W T o (Summary)
be useful if you normally use some other conversion function and are
worried that it might be doing something totally wrong. Say, claiming
that the article was posted in 1854. Although something like that is
-@emph{totally} impossible. Don't you trust me? *titter*
+@emph{totally} impossible. Don't you trust me? *titter*
@end table
@item W D m
@kindex W D m (Summary)
@findex gnus-treat-mail-picon
-Piconify all mail headers (i. e., @code{Cc}, @code{To})
+Piconify all mail headers (i.e., @code{Cc}, @code{To})
(@code{gnus-treat-mail-picon}).
@item W D n
@kindex W D n (Summary)
@findex gnus-treat-newsgroups-picon
-Piconify all news headers (i. e., @code{Newsgroups} and
+Piconify all news headers (i.e., @code{Newsgroups} and
@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}).
@item W D g
@item W D h
@kindex W D h (Summary)
@findex gnus-treat-mail-gravatar
-Gravatarify all mail headers (i. e., @code{Cc}, @code{To})
+Gravatarify all mail headers (i.e., @code{Cc}, @code{To})
(@code{gnus-treat-from-gravatar}).
@item W D D
mostly useful if you wish to save (or perform other actions) on inlined
parts.
+@item W M h
+@kindex W M h (Summary)
+@findex gnus-mime-buttonize-attachments-in-header
+@vindex gnus-mime-display-attachment-buttons-in-header
+Display @acronym{MIME} part buttons in the end of the header of an
+article (@code{gnus-mime-buttonize-attachments-in-header}). This
+command toggles the display. Note that buttons to be added to the
+header are only the ones that aren't inlined in the body. If you want
+those buttons always to be displayed, set
+@code{gnus-mime-display-attachment-buttons-in-header} to non-@code{nil}.
+The default is @code{t}. To change the appearance of buttons, customize
+@code{gnus-header-face-alist}.
+
@item K m
@kindex K m (Summary)
@findex gnus-summary-repair-multipart
This variable is only used when @code{gnus-inhibit-mime-unbuttonizing}
is @code{nil}.
-To see e.g. security buttons but no other buttons, you could set this
+E.g., to see security buttons but no other buttons, you could set this
variable to @code{("multipart/signed")} and leave
@code{gnus-unbuttonized-mime-types} at the default value.
@vindex gnus-article-mime-part-function
For each @acronym{MIME} part, this function will be called with the @acronym{MIME}
handle as the parameter. The function is meant to be used to allow
-users to gather information from the article (e. g., add Vcard info to
-the bbdb database) or to do actions based on parts (e. g., automatically
+users to gather information from the article (e.g., add Vcard info to
+the bbdb database) or to do actions based on parts (e.g., automatically
save all jpegs into some directory).
Here's an example function the does the latter:
If given a positive numerical prefix, fetch that many articles back into
the ancestry. If given a negative numerical prefix, fetch just that
ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the
-grandparent and the grandgrandparent of the current article. If you say
-@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current
+grandparent and the great-grandparent of the current article. If you say
+@kbd{-3 ^}, Gnus will only fetch the great-grandparent of the current
article.
@item A R (Summary)
faster. Of course, it'll make group entry somewhat slow.
@vindex gnus-refer-thread-limit
-The @code{gnus-refer-thread-limit} variable says how many old (i. e.,
+The @code{gnus-refer-thread-limit} variable says how many old (i.e.,
articles before the first displayed in the current group) headers to
fetch when doing this command. The default is 200. If @code{t}, all
the available headers will be fetched. This variable can be overridden
about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}.
If you do that, Gnus won't kill the summary buffer when you exit it.
(Quelle surprise!) Instead it will change the name of the buffer to
-something like @samp{*Dead Summary ... *} and install a minor mode
+something like @file{*Dead Summary ... *} and install a minor mode
called @code{gnus-dead-summary-mode}. Now, if you switch back to this
buffer, you'll find that all keys are mapped to a function called
@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead
@vindex gnus-use-cross-reference
The data on the current group will be updated (which articles you have
-read, which articles you have replied to, etc.) when you exit the
+read, which articles you have replied to, etc.)@: when you exit the
summary buffer. If the @code{gnus-use-cross-reference} variable is
@code{t} (which is the default), articles that are cross-referenced to
this group and are marked as read, will also be marked as read in the
@enumerate
@item
To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to
-install an OpenPGP implementation such as GnuPG. The Lisp interface
+install an OpenPGP implementation such as GnuPG@. The Lisp interface
to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG,
epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg,
PGG Manual}), and Mailcrypt are also supported.
@item
-To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6
+To handle @acronym{S/MIME} message, you need to install OpenSSL@. OpenSSL 0.9.6
or newer is recommended.
@end enumerate
@item gnus-html-frame-width
@vindex gnus-html-frame-width
-The width to use when rendering HTML. The default is 70.
+The width to use when rendering HTML@. The default is 70.
@item gnus-max-image-proportion
@vindex gnus-max-image-proportion
(typep "text/x-vcard"))
@end lisp
+@item
+A function: the function is called with no arguments and should return
+@code{nil} or non-@code{nil}. The current article is available in the
+buffer named by @code{gnus-article-buffer}.
+
@end enumerate
You may have noticed that the word @dfn{part} is used here. This refers
@item p
Displayed when article is digitally signed or encrypted, and Gnus has
hidden the security headers. (N.B. does not tell anything about
-security status, i.e. good or bad signature.)
+security status, i.e., good or bad signature.)
@item s
Displayed when the signature has been hidden in the Article buffer.
@xref{Mail Variables, ,Mail Variables,message,Message manual}, for more
information.
+
@node POP before SMTP
@section POP before SMTP
@cindex pop before smtp
-@findex message-smtpmail-send-it
@findex mail-source-touch-pop
-Does your @acronym{ISP} require the @acronym{POP}-before-@acronym{SMTP}
-authentication? It is whether you need to connect to the @acronym{POP}
-mail server within a certain time before sending mails. If so, there is
-a convenient way. To do that, put the following lines in your
-@file{~/.gnus.el} file:
+Does your @acronym{ISP} use @acronym{POP}-before-@acronym{SMTP}
+authentication? This authentication method simply requires you to
+contact the @acronym{POP} server before sending email. To do that,
+put the following lines in your @file{~/.gnus.el} file:
@lisp
-(setq message-send-mail-function 'message-smtpmail-send-it)
(add-hook 'message-send-mail-hook 'mail-source-touch-pop)
@end lisp
@noindent
-It means to let Gnus connect to the @acronym{POP} mail server in advance
-whenever you send a mail. The @code{mail-source-touch-pop} function
-does only a @acronym{POP} authentication according to the value of
-@code{mail-sources} without fetching mails, just before sending a mail.
-Note that you have to use @code{message-smtpmail-send-it} which runs
-@code{message-send-mail-hook} rather than @code{smtpmail-send-it} and
-set the value of @code{mail-sources} for a @acronym{POP} connection
-correctly. @xref{Mail Sources}.
+The @code{mail-source-touch-pop} function does @acronym{POP}
+authentication according to the value of @code{mail-sources} without
+fetching mails, just before sending a mail. @xref{Mail Sources}.
If you have two or more @acronym{POP} mail servers set in
@code{mail-sources}, you may want to specify one of them to
(mail-source-touch-pop))))
@end lisp
+
@node Mail and Post
@section Mail and Post
contains the message including the message header. Changes made to
the message will only affect the Gcc copy, but not the original
message. You can use these hooks to edit the copy (and influence
-subsequent transformations), e.g. remove MML secure tags
+subsequent transformations), e.g., remove MML secure tags
(@pxref{Signing and encrypting}).
@end table
A foreign group (or any group, really) is specified by a @dfn{name} and
a @dfn{select method}. To take the latter first, a select method is a
-list where the first element says what back end to use (e.g. @code{nntp},
+list where the first element says what back end to use (e.g., @code{nntp},
@code{nnspool}, @code{nnml}) and the second element is the @dfn{server
name}. There may be additional elements in the select method, where the
value may have special meaning for the back end in question.
@subsection Servers and Methods
Wherever you would normally use a select method
-(e.g. @code{gnus-secondary-select-method}, in the group select method,
+(e.g., @code{gnus-secondary-select-method}, in the group select method,
when browsing a foreign server) you can use a virtual server name
instead. This could potentially save lots of typing. And it's nice all
over.
@vindex nntp-nov-gap
@code{nntp} normally sends just one big request for @acronym{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
+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 @acronym{NOV}
lines that you will not need. This variable says how
big a gap between two consecutive articles is allowed to be before the
@item nntp-record-commands
@vindex nntp-record-commands
If non-@code{nil}, @code{nntp} will log all commands it sends to the
-@acronym{NNTP} server (along with a timestamp) in the @samp{*nntp-log*}
+@acronym{NNTP} server (along with a timestamp) in the @file{*nntp-log*}
buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection
that doesn't seem to work.
(add-hook 'nntp-prepare-post-hook 'canlock-insert-header)
@end lisp
-Note that not all servers support the recommended ID. This works for
+Note that not all servers support the recommended ID@. This works for
INN versions 2.3.0 and later, for instance.
@item nntp-server-list-active-group
@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 @uref{http://www.openssl.org, OpenSSL} or
-@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} installed. You
-then define a server as follows:
+this you must have @uref{http://www.openssl.org, OpenSSL}
+@ignore
+@c Defunct URL, ancient package, so don't mention it.
+or @uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay}
+@end ignore
+installed. You then define a server as follows:
@lisp
;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}}
Port number to connect to the @acronym{NNTP} server. The default is
@samp{nntp}. If you use @acronym{NNTP} over
@acronym{TLS}/@acronym{SSL}, you may want to use integer ports rather
-than named ports (i.e, use @samp{563} instead of @samp{snews} or
+than named ports (i.e., use @samp{563} instead of @samp{snews} or
@samp{nntps}), because external @acronym{TLS}/@acronym{SSL} tools may
not work with named ports.
@item nnimap-authenticator
Some @acronym{IMAP} servers allow anonymous logins. In that case,
-this should be set to @code{anonymous}.
+this should be set to @code{anonymous}. If this variable isn't set,
+the normal login methods will be used. If you wish to specify a
+specific login method to be used, you can set this variable to either
+@code{login} (the traditional @acronym{IMAP} login method),
+@code{plain} or @code{cram-md5}.
@item nnimap-expunge
If non-@code{nil}, expunge articles after deleting them. This is always done
@cindex reading mail
@cindex mail
-Reading mail with a newsreader---isn't that just plain WeIrD? But of
+Reading mail with a newsreader---isn't that just plain WeIrD@? But of
course.
@menu
@menu
* Mail Source Specifiers:: How to specify what a mail source is.
+* Mail Source Functions::
* Mail Source Customization:: Some variables that influence things.
* Fetching Mail:: Using the mail source specifiers.
@end menu
@env{MAILHOST} environment variable.
@item :port
-The port number of the @acronym{POP} server. This can be a number (eg,
-@samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a
+The port number of the @acronym{POP} server. This can be a number (e.g.,
+@samp{:port 1234}) or a string (e.g., @samp{:port "pop3"}). If it is a
string, it should be a service name as listed in @file{/etc/services} on
Unix systems. The default is @samp{"pop3"}. On some systems you might
need to specify it as @samp{"pop-3"} instead.
and says what authentication scheme to use. The default is
@code{password}.
+@item :leave
+Non-@code{nil} if the mail is to be left on the @acronym{POP} server
+after fetching. Only the built-in @code{pop3-movemail} program (the
+default) supports this keyword.
+
+If this is a number, leave mails on the server for this many days since
+you first checked new mails. In that case, mails once fetched will
+never be fetched again by the @acronym{UIDL} control. If this is
+@code{nil} (the default), mails will be deleted on the server right
+after fetching. If this is neither @code{nil} nor a number, all mails
+will be left on the server, and you will end up getting the same mails
+again and again.
+
+@vindex pop3-uidl-file
+The @code{pop3-uidl-file} variable specifies the file to which the
+@acronym{UIDL} data are locally stored. The default value is
+@file{~/.pop3-uidl}.
+
+Note that @acronym{POP} servers maintain no state information between
+sessions, so what the client believes is there and what is actually
+there may not match up. If they do not, then you may get duplicate
+mails or the whole thing can fall apart and leave you with a corrupt
+mailbox.
+
@end table
-@vindex pop3-movemail
+@findex pop3-movemail
@vindex pop3-leave-mail-on-server
If the @code{:program} and @code{:function} keywords aren't specified,
-@code{pop3-movemail} will be used. If @code{pop3-leave-mail-on-server}
-is non-@code{nil} the mail is to be left on the @acronym{POP} server
-after fetching when using @code{pop3-movemail}. Note that POP servers
-maintain no state information between sessions, so what the client
-believes is there and what is actually there may not match up. If they
-do not, then you may get duplicate mails or the whole thing can fall
-apart and leave you with a corrupt mailbox.
+@code{pop3-movemail} will be used.
Here are some examples for getting mail from a @acronym{POP} server.
+
Fetch from the default @acronym{POP} server, using the default user
name, and default fetcher:
:user "user-name" :password "secret")
@end lisp
+Leave mails on the server for 14 days:
+
+@lisp
+(pop :server "my.pop.server"
+ :user "user-name" :password "secret"
+ :leave 14)
+@end lisp
+
Use @samp{movemail} to move the mail:
@lisp
@item imap
Get mail from a @acronym{IMAP} server. If you don't want to use
-@acronym{IMAP} as intended, as a network mail reading protocol (ie
+@acronym{IMAP} as intended, as a network mail reading protocol (i.e.,
with nnimap), for some reason or other, Gnus let you treat it similar
to a @acronym{POP} server and fetches articles from a given
@acronym{IMAP} mailbox. @xref{Using IMAP}, for more information.
@end table
@end table
+@node Mail Source Functions
@subsubsection Function Interface
Some of the above keywords specify a Lisp function to be executed.
In this example, messages sent to @samp{debian-foo@@lists.debian.org}
will be filed in @samp{mail.debian.foo}.
-If the string contains the element @samp{\&}, then the previously
+If the string contains the element @samp{\\&}, then the previously
matched string will be substituted. Similarly, the elements @samp{\\1}
up to @samp{\\9} will be substituted with the text matched by the
groupings 1 through 9.
lowercase of the matched string should be used for the substitution.
Setting it as non-@code{nil} is useful to avoid the creation of multiple
groups when users send to an address using different case
-(i.e. mailing-list@@domain vs Mailing-List@@Domain). The default value
+(i.e., mailing-list@@domain vs Mailing-List@@Domain). The default value
is @code{t}.
@findex nnmail-split-fancy-with-parent
@c @findex nnmail-fix-eudora-headers
@cindex Eudora
@cindex Pegasus
-Some mail user agents (e.g. Eudora and Pegasus) produce broken
+Some mail user agents (e.g., Eudora and Pegasus) produce broken
@code{References} headers, but correct @code{In-Reply-To} headers. This
function will get rid of the @code{References} header if the headers
contain a line matching the regular expression
If you are a member of a couple of mailing lists, you will sometimes
receive two copies of the same mail. This can be quite annoying, so
@code{nnmail} checks for and treats any duplicates it might find. To do
-this, it keeps a cache of old @code{Message-ID}s---
+this, it keeps a cache of old @code{Message-ID}s:
@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by
default. The approximate maximum number of @code{Message-ID}s stored
there is controlled by the @code{nnmail-message-id-cache-length}
variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be
-stored.) If all this sounds scary to you, you can set
+stored.) If all this sounds scary to you, you can set
@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by
default), and @code{nnmail} won't delete duplicate mails. Instead it
will insert a warning into the head of the mail saying that it thinks
* Mail Spool:: Store your mail in a private spool?
* MH Spool:: An mhspool-like back end.
* Maildir:: Another one-file-per-message format.
+* nnmaildir Group Parameters::
+* Article Identification::
+* NOV Data::
+* Article Marks::
* Mail Folders:: Having one file for each group.
* Comparing Mail Back Ends:: An in-depth looks at pros and cons.
@end menu
remember to supply a @code{create-directory} server parameter.
@end table
+@node nnmaildir Group Parameters
@subsubsection Group parameters
@code{nnmaildir} uses several group parameters. It's safe to ignore
@code{read}, plus a little extra.
@end table
+@node Article Identification
@subsubsection Article identification
Articles are stored in the @file{cur/} subdirectory of each maildir.
Each article file is named like @code{uniq:info}, where @code{uniq}
available in the variable @code{nnmaildir-article-file-name} after you
request the article in the summary buffer.
+@node NOV Data
@subsubsection NOV data
An article identified by @code{uniq} has its @acronym{NOV} data (used
to generate lines in the summary buffer) stored in
assign a new article number for this article, which may cause trouble
with @code{seen} marks, the Agent, and the cache.
+@node Article Marks
@subsubsection Article marks
An article identified by @code{uniq} is considered to have the mark
@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists.
@table @code
@item nnmbox
-UNIX systems have historically had a single, very common, and well-
-defined format. All messages arrive in a single @dfn{spool file}, and
+UNIX systems have historically had a single, very common, and well-defined
+format. All messages arrive in a single @dfn{spool file}, and
they are delineated by a line whose regular expression matches
@samp{^From_}. (My notational use of @samp{_} is to indicate a space,
to make it clear in this instance that this is not the RFC-specified
mail back ends.
@code{nnmaildir} is largely similar to @code{nnml}, with some notable
-differences. Each message is stored in a separate file, but the
+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
+(Use @code{df -i} to see how plentiful your inode supply is.) If this
slows you down or takes up very much space, a non-block-structured
file system.
* Archiving Mail::
* Web Searches:: Creating groups from articles that match a string.
* RSS:: Reading RDF site summary.
-* Customizing W3:: Doing stuff to Emacs/W3 from Gnus.
@end menu
-All the web sources require Emacs/W3 and the url library or those
-alternatives 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 @acronym{HTML} data
is guesswork at best, and when the layout is altered, the Gnus back end
community. Since @code{nnweb} washes the ads off all the articles, one
might think that the providers might be somewhat miffed. We'll see.
-You must have the @code{url} and @code{W3} package or those alternatives
-(try @code{customize-group} on the @samp{mm-url} variable group)
-installed to be able to use @code{nnweb}.
-
Virtual server variables:
@table @code
@acronym{RSS} is a format for summarizing headlines from news related
sites (such as BBC or CNN). But basically anything list-like can be
presented as an @acronym{RSS} feed: weblogs, changelogs or recent
-changes to a wiki (e.g. @url{http://cliki.net/recent-changes.rdf}).
+changes to a wiki (e.g., @url{http://cliki.net/site/recent-changes}).
@acronym{RSS} has a quite regular and nice interface, and it's
possible to get the information Gnus needs to keep groups updated.
@item nnrss-ignore-article-fields
@vindex nnrss-ignore-article-fields
Some feeds update constantly article fields during their publications,
-e.g. to indicate the number of comments. However, if there is
+e.g., to indicate the number of comments. However, if there is
a difference between the local article and the distant one, the latter
is considered to be new. To avoid this and discard some fields, set this
variable to the list of fields to be ignored. The default is
@end lisp
-@node Customizing W3
-@subsection Customizing W3
-@cindex W3
-@cindex html
-@cindex url
-@cindex Netscape
-
-Gnus uses the url library to fetch web pages and Emacs/W3 (or those
-alternatives) 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
-browser like Netscape). Here's one way:
-
-@lisp
-(eval-after-load "w3"
- '(progn
- (fset 'w3-fetch-orig (symbol-function 'w3-fetch))
- (defun w3-fetch (&optional url target)
- (interactive (list (w3-read-url-with-default)))
- (if (eq major-mode 'gnus-article-mode)
- (browse-url url)
- (w3-fetch-orig url target)))))
-@end lisp
-
-Put that in your @file{.emacs} file, and hitting links in W3-rendered
-@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to
-follow the link.
-
-
@node Other Sources
@section Other Sources
@code{nneething} does this in a two-step process. First, it snoops each
file in question. If the file looks like an article (i.e., the first
few lines look like headers), it will use this as the head. If this is
-just some arbitrary file without a head (e.g. a C source file),
+just some arbitrary file without a head (e.g., a C source file),
@code{nneething} will cobble up a header out of thin air. It will use
file ownership, name and date and do whatever it can with these
elements.
@defvar nndiary-reminders
This is the list of times when you want to be reminded of your
-appointments (e.g. 3 weeks before, then 2 days before, then 1 hour
+appointments (e.g., 3 weeks before, then 2 days before, then 1 hour
before and that's it). Remember that ``being reminded'' means that the
diary message will pop up as brand new and unread again when you get new
mail.
@code{gnus-diary} provides two supplemental user formats to be used in
summary line formats. @code{D} corresponds to a formatted time string
-for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''),
+for the next occurrence of the event (e.g., ``Sat, Sep 22 01, 12:00''),
while @code{d} corresponds to an approximate remaining time until the
-next occurrence of the event (e.g. ``in 6 months, 1 week'').
+next occurrence of the event (e.g., ``in 6 months, 1 week'').
For example, here's how Joe's birthday is displayed in my
@code{nndiary+diary:birthdays} summary buffer (note that the message is
@item
However, since @code{nndiary} also has a @code{request-post} method, you
can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the
-message won't actually be sent; just stored locally in the group. This
+message won't actually be sent; just stored locally in the group. This
comes in very handy for private appointments.
@end itemize
useful values.
For example, you could decide that you don't want to download articles
-that were posted more than a certain number of days ago (e.g. posted
+that were posted more than a certain number of days ago (e.g., posted
more than @code{gnus-agent-expire-days} ago) you might write a function
something along the lines of the following:
@subsection Agent and flags
The Agent works with any Gnus back end including those, such as
-nnimap, that store flags (read, ticked, etc) on the server. Sadly,
+nnimap, that store flags (read, ticked, etc.)@: on the server. Sadly,
the Agent does not actually know which backends keep their flags in
the backend server rather than in @file{.newsrc}. This means that the
Agent, while unplugged or disconnected, will always record all changes
@item gnus-agent-cache
@vindex gnus-agent-cache
Variable to control whether use the locally stored @acronym{NOV} and
-articles when plugged, e.g. essentially using the Agent as a cache.
+articles when plugged, e.g., essentially using the Agent as a cache.
The default is non-@code{nil}, which means to use the Agent as a cache.
@item gnus-agent-go-online
The current score file is by default the group's local score file, even
if no such score file actually exists. To insert score commands into
-some other score file (e.g. @file{all.SCORE}), you must first make this
+some other score file (e.g., @file{all.SCORE}), you must first make this
score file the current one.
General score commands that don't actually change the score file:
@kindex V t (Summary)
@findex gnus-score-find-trace
Display all score rules that have been used on the current article
-(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you
+(@code{gnus-score-find-trace}). In the @file{*Score Trace*} buffer, you
may type @kbd{e} to edit score file corresponding to the score rule on
current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the
score file and edit it.
whole family, eh?)
@item Head, Body, All
-These three match keys use the same match types as the @code{From} (etc)
+These three match keys use the same match types as the @code{From} (etc.)@:
header uses.
@item Followup
This match key is somewhat special, in that it will match the
@code{From} header, and affect the score of not only the matching
articles, but also all followups to the matching articles. This allows
-you e.g. increase the score of followups to your own articles, or
+you to increase the score of followups to your own articles, or
decrease the score of followups to the articles of some known
trouble-maker. Uses the same match types as the @code{From} header
uses. (Using this match key will lead to creation of @file{ADAPT}
rest. Next time you enter the group, you will see new articles in the
interesting threads, plus any new threads.
-I.e.---the orphan score atom is for high-volume groups where a few
+I.e., the orphan score atom is for high-volume groups where a few
interesting threads which can't be found automatically by ordinary
scoring rules exist.
@item !
@itemx not
-@itemx ¬
+@itemx ¬
This logical operator only takes a single argument. It returns the
logical negation of the value of its argument.
@end example
Suppose you're reading a high volume group and you're only interested
-in replies. The plan is to score down all articles that don't have
+in replies. The plan is to score down all articles that don't have
subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all
parents of articles that have subjects that begin with reply marks.
non-@code{nil}, Gnus will run the score files through the decaying
mechanism thereby lowering the scores of all non-permanent score rules.
If @code{gnus-decay-scores} is a regexp, only score files matching this
-regexp are treated. E.g. you may set it to @samp{\\.ADAPT\\'} if only
+regexp are treated. E.g., you may set it to @samp{\\.ADAPT\\'} if only
@emph{adaptive} score files should be decayed. The decay itself if
performed by the @code{gnus-decay-score-function} function, which is
@code{gnus-decay-score} by default. Here's the definition of that
as well.
This chapter describes tools for searching groups and servers for
-articles matching a query and then retrieving those articles. Gnus
+articles matching a query and then retrieving those articles. Gnus
provides a simpler mechanism for searching through articles in a summary buffer
to find those matching a pattern. @xref{Searching for Articles}.
@subsection What is nnir?
@code{nnir} is a Gnus interface to a number of tools for searching
-through mail and news repositories. Different backends (like
+through mail and news repositories. Different backends (like
@code{nnimap} and @code{nntp}) work with different tools (called
@dfn{engines} in @code{nnir} lingo), but all use the same basic search
interface.
The @code{nnimap} and @code{gmane} search engines should work with no
-configuration. Other engines require a local index that needs to be
+configuration. Other engines require a local index that needs to be
created and maintained outside of Gnus.
current line by calling @code{gnus-group-make-nnir-group}. This prompts
for a query string, creates an ephemeral @code{nnir} group containing
the articles that match this query, and takes you to a summary buffer
-showing these articles. Articles may then be read, moved and deleted
+showing these articles. Articles may then be read, moved and deleted
using the usual commands.
-The @code{nnir} group made in this way is an @code{ephemeral} group, and
-some changes are not permanent: aside from reading, moving, and
-deleting, you can't act on the original article. But there is an
-alternative: you can @emph{warp} to the original group for the article
-on the current line with @kbd{A W}, aka
-@code{gnus-warp-to-article}. Even better, the function
-@code{gnus-summary-refer-thread}, bound by default in summary buffers to
-@kbd{A T}, will first warp to the original group before it works its
-magic and includes all the articles in the thread. From here you can
-read, move and delete articles, but also copy them, alter article marks,
-whatever. Go nuts.
+The @code{nnir} group made in this way is an @code{ephemeral} group,
+and some changes are not permanent: aside from reading, moving, and
+deleting, you can't act on the original article. But there is an
+alternative: you can @emph{warp} (i.e., jump) to the original group
+for the article on the current line with @kbd{A W}, aka
+@code{gnus-warp-to-article}. Even better, the function
+@code{gnus-summary-refer-thread}, bound by default in summary buffers
+to @kbd{A T}, will first warp to the original group before it works
+its magic and includes all the articles in the thread. From here you
+can read, move and delete articles, but also copy them, alter article
+marks, whatever. Go nuts.
You say you want to search more than just the group on the current line?
-No problem: just process-mark the groups you want to search. You want
-even more? Calling for an nnir search with the cursor on a topic heading
+No problem: just process-mark the groups you want to search. You want
+even more? Calling for an nnir search with the cursor on a topic heading
will search all the groups under that heading.
-Still not enough? OK, in the server buffer
+Still not enough? OK, in the server buffer
@code{gnus-group-make-nnir-group} (now bound to @kbd{G}) will search all
-groups from the server on the current line. Too much? Want to ignore
-certain groups when searching, like spam groups? Just customize
+groups from the server on the current line. Too much? Want to ignore
+certain groups when searching, like spam groups? Just customize
@code{nnir-ignored-newsgroups}.
One more thing: individual search engines may have special search
-features. You can access these special features by giving a prefix-arg
-to @code{gnus-group-make-nnir-group}. If you are searching multiple
+features. You can access these special features by giving a prefix-arg
+to @code{gnus-group-make-nnir-group}. If you are searching multiple
groups with different search engines you will be prompted for the
special search features for each engine separately.
@node Setting up nnir
@subsection Setting up nnir
-To set up nnir you may need to do some prep work. Firstly, you may need
-to configure the search engines you plan to use. Some of them, like
-@code{imap} and @code{gmane}, need no special configuration. Others,
+To set up nnir you may need to do some prep work. Firstly, you may need
+to configure the search engines you plan to use. Some of them, like
+@code{imap} and @code{gmane}, need no special configuration. Others,
like @code{namazu} and @code{swish}, require configuration as described
-below. Secondly, you need to associate a search engine with a server or
+below. Secondly, you need to associate a search engine with a server or
a backend.
If you just want to use the @code{imap} engine to search @code{nnimap}
servers, and the @code{gmane} engine to search @code{gmane} then you
-don't have to do anything. But you might want to read the details of the
+don't have to do anything. But you might want to read the details of the
query language anyway.
@menu
* The swish++ Engine:: Swish++ configuration and usage.
* The swish-e Engine:: Swish-e configuration and usage.
* The namazu Engine:: Namazu configuration and usage.
+* The notmuch Engine:: Notmuch configuration and usage.
* The hyrex Engine:: Hyrex configuration and usage.
* Customizations:: User customizable settings.
@end menu
When searching a group, @code{nnir} needs to know which search engine to
-use. You can configure a given server to use a particular engine by
+use. You can configure a given server to use a particular engine by
setting the server variable @code{nnir-search-engine} to the engine
-name. For example to use the @code{namazu} engine to search the server
+name. For example to use the @code{namazu} engine to search the server
named @code{home} you can use
@lisp
@end lisp
Alternatively you might want to use a particular engine for all servers
-with a given backend. For example, you might want to use the @code{imap}
-engine for all servers using the @code{nnimap} backend. In this case you
-can customize the variable @code{nnir-method-default-engines}. This is
-an alist of pairs of the form @code{(backend . engine)}. By default this
+with a given backend. For example, you might want to use the @code{imap}
+engine for all servers using the @code{nnimap} backend. In this case you
+can customize the variable @code{nnir-method-default-engines}. This is
+an alist of pairs of the form @code{(backend . engine)}. By default this
variable is set to use the @code{imap} engine for all servers using the
@code{nnimap} backend, and the @code{gmane} backend for @code{nntp}
-servers. (Don't worry, the @code{gmane} search engine won't actually try
-to search non-gmane @code{nntp} servers.) But if you wanted to use
+servers. (Don't worry, the @code{gmane} search engine won't actually try
+to search non-gmane @code{nntp} servers.) But if you wanted to use
@code{namazu} for all your servers with an @code{nnimap} backend you
could change this to
@item Boolean query operators
AND, OR, and NOT are supported, and parentheses can be used to control
-operator precedence, e.g. (emacs OR xemacs) AND linux. Note that
+operator precedence, e.g., (emacs OR xemacs) AND linux. Note that
operators must be written with all capital letters to be
-recognized. Also preceding a term with a - sign is equivalent to NOT
-term.
+recognized. Also preceding a term with a @minus{} sign is equivalent
+to NOT term.
@item Automatic AND queries
If you specify multiple words then they will be treated as an AND
@end table
-By default the whole message will be searched. The query can be limited
-to a specific part of a message by using a prefix-arg. After inputting
+By default the whole message will be searched. The query can be limited
+to a specific part of a message by using a prefix-arg. After inputting
the query this will prompt (with completion) for a message part.
Choices include ``Whole message'', ``Subject'', ``From'', and
-``To''. Any unrecognized input is interpreted as a header name. For
+``To''. Any unrecognized input is interpreted as a header name. For
example, typing @kbd{Message-ID} in response to this prompt will limit
the query to the Message-ID header.
Finally selecting ``Imap'' will interpret the query as a raw
-@acronym{IMAP} search query. The format of such queries can be found in
+@acronym{IMAP} search query. The format of such queries can be found in
RFC3501.
If you don't like the default of searching whole messages you can
-customize @code{nnir-imap-default-search-key}. For example to use
+customize @code{nnir-imap-default-search-key}. For example to use
@acronym{IMAP} queries by default
@lisp
@table @samp
@item Boolean query operators
AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be
-used to control operator precedence, e.g. (emacs OR xemacs) AND linux.
+used to control operator precedence, e.g., (emacs OR xemacs) AND linux.
Note that operators must be written with all capital letters to be
recognized.
@item Required and excluded terms
-+ and - can be used to require or exclude terms, e.g. football -american
++ and @minus{} can be used to require or exclude terms, e.g., football
+@minus{}american
@item Unicode handling
The search engine converts all text to utf-8, so searching should work
in any language.
@item Stopwords
-Common English words (like 'the' and 'a') are ignored by default. You
-can override this by prefixing such words with a + (e.g. +the) or
-enclosing the word in quotes (e.g. "the").
+Common English words (like 'the' and 'a') are ignored by default. You
+can override this by prefixing such words with a + (e.g., +the) or
+enclosing the word in quotes (e.g., "the").
@end table
The query can be limited to articles by a specific author using a
-prefix-arg. After inputting the query this will prompt for an author
+prefix-arg. After inputting the query this will prompt for an author
name (or part of a name) to match.
@node The swish++ Engine
@table @code
@item nnir-swish++-program
-The name of the swish++ executable. Defaults to @code{search}
+The name of the swish++ executable. Defaults to @code{search}
@item nnir-swish++-additional-switches
A list of strings to be given as additional arguments to
-swish++. @code{nil} by default.
+swish++. @code{nil} by default.
@item nnir-swish++-remove-prefix
The prefix to remove from each file name returned by swish++ in order
-to get a group name. By default this is @code{$HOME/Mail}.
+to get a group name. By default this is @code{$HOME/Mail}.
@end table
@table @code
@item nnir-swish-e-program
-The name of the swish-e search program. Defaults to @code{swish-e}.
+The name of the swish-e search program. Defaults to @code{swish-e}.
@item nnir-swish-e-additional-switches
A list of strings to be given as additional arguments to
-swish-e. @code{nil} by default.
+swish-e. @code{nil} by default.
@item nnir-swish-e-remove-prefix
The prefix to remove from each file name returned by swish-e in order
-to get a group name. By default this is @code{$HOME/Mail}.
+to get a group name. By default this is @code{$HOME/Mail}.
@end table
variable.
To work correctly the @code{nnir-namazu-remove-prefix} variable must
-also be correct. This is the prefix to remove from each file name
+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 `.').
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:
+for namazu to create a configuration file. Here is an example:
@cartouche
@example
For maximum searching efficiency you might want to have a cron job run
this command periodically, say every four hours.
+
+@node The notmuch Engine
+@subsubsection The notmuch Engine
+
+@table @code
+@item nnir-notmuch-program
+The name of the notmuch search executable. Defaults to
+@samp{notmuch}.
+
+@item nnir-notmuch-additional-switches
+A list of strings, to be given as additional arguments to notmuch.
+
+@item nnir-notmuch-remove-prefix
+The prefix to remove from each file name returned by notmuch in order
+to get a group name (albeit with @samp{/} instead of @samp{.}). This
+is a regular expression.
+
+@end table
+
+
@node The hyrex Engine
@subsubsection The hyrex Engine
This engine is obsolete.
@table @code
@item nnir-method-default-engines
-Alist of server backend - search engine pairs. The default associations
-are
+Alist of pairs of server backends and search engines. The default
+associations are
@example
(nnimap . imap)
(nntp . gmane)
If non-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
-retrieved headers. It should then return either 'nov or 'headers
-indicating the retrieved header format. Failure to retrieve headers
-should return @code{nil}
+retrieved headers. It should then return either 'nov or 'headers
+indicating the retrieved header format. Failure to retrieve headers
+should return @code{nil}.
If this variable is nil, or if the provided function returns nil for a
search result, @code{gnus-retrieve-headers} will be called instead."
@end menu
@c FIXME: The markup in this section might need improvement.
-@c E.g. adding @samp, @var, @file, @command, etc.
+@c E.g., adding @samp, @var, @file, @command, etc.
@c Cf. (info "(texinfo)Indicating")
@node About mairix
Mairix is a tool for indexing and searching words in locally stored
mail. It was written by Richard Curnow and is licensed under the
-GPL. Mairix comes with most popular GNU/Linux distributions, but it also
+GPL@. Mairix comes with most popular GNU/Linux distributions, but it also
runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can
be found at
@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html}
Mairix searches local mail---that means, mairix absolutely must have
direct access to your mail folders. If your mail resides on another
-server (e.g. an @acronym{IMAP} server) and you happen to have shell
-access, @code{nnmairix} supports running mairix remotely, e.g. via ssh.
+server (e.g., an @acronym{IMAP} server) and you happen to have shell
+access, @code{nnmairix} supports running mairix remotely, e.g., via ssh.
Additionally, @code{nnmairix} only supports the following Gnus back
ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use
The back end @code{nnmairix} enables you to call mairix from within Gnus,
either to query mairix with a search term or to update the
database. While visiting a message in the summary buffer, you can use
-several pre-defined shortcuts for calling mairix, e.g. to quickly
+several pre-defined shortcuts for calling mairix, e.g., to quickly
search for all mails from the sender of the current message or to
display the whole thread associated with the message, even if the
mails are in different folders.
Additionally, you can create permanent @code{nnmairix} groups which are bound
to certain mairix searches. This way, you can easily create a group
containing mails from a certain sender, with a certain subject line or
-even for one specific thread based on the Message-ID. If you check for
-new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they
+even for one specific thread based on the Message-ID@. If you check for
+new mail in these folders (e.g., by pressing @kbd{g} or @kbd{M-g}), they
automatically update themselves by calling mairix.
You might ask why you need @code{nnmairix} at all, since mairix already
strange article counts, and sometimes you might see mails which Gnus
claims have already been canceled and are inaccessible. This is due to
the fact that Gnus isn't really amused when things are happening behind
-its back. Another problem can be the mail back end itself, e.g. if you
+its back. Another problem can be the mail back end itself, e.g., if you
use mairix with an @acronym{IMAP} server (I had Dovecot complaining
about corrupt index files when mairix changed the contents of the search
group). Using @code{nnmairix} should circumvent these problems.
present these folders in the Gnus front end only with @code{<NAME>}.
You can use an existing mail back end where you already store your mail,
but if you're uncomfortable with @code{nnmairix} creating new mail
-groups alongside your other mail, you can also create e.g. a new
+groups alongside your other mail, you can also create, e.g., a new
@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then
make sure those servers do not accidentally receive your new mail
(@pxref{nnmairix caveats}). A special case exists if you want to use
which are accessed through @code{nnmaildir}, @code{nnimap} and
@code{nnml} are supported. As explained above, for locally stored
mails, this can be an existing server where you store your mails.
-However, you can also create e.g. a new @code{nnmaildir} or @code{nnml}
+However, you can also create, e.g., a new @code{nnmaildir} or @code{nnml}
server exclusively for @code{nnmairix} in your secondary select methods
(@pxref{Finding the News}). If you use a secondary @code{nnml} server
just for mairix, make sure that you explicitly set the server variable
@vindex nnmairix-mairix-search-options
The @strong{command} to call the mairix binary. This will usually just
be @code{mairix}, but you can also choose something like @code{ssh
-SERVER mairix} if you want to call mairix remotely, e.g. on your
+SERVER mairix} if you want to call mairix remotely, e.g., on your
@acronym{IMAP} server. If you want to add some default options to
mairix, you could do this here, but better use the variable
@code{nnmairix-mairix-search-options} instead.
@item
The name of the @strong{default search group}. This will be the group
-where all temporary mairix searches are stored, i.e. all searches which
+where all temporary mairix searches are stored, i.e., all searches which
are not bound to permanent @code{nnmairix} groups. Choose whatever you
like.
@item
If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be
-asked if you work with @strong{Maildir++}, i.e. with hidden maildir
+asked if you work with @strong{Maildir++}, i.e., with hidden maildir
folders (=beginning with a dot). For example, you have to answer
@samp{yes} here if you work with the Dovecot @acronym{IMAP}
server. Otherwise, you should answer @samp{no}&
projects / gnus / blobdiff