[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r102651: gnus.texi (Filtering New Gro
|
From: |
Katsumi Yamaoka |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r102651: gnus.texi (Filtering New Groups): Mention. |
|
Date: |
Mon, 13 Dec 2010 23:54:31 +0000 |
|
User-agent: |
Bazaar (2.0.3) |
------------------------------------------------------------
revno: 102651
author: Andrew Cohen <address@hidden>
committer: Katsumi Yamaoka <address@hidden>
branch nick: trunk
timestamp: Mon 2010-12-13 23:54:31 +0000
message:
gnus.texi (Filtering New Groups): Mention.
modified:
doc/misc/ChangeLog
doc/misc/gnus.texi
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2010-12-13 22:29:12 +0000
+++ b/doc/misc/ChangeLog 2010-12-13 23:54:31 +0000
@@ -1,3 +1,7 @@
+2010-12-13 Andrew Cohen <address@hidden>
+
+ * gnus.texi: First pass at adding (rough) nnir documentation.
+
2010-12-13 Lars Magne Ingebrigtsen <address@hidden>
* gnus.texi (Filtering New Groups): Mention
=== modified file 'doc/misc/gnus.texi'
--- a/doc/misc/gnus.texi 2010-12-13 22:29:12 +0000
+++ b/doc/misc/gnus.texi 2010-12-13 23:54:31 +0000
@@ -407,6 +407,7 @@
* Composing Messages:: Information on sending mail and news.
* Select Methods:: Gnus reads all messages from various select
methods.
* Scoring:: Assigning values to articles.
+* Searching:: Mail and News search engines.
* Various:: General purpose settings.
* The End:: Farewell and goodbye.
* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History,
Internals.
@@ -785,6 +786,21 @@
* Advanced Scoring Examples:: What they look like.
* Advanced Scoring Tips:: Getting the most out of it.
+Searching
+
+* nnir:: Searching with various engines.
+* nnmairix:: Searching with Mairix.
+
+nnir
+
+* What is nnir:: What does nnir do.
+* Basic Usage:: How to perform simple searches.
+* Setting up nnir:: How to set up nnir.
+
+Setting up nnir
+
+* Associating Engines:: How to associate engines.
+
Various
* Process/Prefix:: A convention used by many treatment commands.
@@ -1660,7 +1676,6 @@
* Exiting Gnus:: Stop reading news and get some work done.
* Group Topics:: A folding group mode divided into topics.
* Non-ASCII Group Names:: Accessing groups of non-English names.
-* Searching:: Mail search engines.
* Misc Group Stuff:: Other stuff that you can to do.
@end menu
@@ -4282,712 +4297,6 @@
header will be displayed incorrectly in the article buffer.
address@hidden Searching
address@hidden Searching
-
address@hidden
-* nnir:: Searching on IMAP, with swish, namazu, etc.
-* nnmairix:: Searching maildir, MH or mbox with Mairix.
address@hidden menu
-
address@hidden Searching
-
-FIXME: This node is a stub.
-
-FIXME: Add a brief overview of Gnus search capabilities. A brief
-comparison of nnir, nnmairix, contrib/gnus-namazu would be nice
-as well.
-
-FIXME: Explain difference to @ref{Searching for Articles}, add reference
-and back-reference.
-
address@hidden nnir
address@hidden nnir
-
-FIXME: As a first step, convert the commentary of @file{nnir} to texi.
address@hidden nnir
-
address@hidden nnmairix
address@hidden nnmairix
-
address@hidden mairix
address@hidden nnmairix
-This paragraph describes how to set up mairix and the back end
address@hidden for indexing and searching your mail from within
-Gnus. Additionally, you can create permanent ``smart'' groups which are
-bound to mairix searches and are automatically updated.
-
address@hidden
-* About mairix:: About the mairix mail search engine
-* nnmairix requirements:: What you will need for using nnmairix
-* What nnmairix does:: What does nnmairix actually do?
-* Setting up mairix:: Set up your mairix installation
-* Configuring nnmairix:: Set up the nnmairix back end
-* nnmairix keyboard shortcuts:: List of available keyboard shortcuts
-* Propagating marks:: How to propagate marks from nnmairix groups
-* nnmairix tips and tricks:: Some tips, tricks and examples
-* nnmairix caveats:: Some more stuff you might want to know
address@hidden menu
-
address@hidden FIXME: The markup in this section might need improvement.
address@hidden E.g. adding @samp, @var, @file, @command, etc.
address@hidden Cf. (info "(texinfo)Indicating")
-
address@hidden About mairix
address@hidden 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
-runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can
-be found at
address@hidden://www.rpcurnow.force9.co.uk/mairix/index.html}
-
-Though mairix might not be as flexible as other search tools like
-swish++ or namazu, which you can use via the @code{nnir} back end, it
-has the prime advantage of being incredibly fast. On current systems, it
-can easily search through headers and message bodies of thousands and
-thousands of mails in well under a second. Building the database
-necessary for searching might take a minute or two, but only has to be
-done once fully. Afterwards, the updates are done incrementally and
-therefore are really fast, too. Additionally, mairix is very easy to set
-up.
-
-For maximum speed though, mairix should be used with mails stored in
address@hidden or @code{MH} format (this includes the @code{nnml} back
-end), although it also works with mbox. Mairix presents the search
-results by populating a @emph{virtual} maildir/MH folder with symlinks
-which point to the ``real'' message files (if mbox is used, copies are
-made). Since mairix already presents search results in such a virtual
-mail folder, it is very well suited for using it as an external program
-for creating @emph{smart} mail folders, which represent certain mail
-searches.
-
address@hidden nnmairix requirements
address@hidden nnmairix requirements
-
-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.
-
-Additionally, @code{nnmairix} only supports the following Gnus back
-ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use
-one of these back ends for using @code{nnmairix}. Other back ends, like
address@hidden, @code{nnfolder} or @code{nnmh}, won't work.
-
-If you absolutely must use mbox and still want to use @code{nnmairix},
-you can set up a local @acronym{IMAP} server, which you then access via
address@hidden This is a rather massive setup for accessing some mbox
-files, so just change to MH or Maildir already... However, if you're
-really, really passionate about using mbox, you might want to look into
-the package @file{mairix.el}, which comes with Emacs 23.
-
address@hidden What nnmairix does
address@hidden What nnmairix does
-
-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
-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
-automatically update themselves by calling mairix.
-
-You might ask why you need @code{nnmairix} at all, since mairix already
-creates the group, populates it with links to the mails so that you can
-then access it with Gnus, right? Well, this @emph{might} work, but often
-does not---at least not without problems. Most probably you will get
-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
-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.
-
address@hidden is not really a mail back end---it's actually more like
-a wrapper, sitting between a ``real'' mail back end where mairix stores
-the searches and the Gnus front end. You can choose between three
-different mail back ends for the mairix folders: @code{nnml},
address@hidden or @code{nnimap}. @code{nnmairix} will call the mairix
-binary so that the search results are stored in folders named
address@hidden<NAME>-<NUMBER>} on this mail back end, but it will
-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
address@hidden 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
-mairix remotely on an IMAP server with @code{nnimap}---here the mairix
-folders and your other mail must be on the same @code{nnimap} back end.
-
address@hidden Setting up mairix
address@hidden Setting up mairix
-
-First: create a backup of your mail folders (@pxref{nnmairix caveats}).
-
-Setting up mairix is easy: simply create a @file{.mairixrc} file with
-(at least) the following entries:
-
address@hidden
-# Your Maildir/MH base folder
-base=~/Maildir
address@hidden example
-
-This is the base folder for your mails. All the following directories
-are relative to this base folder. If you want to use @code{nnmairix}
-with @code{nnimap}, this base directory has to point to the mail
-directory where the @acronym{IMAP} server stores the mail folders!
-
address@hidden
-maildir= ... your maildir folders which should be indexed ...
-mh= ... your nnml/mh folders which should be indexed ...
-mbox = ... your mbox files which should be indexed ...
address@hidden example
-
-This specifies all your mail folders and mbox files (relative to the
-base directory!) you want to index with mairix. Note that the
address@hidden back end saves mails in MH format, so you have to put those
-directories in the @code{mh} line. See the example at the end of this
-section and mairixrc's man-page for further details.
-
address@hidden
-omit=zz_mairix-*
address@hidden example
-
address@hidden nnmairix-group-prefix
-This should make sure that you don't accidentally index the mairix
-search results. You can change the prefix of these folders with the
-variable @code{nnmairix-group-prefix}.
-
address@hidden
-mformat= ... 'maildir' or 'mh' ...
-database= ... location of database file ...
address@hidden example
-
-The @code{format} setting specifies the output format for the mairix
-search folder. Set this to @code{mh} if you want to access search results
-with @code{nnml}. Otherwise choose @code{maildir}.
-
-To summarize, here is my shortened @file{.mairixrc} file as an example:
-
address@hidden
-base=~/Maildir
-maildir=.personal:.work:.logcheck:.sent
-mh=../Mail/nnml/*...
-mbox=../mboxmail/mailarchive_year*
-mformat=maildir
-omit=zz_mairix-*
-database=~/.mairixdatabase
address@hidden example
-
-In this case, the base directory is @file{~/Maildir}, where all my Maildir
-folders are stored. As you can see, the folders are separated by
-colons. If you wonder why every folder begins with a dot: this is
-because I use Dovecot as @acronym{IMAP} server, which again uses
address@hidden folders. For testing nnmairix, I also have some
address@hidden mail, which is saved in @file{~/Mail/nnml}. Since this has
-to be specified relative to the @code{base} directory, the @code{../Mail}
-notation is needed. Note that the line ends in @code{*...}, which means
-to recursively scan all files under this directory. Without the three
-dots, the wildcard @code{*} will not work recursively. I also have some
-old mbox files with archived mail lying around in @file{~/mboxmail}.
-The other lines should be obvious.
-
-See the man page for @code{mairixrc} for details and further options,
-especially regarding wildcard usage, which may be a little different
-than you are used to.
-
-Now simply call @code{mairix} to create the index for the first time.
-Note that this may take a few minutes, but every following index will do
-the updates incrementally and hence is very fast.
-
address@hidden Configuring nnmairix
address@hidden Configuring nnmairix
-
-In group mode, type @kbd{G b c}
-(@code{nnmairix-create-server-and-default-group}). This will ask you for all
-necessary information and create a @code{nnmairix} server as a foreign
-server. You will have to specify the following:
-
address@hidden @bullet
-
address@hidden
-The @strong{name} of the @code{nnmairix} server---choose whatever you
-want.
-
address@hidden
-The name of the @strong{back end server} where mairix should store its
-searches. This must be a full server name, like @code{nnml:mymail}.
-Just hit @kbd{TAB} to see the available servers. Currently, servers
-which are accessed through @code{nnmaildir}, @code{nnimap} and
address@hidden 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}
-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
address@hidden to @code{nil}, or you might lose mail
-(@pxref{nnmairix caveats}). If you want to use mairix remotely on an
address@hidden server, you have to choose the corresponding
address@hidden server here.
-
address@hidden
address@hidden 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
address@hidden server. If you want to add some default options to
-mairix, you could do this here, but better use the variable
address@hidden instead.
-
address@hidden
-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
-are not bound to permanent @code{nnmairix} groups. Choose whatever you
-like.
-
address@hidden
-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
-folders (=beginning with a dot). For example, you have to answer
address@hidden here if you work with the Dovecot @acronym{IMAP}
-server. Otherwise, you should answer @samp{no} here.
-
address@hidden itemize
-
address@hidden nnmairix keyboard shortcuts
address@hidden nnmairix keyboard shortcuts
-
-In group mode:
-
address@hidden @kbd
-
address@hidden G b c
address@hidden G b c (Group)
address@hidden nnmairix-create-server-and-default-group
-Creates @code{nnmairix} server and default search group for this server
-(@code{nnmairix-create-server-and-default-group}). You should have done
-this by now (@pxref{Configuring nnmairix}).
-
address@hidden G b s
address@hidden G b s (Group)
address@hidden nnmairix-search
-Prompts for query which is then sent to the mairix binary. Search
-results are put into the default search group which is automatically
-displayed (@code{nnmairix-search}).
-
address@hidden G b m
address@hidden G b m (Group)
address@hidden nnmairix-widget-search
-Allows you to create a mairix search or a permanent group more
-comfortably using graphical widgets, similar to a customization
-group. Just try it to see how it works (@code{nnmairix-widget-search}).
-
address@hidden G b i
address@hidden G b i (Group)
address@hidden nnmairix-search-interactive
-Another command for creating a mairix query more comfortably, but uses
-only the minibuffer (@code{nnmairix-search-interactive}).
-
address@hidden G b g
address@hidden G b g (Group)
address@hidden nnmairix-create-search-group
-Creates a permanent group which is associated with a search query
-(@code{nnmairix-create-search-group}). The @code{nnmairix} back end
-automatically calls mairix when you update this group with @kbd{g} or
address@hidden
-
address@hidden G b q
address@hidden G b q (Group)
address@hidden nnmairix-group-change-query-this-group
-Changes the search query for the @code{nnmairix} group under cursor
-(@code{nnmairix-group-change-query-this-group}).
-
address@hidden G b t
address@hidden G b t (Group)
address@hidden nnmairix-group-toggle-threads-this-group
-Toggles the 'threads' parameter for the @code{nnmairix} group under cursor,
-i.e. if you want see the whole threads of the found messages
-(@code{nnmairix-group-toggle-threads-this-group}).
-
address@hidden G b u
address@hidden G b u (Group)
address@hidden nnmairix-update-database
address@hidden nnmairix-mairix-update-options
-Calls mairix binary for updating the database
-(@code{nnmairix-update-database}). The default parameters are @code{-F}
-and @code{-Q} for making this as fast as possible (see variable
address@hidden for defining these default
-options).
-
address@hidden G b r
address@hidden G b r (Group)
address@hidden nnmairix-group-toggle-readmarks-this-group
-Keep articles in this @code{nnmairix} group always read or unread, or leave the
-marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}).
-
address@hidden G b d
address@hidden G b d (Group)
address@hidden nnmairix-group-delete-recreate-this-group
-Recreate @code{nnmairix} group on the ``real'' mail back end
-(@code{nnmairix-group-delete-recreate-this-group}). You can do this if
-you always get wrong article counts with a @code{nnmairix} group.
-
address@hidden G b a
address@hidden G b a (Group)
address@hidden nnmairix-group-toggle-allowfast-this-group
-Toggles the @code{allow-fast} parameters for group under cursor
-(@code{nnmairix-group-toggle-allowfast-this-group}). The default
-behavior of @code{nnmairix} is to do a mairix search every time you
-update or enter the group. With the @code{allow-fast} parameter set,
-mairix will only be called when you explicitly update the group, but not
-upon entering. This makes entering the group faster, but it may also
-lead to dangling symlinks if something changed between updating and
-entering the group which is not yet in the mairix database.
-
address@hidden G b p
address@hidden G b p (Group)
address@hidden nnmairix-group-toggle-propmarks-this-group
-Toggle marks propagation for this group
-(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating
-marks}).
-
address@hidden G b o
address@hidden G b o (Group)
address@hidden nnmairix-propagate-marks
-Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when
address@hidden is set to @code{nil}.
-
address@hidden table
-
-In summary mode:
-
address@hidden @kbd
-
address@hidden $ m
address@hidden $ m (Summary)
address@hidden nnmairix-widget-search-from-this-article
-Allows you to create a mairix query or group based on the current
-message using graphical widgets (same as @code{nnmairix-widget-search})
-(@code{nnmairix-widget-search-from-this-article}).
-
address@hidden $ g
address@hidden $ g (Summary)
address@hidden nnmairix-create-search-group-from-message
-Interactively creates a new search group with query based on the current
-message, but uses the minibuffer instead of graphical widgets
-(@code{nnmairix-create-search-group-from-message}).
-
address@hidden $ t
address@hidden $ t (Summary)
address@hidden nnmairix-search-thread-this-article
-Searches thread for the current article
-(@code{nnmairix-search-thread-this-article}). This is effectively a
-shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the
-current article and enabled threads.
-
address@hidden $ f
address@hidden $ f (Summary)
address@hidden nnmairix-search-from-this-article
-Searches all messages from sender of the current article
-(@code{nnmairix-search-from-this-article}). This is a shortcut for
-calling @code{nnmairix-search} with @samp{f:From}.
-
address@hidden $ o
address@hidden $ o (Summary)
address@hidden nnmairix-goto-original-article
-(Only in @code{nnmairix} groups!) Tries determine the group this article
-originally came from and displays the article in this group, so that
-e.g. replying to this article the correct posting styles/group
-parameters are applied (@code{nnmairix-goto-original-article}). This
-function will use the registry if available, but can also parse the
-article file name as a fallback method.
-
address@hidden $ u
address@hidden $ u (Summary)
address@hidden nnmairix-remove-tick-mark-original-article
-Remove possibly existing tick mark from original article
-(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix
-tips and tricks}).
-
address@hidden table
-
address@hidden Propagating marks
address@hidden Propagating marks
-
-First of: you really need a patched mairix binary for using the marks
-propagation feature efficiently. Otherwise, you would have to update
-the mairix database all the time. You can get the patch at
-
address@hidden://www.randomsample.de/mairix-maildir-patch.tar}
-
-You need the mairix v0.21 source code for this patch; everything else
-is explained in the accompanied readme file. If you don't want to use
-marks propagation, you don't have to apply these patches, but they also
-fix some annoyances regarding changing maildir flags, so it might still
-be useful to you.
-
-With the patched mairix binary, you can use @code{nnmairix} as an
-alternative to mail splitting (@pxref{Fancy Mail Splitting}). For
-example, instead of splitting all mails from @samp{david@@foobar.com}
-into a group, you can simply create a search group with the query
address@hidden:david@@foobar.com}. This is actually what ``smart folders'' are
-all about: simply put everything in one mail folder and dynamically
-create searches instead of splitting. This is more flexible, since you
-can dynamically change your folders any time you want to. This also
-implies that you will usually read your mails in the @code{nnmairix}
-groups instead of your ``real'' mail groups.
-
-There is one problem, though: say you got a new mail from
address@hidden@@foobar.com}; it will now show up in two groups, the
-``real'' group (your INBOX, for example) and in the @code{nnmairix}
-search group (provided you have updated the mairix database). Now you
-enter the @code{nnmairix} group and read the mail. The mail will be
-marked as read, but only in the @code{nnmairix} group---in the ``real''
-mail group it will be still shown as unread.
-
-You could now catch up the mail group (@pxref{Group Data}), but this is
-tedious and error prone, since you may overlook mails you don't have
-created @code{nnmairix} groups for. Of course, you could first use
address@hidden (@pxref{nnmairix keyboard
-shortcuts}) and then read the mail in the original group, but that's
-even more cumbersome.
-
-Clearly, the easiest way would be if marks could somehow be
-automatically set for the original article. This is exactly what
address@hidden propagation} is about.
-
-Marks propagation is deactivated by default. You can activate it for a
-certain @code{nnmairix} group with
address@hidden (bound to @kbd{G b
-p}). This function will warn you if you try to use it with your default
-search group; the reason is that the default search group is used for
-temporary searches, and it's easy to accidentally propagate marks from
-this group. However, you can ignore this warning if you really want to.
-
-With marks propagation enabled, all the marks you set in a @code{nnmairix}
-group should now be propagated to the original article. For example,
-you can now tick an article (by default with @kbd{!}) and this mark should
-magically be set for the original article, too.
-
-A few more remarks which you may or may not want to know:
-
address@hidden nnmairix-propagate-marks-upon-close
-Marks will not be set immediately, but only upon closing a group. This
-not only makes marks propagation faster, it also avoids problems with
-dangling symlinks when dealing with maildir files (since changing flags
-will change the file name). You can also control when to propagate marks
-via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for
-details).
-
-Obviously, @code{nnmairix} will have to look up the original group for every
-article you want to set marks for. If available, @code{nnmairix} will first use
-the registry for determining the original group. The registry is very
-fast, hence you should really, really enable the registry when using
-marks propagation. If you don't have to worry about RAM and disc space,
-set @code{gnus-registry-max-entries} to a large enough value; to be on
-the safe side, choose roughly the amount of mails you index with mairix.
-
address@hidden nnmairix-only-use-registry
-If you don't want to use the registry or the registry hasn't seen the
-original article yet, @code{nnmairix} will use an additional mairix
-search for determining the file name of the article. This, of course, is
-way slower than the registry---if you set hundreds or even thousands of
-marks this way, it might take some time. You can avoid this situation by
-setting @code{nnmairix-only-use-registry} to t.
-
-Maybe you also want to propagate marks the other way round, i.e. if you
-tick an article in a "real" mail group, you'd like to have the same
-article in a @code{nnmairix} group ticked, too. For several good
-reasons, this can only be done efficiently if you use maildir. To
-immediately contradict myself, let me mention that it WON'T work with
address@hidden, since @code{nnmaildir} stores the marks externally and
-not in the file name. Therefore, propagating marks to @code{nnmairix}
-groups will usually only work if you use an IMAP server which uses
-maildir as its file format.
-
address@hidden nnmairix-propagate-marks-to-nnmairix-groups
-If you work with this setup, just set
address@hidden to @code{t} and see what
-happens. If you don't like what you see, just set it to @code{nil} again. One
-problem might be that you get a wrong number of unread articles; this
-usually happens when you delete or expire articles in the original
-groups. When this happens, you can recreate the @code{nnmairix} group on the
-back end using @kbd{G b d}.
-
address@hidden nnmairix tips and tricks
address@hidden nnmairix tips and tricks
-
address@hidden
address@hidden
-Checking Mail
-
address@hidden nnmairix-update-groups
-I put all my important mail groups at group level 1. The mairix groups
-have group level 5, so they do not get checked at start up (@pxref{Group
-Levels}).
-
-I use the following to check for mails:
-
address@hidden
-(defun my-check-mail-mairix-update (level)
- (interactive "P")
- ;; if no prefix given, set level=1
- (gnus-group-get-new-news (or level 1))
- (nnmairix-update-groups "mairixsearch" t t)
- (gnus-group-list-groups))
-
-(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update)
address@hidden lisp
-
-Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix}
-server. See the doc string for @code{nnmairix-update-groups} for
-details.
-
address@hidden
-Example: search group for ticked articles
-
-For example, you can create a group for all ticked articles, where the
-articles always stay unread:
-
-Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use
address@hidden:f} as query and do not include threads.
-
-Now activate marks propagation for this group by using @kbd{G b p}. Then
-activate the always-unread feature by using @kbd{G b r} twice.
-
-So far so good---but how do you remove the tick marks in the @code{nnmairix}
-group? There are two options: You may simply use
address@hidden (bound to @kbd{$ u}) to remove
-tick marks from the original article. The other possibility is to set
address@hidden to @code{t}, but see the above
-comments about this option. If it works for you, the tick marks should
-also exist in the @code{nnmairix} group and you can remove them as usual,
-e.g. by marking an article as read.
-
-When you have removed a tick mark from the original article, this
-article should vanish from the @code{nnmairix} group after you have updated the
-mairix database and updated the group. Fortunately, there is a function
-for doing exactly that: @code{nnmairix-update-groups}. See the previous code
-snippet and the doc string for details.
-
address@hidden
-Dealing with auto-subscription of mail groups
-
-As described before, all @code{nnmairix} groups are in fact stored on
-the mail back end in the form @samp{zz_mairix-<NAME>-<NUMBER>}. You can
-see them when you enter the back end server in the server buffer. You
-should not subscribe these groups! Unfortunately, these groups will
-usually get @emph{auto-subscribed} when you use @code{nnmaildir} or
address@hidden, i.e. you will suddenly see groups of the form
address@hidden pop up in your group buffer. If this happens to you,
-simply kill these groups with C-k. For avoiding this, turn off
-auto-subscription completely by setting the variable
address@hidden to @code{nil} (@pxref{Filtering New
-Groups}), or if you like to keep this feature use the following kludge
-for turning it off for all groups beginning with @samp{zz_}:
-
address@hidden
-(setq gnus-auto-subscribed-groups
-
"^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*")
address@hidden lisp
-
address@hidden itemize
-
address@hidden nnmairix caveats
address@hidden nnmairix caveats
-
address@hidden
address@hidden
-You can create a secondary @code{nnml} server just for nnmairix, but then
-you have to explicitly set the corresponding server variable
address@hidden to @code{nil}. Otherwise, new mail might get
-put into this secondary server (and would never show up again). Here's
-an example server definition:
-
address@hidden
-(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil))
address@hidden lisp
-
-(The @code{nnmaildir} back end also has a server variabe
address@hidden, but its default value is @code{nil}, so you don't
-have to explicitly set it if you use a @code{nnmaildir} server just for
-mairix.)
-
address@hidden
-If you use the Gnus registry: don't use the registry with
address@hidden groups (put them in
address@hidden). Be @emph{extra careful} if
-you use @code{gnus-registry-split-fancy-with-parent}; mails which are
-split into @code{nnmairix} groups are usually gone for good as soon as
-you check the group for new mail (yes, it has happened to me...).
-
address@hidden
-Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix}
-groups (you shouldn't be able to, anyway).
-
address@hidden
-If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize
address@hidden groups (though I have no idea what happens if you do).
-
address@hidden
-mairix does only support us-ascii characters.
-
address@hidden
address@hidden uses a rather brute force method to force Gnus to
-completely reread the group on the mail back end after mairix was
-called---it simply deletes and re-creates the group on the mail
-back end. So far, this has worked for me without any problems, and I
-don't see how @code{nnmairix} could delete other mail groups than its
-own, but anyway: you really should have a backup of your mail
-folders.
-
address@hidden
-All necessary information is stored in the group parameters
-(@pxref{Group Parameters}). This has the advantage that no active file
-is needed, but also implies that when you kill a @code{nnmairix} group,
-it is gone for good.
-
address@hidden
address@hidden nnmairix-purge-old-groups
-If you create and kill a lot of @code{nnmairix} groups, the
-``zz_mairix-*'' groups will accumulate on the mail back end server. To
-delete old groups which are no longer needed, call
address@hidden Note that this assumes that you don't
-save any ``real'' mail in folders of the form
address@hidden<NAME>-<NUMBER>}. You can change the prefix of
address@hidden groups by changing the variable
address@hidden
-
address@hidden
-The following only applies if you @emph{don't} use the mentioned patch
-for mairix (@pxref{Propagating marks}):
-
-A problem can occur when using @code{nnmairix} with maildir folders and
-comes with the fact that maildir stores mail flags like @samp{Seen} or
address@hidden by appending chars @samp{S} and @samp{R} to the message
-file name, respectively. This implies that currently you would have to
-update the mairix database not only when new mail arrives, but also when
-mail flags are changing. The same applies to new mails which are indexed
-while they are still in the @samp{new} folder but then get moved to
address@hidden when Gnus has seen the mail. If you don't update the database
-after this has happened, a mairix query can lead to symlinks pointing to
-non-existing files. In Gnus, these messages will usually appear with
-``(none)'' entries in the header and can't be accessed. If this happens
-to you, using @kbd{G b u} and updating the group will usually fix this.
-
address@hidden itemize
-
@node Misc Group Stuff
@section Misc Group Stuff
@@ -21691,6 +21000,1039 @@
Gnus will try to decay scores once a day. If you haven't run Gnus for
four days, Gnus will decay the scores four times, for instance.
address@hidden Searching
address@hidden Searching
address@hidden searching
+
+FIXME: Add a brief overview of Gnus search capabilities. A brief
+comparison of nnir, nnmairix, contrib/gnus-namazu would be nice
+as well.
+
+This chapter describes tools for searching groups and servers for
+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}.
+
address@hidden
+* nnir:: Searching with various engines.
+* nnmairix:: Searching with Mairix.
address@hidden menu
+
address@hidden nnir
address@hidden nnir
address@hidden nnir
+
+This section describes how to use @code{nnir} to search for articles
+within gnus.
+
address@hidden
+* What is nnir:: What does nnir do?
+* Basic Usage:: How to perform simple searches.
+* Setting up nnir:: How to set up nnir.
address@hidden menu
+
address@hidden What is nnir
address@hidden What is nnir
+
address@hidden is a gnus interface to a number of tools for searching
+through mail and news repositories. Different backends (like
address@hidden and @code{nntp}) work with different tools (called
address@hidden in 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
+created and maintained outside of Gnus.
+
address@hidden Basic Usage
address@hidden Basic Usage
+
+In the group buffer typing @kbd{G G} will search the group on the
+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
+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
address@hidden Even better, the function
address@hidden, bound by default in summary buffers to
address@hidden 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
+will search all the groups under that heading.
+
+Still not enough? OK, in the server buffer
address@hidden (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
address@hidden
+
+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
+groups with different search engines you will be prompted for the
+special search features for each engine separately.
+
address@hidden Setting up nnir
address@hidden 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
address@hidden 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
+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
+query language anyway.
+
address@hidden
+* Associating Engines:: How to associate engines.
+* The imap Engine:: Imap configuration and usage.
+* The gmane Engine:: Gmane configuration and usage.
+* The swish++ Engine:: Swish++ configuration and usage.
+* The swish-e Engine:: Swish-e configuration and usage.
+* The namazu Engine:: Namazu configuration and usage.
+* The hyrex Engine:: Hyrex configuration and usage.
+* Customizations:: User customizable settings.
address@hidden menu
+
address@hidden Associating Engines
address@hidden Associating Engines
+
+
+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
+setting the server variable @code{nnir-search-engine} to the engine
+name. For example to use the @code{namazu} engine to search the server
+named @code{home} you can use
+
address@hidden
+(setq gnus-secondary-select-methods '(
+ (nnml "home"
+ (nnimap-address "localhost")
+ (nnir-search-engine namazu))))
address@hidden 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
+variable is set to use the @code{imap} engine for all servers using the
address@hidden 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
address@hidden for all your servers with an @code{nnimap} backend you
+could change this to
+
address@hidden
+'((nnimap . namazu)
+ (nntp . gmane))
address@hidden lisp
+
address@hidden The imap Engine
address@hidden The imap Engine
+
+The @code{imap} engine requires no configuration.
+
+Queries using the @code{imap} engine follow a simple query language.
+The search is always case-insensitive and supports the following
+features (inspired by the Google search input language):
+
address@hidden @samp
+
address@hidden 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
+operators must be written with all capital letters to be
+recognised. Also preceding a term with a - sign is equivalent to NOT
+term.
+
address@hidden Automatic AND queries
+If you specify multiple words then they will be treated as an AND
+expression intended to match all components.
+
address@hidden Phrase searches
+If you wrap your query in double-quotes then it will be treated as a
+literal string.
+
address@hidden 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
+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
+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
address@hidden 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
address@hidden queries by default
+
address@hidden
+(setq nnir-imap-default-search-key "Imap")
address@hidden lisp
+
address@hidden The gmane Engine
address@hidden The gmane Engine
+
+The @code{gmane} engine requires no configuration.
+
+Gmane queries follow a simple query language:
+
address@hidden @samp
address@hidden 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.
+Note that operators must be written with all capital letters to be
+recognised.
+
address@hidden Required and excluded terms
++ and - can be used to require or exclude terms, e.g. football -american
+
address@hidden Unicode handling
+The search engine converts all text to utf-8, so searching should work
+in any language.
+
address@hidden 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").
+
address@hidden 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
+name (or part of a name) to match.
+
address@hidden The swish++ Engine
address@hidden The swish++ Engine
+
+FIXEM: Say something more here.
+
+Documentation for swish++ may be found at the swish++ sourceforge page:
address@hidden://swishplusplus.sourceforge.net}
+
address@hidden The swish-e Engine
address@hidden The swish-e Engine
+
+FIXEM: Say something more here.
+
+Documentation for swish-e may be found at the swish-e homepage
address@hidden://swish-e.org}
+
address@hidden The namazu Engine
address@hidden The namazu Engine
+
+Using the namazu engine requires creating and maintaining index files.
+One directory should contain all the index files, and nnir must be told
+where to find them by setting the @code{nnir-namazu-index-directory}
+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
+returned by Namazu in order to get a proper group name (albeit with `/'
+instead of `.').
+
+For example, suppose that Namazu returns file names such as
address@hidden/home/john/Mail/mail/misc/42}. For this example, use the
+following setting: @code{(setq nnir-namazu-remove-prefix
+"/home/john/Mail/")} Note the trailing slash. Removing this prefix from
+the directory gives @samp{mail/misc/42}. @code{nnir} knows to remove
+the @samp{/42} and to replace @samp{/} with @samp{.} to arrive at the
+correct group name @samp{mail.misc}.
+
+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
+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:
+
address@hidden
address@hidden
+ package conf; # Don't remove this line!
+
+ # Paths which will not be indexed. Don't use `^' or `$' anchors.
+ $EXCLUDE_PATH = "spam|sent";
+
+ # Header fields which should be searchable. case-insensitive
+ $REMAIN_HEADER = "from|date|message-id|subject";
+
+ # Searchable fields. case-insensitive
+ $SEARCH_FIELD = "from|date|message-id|subject";
+
+ # The max length of a word.
+ $WORD_LENG_MAX = 128;
+
+ # The max length of a field.
+ $MAX_FIELD_LENGTH = 256;
address@hidden example
address@hidden cartouche
+
+For this example, mail is stored in the directories @samp{~/Mail/mail/},
address@hidden/Mail/lists/} and @samp{~/Mail/archive/}, so to index them go to
+the index directory set in @code{nnir-namazu-index-directory} and issue
+the following command:
+
address@hidden
+mknmz --mailnews ~/Mail/archive/ ~/Mail/mail/ ~/Mail/lists/
address@hidden example
+
+For maximum searching efficiency you might want to have a cron job run
+this command periodically, say every four hours.
+
address@hidden The hyrex Engine
address@hidden The hyrex Engine
+FIXME: Add documentation.
+
address@hidden Customizations
address@hidden Custimozations
+
address@hidden @code
+
address@hidden nnir-method-default-engines
+Alist of server backend - search engine pairs. The default associations
+are
address@hidden
+(nnimap . imap)
+(nntp . gmane)
address@hidden example
+
address@hidden nnir-ignored-newsgroups
+A regexp to match newsgroups in the active file that should be skipped
+when searching all groups on a server.
+
address@hidden 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
+three items unique to nnir summary buffers:
+
address@hidden
+%Z Search retrieval score value (integer)
+%G Article original full group name (string)
+%g Article original short group name (string)
address@hidden example
+
+If nil (the default) this will use @code{gnus-summary-line-format}.
+
address@hidden nnir-retrieve-headers-override-function
+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}
+
+If this variable is nil, or if the provided function returns nil for a
+search result, @code{gnus-retrieve-headers} will be called instead."
+
+
address@hidden table
+
+
address@hidden nnmairix
address@hidden nnmairix
+
address@hidden mairix
address@hidden nnmairix
+This paragraph describes how to set up mairix and the back end
address@hidden for indexing and searching your mail from within
+Gnus. Additionally, you can create permanent ``smart'' groups which are
+bound to mairix searches and are automatically updated.
+
address@hidden
+* About mairix:: About the mairix mail search engine
+* nnmairix requirements:: What you will need for using nnmairix
+* What nnmairix does:: What does nnmairix actually do?
+* Setting up mairix:: Set up your mairix installation
+* Configuring nnmairix:: Set up the nnmairix back end
+* nnmairix keyboard shortcuts:: List of available keyboard shortcuts
+* Propagating marks:: How to propagate marks from nnmairix groups
+* nnmairix tips and tricks:: Some tips, tricks and examples
+* nnmairix caveats:: Some more stuff you might want to know
address@hidden menu
+
address@hidden FIXME: The markup in this section might need improvement.
address@hidden E.g. adding @samp, @var, @file, @command, etc.
address@hidden Cf. (info "(texinfo)Indicating")
+
address@hidden About mairix
address@hidden 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
+runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can
+be found at
address@hidden://www.rpcurnow.force9.co.uk/mairix/index.html}
+
+Though mairix might not be as flexible as other search tools like
+swish++ or namazu, which you can use via the @code{nnir} back end, it
+has the prime advantage of being incredibly fast. On current systems, it
+can easily search through headers and message bodies of thousands and
+thousands of mails in well under a second. Building the database
+necessary for searching might take a minute or two, but only has to be
+done once fully. Afterwards, the updates are done incrementally and
+therefore are really fast, too. Additionally, mairix is very easy to set
+up.
+
+For maximum speed though, mairix should be used with mails stored in
address@hidden or @code{MH} format (this includes the @code{nnml} back
+end), although it also works with mbox. Mairix presents the search
+results by populating a @emph{virtual} maildir/MH folder with symlinks
+which point to the ``real'' message files (if mbox is used, copies are
+made). Since mairix already presents search results in such a virtual
+mail folder, it is very well suited for using it as an external program
+for creating @emph{smart} mail folders, which represent certain mail
+searches.
+
address@hidden nnmairix requirements
address@hidden nnmairix requirements
+
+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.
+
+Additionally, @code{nnmairix} only supports the following Gnus back
+ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use
+one of these back ends for using @code{nnmairix}. Other back ends, like
address@hidden, @code{nnfolder} or @code{nnmh}, won't work.
+
+If you absolutely must use mbox and still want to use @code{nnmairix},
+you can set up a local @acronym{IMAP} server, which you then access via
address@hidden This is a rather massive setup for accessing some mbox
+files, so just change to MH or Maildir already... However, if you're
+really, really passionate about using mbox, you might want to look into
+the package @file{mairix.el}, which comes with Emacs 23.
+
address@hidden What nnmairix does
address@hidden What nnmairix does
+
+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
+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
+automatically update themselves by calling mairix.
+
+You might ask why you need @code{nnmairix} at all, since mairix already
+creates the group, populates it with links to the mails so that you can
+then access it with Gnus, right? Well, this @emph{might} work, but often
+does not---at least not without problems. Most probably you will get
+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
+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.
+
address@hidden is not really a mail back end---it's actually more like
+a wrapper, sitting between a ``real'' mail back end where mairix stores
+the searches and the Gnus front end. You can choose between three
+different mail back ends for the mairix folders: @code{nnml},
address@hidden or @code{nnimap}. @code{nnmairix} will call the mairix
+binary so that the search results are stored in folders named
address@hidden<NAME>-<NUMBER>} on this mail back end, but it will
+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
address@hidden 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
+mairix remotely on an IMAP server with @code{nnimap}---here the mairix
+folders and your other mail must be on the same @code{nnimap} back end.
+
address@hidden Setting up mairix
address@hidden Setting up mairix
+
+First: create a backup of your mail folders (@pxref{nnmairix caveats}).
+
+Setting up mairix is easy: simply create a @file{.mairixrc} file with
+(at least) the following entries:
+
address@hidden
+# Your Maildir/MH base folder
+base=~/Maildir
address@hidden example
+
+This is the base folder for your mails. All the following directories
+are relative to this base folder. If you want to use @code{nnmairix}
+with @code{nnimap}, this base directory has to point to the mail
+directory where the @acronym{IMAP} server stores the mail folders!
+
address@hidden
+maildir= ... your maildir folders which should be indexed ...
+mh= ... your nnml/mh folders which should be indexed ...
+mbox = ... your mbox files which should be indexed ...
address@hidden example
+
+This specifies all your mail folders and mbox files (relative to the
+base directory!) you want to index with mairix. Note that the
address@hidden back end saves mails in MH format, so you have to put those
+directories in the @code{mh} line. See the example at the end of this
+section and mairixrc's man-page for further details.
+
address@hidden
+omit=zz_mairix-*
address@hidden example
+
address@hidden nnmairix-group-prefix
+This should make sure that you don't accidentally index the mairix
+search results. You can change the prefix of these folders with the
+variable @code{nnmairix-group-prefix}.
+
address@hidden
+mformat= ... 'maildir' or 'mh' ...
+database= ... location of database file ...
address@hidden example
+
+The @code{format} setting specifies the output format for the mairix
+search folder. Set this to @code{mh} if you want to access search results
+with @code{nnml}. Otherwise choose @code{maildir}.
+
+To summarize, here is my shortened @file{.mairixrc} file as an example:
+
address@hidden
+base=~/Maildir
+maildir=.personal:.work:.logcheck:.sent
+mh=../Mail/nnml/*...
+mbox=../mboxmail/mailarchive_year*
+mformat=maildir
+omit=zz_mairix-*
+database=~/.mairixdatabase
address@hidden example
+
+In this case, the base directory is @file{~/Maildir}, where all my Maildir
+folders are stored. As you can see, the folders are separated by
+colons. If you wonder why every folder begins with a dot: this is
+because I use Dovecot as @acronym{IMAP} server, which again uses
address@hidden folders. For testing nnmairix, I also have some
address@hidden mail, which is saved in @file{~/Mail/nnml}. Since this has
+to be specified relative to the @code{base} directory, the @code{../Mail}
+notation is needed. Note that the line ends in @code{*...}, which means
+to recursively scan all files under this directory. Without the three
+dots, the wildcard @code{*} will not work recursively. I also have some
+old mbox files with archived mail lying around in @file{~/mboxmail}.
+The other lines should be obvious.
+
+See the man page for @code{mairixrc} for details and further options,
+especially regarding wildcard usage, which may be a little different
+than you are used to.
+
+Now simply call @code{mairix} to create the index for the first time.
+Note that this may take a few minutes, but every following index will do
+the updates incrementally and hence is very fast.
+
address@hidden Configuring nnmairix
address@hidden Configuring nnmairix
+
+In group mode, type @kbd{G b c}
+(@code{nnmairix-create-server-and-default-group}). This will ask you for all
+necessary information and create a @code{nnmairix} server as a foreign
+server. You will have to specify the following:
+
address@hidden @bullet
+
address@hidden
+The @strong{name} of the @code{nnmairix} server---choose whatever you
+want.
+
address@hidden
+The name of the @strong{back end server} where mairix should store its
+searches. This must be a full server name, like @code{nnml:mymail}.
+Just hit @kbd{TAB} to see the available servers. Currently, servers
+which are accessed through @code{nnmaildir}, @code{nnimap} and
address@hidden 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}
+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
address@hidden to @code{nil}, or you might lose mail
+(@pxref{nnmairix caveats}). If you want to use mairix remotely on an
address@hidden server, you have to choose the corresponding
address@hidden server here.
+
address@hidden
address@hidden 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
address@hidden server. If you want to add some default options to
+mairix, you could do this here, but better use the variable
address@hidden instead.
+
address@hidden
+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
+are not bound to permanent @code{nnmairix} groups. Choose whatever you
+like.
+
address@hidden
+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
+folders (=beginning with a dot). For example, you have to answer
address@hidden here if you work with the Dovecot @acronym{IMAP}
+server. Otherwise, you should answer @samp{no} here.
+
address@hidden itemize
+
address@hidden nnmairix keyboard shortcuts
address@hidden nnmairix keyboard shortcuts
+
+In group mode:
+
address@hidden @kbd
+
address@hidden G b c
address@hidden G b c (Group)
address@hidden nnmairix-create-server-and-default-group
+Creates @code{nnmairix} server and default search group for this server
+(@code{nnmairix-create-server-and-default-group}). You should have done
+this by now (@pxref{Configuring nnmairix}).
+
address@hidden G b s
address@hidden G b s (Group)
address@hidden nnmairix-search
+Prompts for query which is then sent to the mairix binary. Search
+results are put into the default search group which is automatically
+displayed (@code{nnmairix-search}).
+
address@hidden G b m
address@hidden G b m (Group)
address@hidden nnmairix-widget-search
+Allows you to create a mairix search or a permanent group more
+comfortably using graphical widgets, similar to a customization
+group. Just try it to see how it works (@code{nnmairix-widget-search}).
+
address@hidden G b i
address@hidden G b i (Group)
address@hidden nnmairix-search-interactive
+Another command for creating a mairix query more comfortably, but uses
+only the minibuffer (@code{nnmairix-search-interactive}).
+
address@hidden G b g
address@hidden G b g (Group)
address@hidden nnmairix-create-search-group
+Creates a permanent group which is associated with a search query
+(@code{nnmairix-create-search-group}). The @code{nnmairix} back end
+automatically calls mairix when you update this group with @kbd{g} or
address@hidden
+
address@hidden G b q
address@hidden G b q (Group)
address@hidden nnmairix-group-change-query-this-group
+Changes the search query for the @code{nnmairix} group under cursor
+(@code{nnmairix-group-change-query-this-group}).
+
address@hidden G b t
address@hidden G b t (Group)
address@hidden nnmairix-group-toggle-threads-this-group
+Toggles the 'threads' parameter for the @code{nnmairix} group under cursor,
+i.e. if you want see the whole threads of the found messages
+(@code{nnmairix-group-toggle-threads-this-group}).
+
address@hidden G b u
address@hidden G b u (Group)
address@hidden nnmairix-update-database
address@hidden nnmairix-mairix-update-options
+Calls mairix binary for updating the database
+(@code{nnmairix-update-database}). The default parameters are @code{-F}
+and @code{-Q} for making this as fast as possible (see variable
address@hidden for defining these default
+options).
+
address@hidden G b r
address@hidden G b r (Group)
address@hidden nnmairix-group-toggle-readmarks-this-group
+Keep articles in this @code{nnmairix} group always read or unread, or leave the
+marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}).
+
address@hidden G b d
address@hidden G b d (Group)
address@hidden nnmairix-group-delete-recreate-this-group
+Recreate @code{nnmairix} group on the ``real'' mail back end
+(@code{nnmairix-group-delete-recreate-this-group}). You can do this if
+you always get wrong article counts with a @code{nnmairix} group.
+
address@hidden G b a
address@hidden G b a (Group)
address@hidden nnmairix-group-toggle-allowfast-this-group
+Toggles the @code{allow-fast} parameters for group under cursor
+(@code{nnmairix-group-toggle-allowfast-this-group}). The default
+behavior of @code{nnmairix} is to do a mairix search every time you
+update or enter the group. With the @code{allow-fast} parameter set,
+mairix will only be called when you explicitly update the group, but not
+upon entering. This makes entering the group faster, but it may also
+lead to dangling symlinks if something changed between updating and
+entering the group which is not yet in the mairix database.
+
address@hidden G b p
address@hidden G b p (Group)
address@hidden nnmairix-group-toggle-propmarks-this-group
+Toggle marks propagation for this group
+(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating
+marks}).
+
address@hidden G b o
address@hidden G b o (Group)
address@hidden nnmairix-propagate-marks
+Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when
address@hidden is set to @code{nil}.
+
address@hidden table
+
+In summary mode:
+
address@hidden @kbd
+
address@hidden $ m
address@hidden $ m (Summary)
address@hidden nnmairix-widget-search-from-this-article
+Allows you to create a mairix query or group based on the current
+message using graphical widgets (same as @code{nnmairix-widget-search})
+(@code{nnmairix-widget-search-from-this-article}).
+
address@hidden $ g
address@hidden $ g (Summary)
address@hidden nnmairix-create-search-group-from-message
+Interactively creates a new search group with query based on the current
+message, but uses the minibuffer instead of graphical widgets
+(@code{nnmairix-create-search-group-from-message}).
+
address@hidden $ t
address@hidden $ t (Summary)
address@hidden nnmairix-search-thread-this-article
+Searches thread for the current article
+(@code{nnmairix-search-thread-this-article}). This is effectively a
+shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the
+current article and enabled threads.
+
address@hidden $ f
address@hidden $ f (Summary)
address@hidden nnmairix-search-from-this-article
+Searches all messages from sender of the current article
+(@code{nnmairix-search-from-this-article}). This is a shortcut for
+calling @code{nnmairix-search} with @samp{f:From}.
+
address@hidden $ o
address@hidden $ o (Summary)
address@hidden nnmairix-goto-original-article
+(Only in @code{nnmairix} groups!) Tries determine the group this article
+originally came from and displays the article in this group, so that
+e.g. replying to this article the correct posting styles/group
+parameters are applied (@code{nnmairix-goto-original-article}). This
+function will use the registry if available, but can also parse the
+article file name as a fallback method.
+
address@hidden $ u
address@hidden $ u (Summary)
address@hidden nnmairix-remove-tick-mark-original-article
+Remove possibly existing tick mark from original article
+(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix
+tips and tricks}).
+
address@hidden table
+
address@hidden Propagating marks
address@hidden Propagating marks
+
+First of: you really need a patched mairix binary for using the marks
+propagation feature efficiently. Otherwise, you would have to update
+the mairix database all the time. You can get the patch at
+
address@hidden://www.randomsample.de/mairix-maildir-patch.tar}
+
+You need the mairix v0.21 source code for this patch; everything else
+is explained in the accompanied readme file. If you don't want to use
+marks propagation, you don't have to apply these patches, but they also
+fix some annoyances regarding changing maildir flags, so it might still
+be useful to you.
+
+With the patched mairix binary, you can use @code{nnmairix} as an
+alternative to mail splitting (@pxref{Fancy Mail Splitting}). For
+example, instead of splitting all mails from @samp{david@@foobar.com}
+into a group, you can simply create a search group with the query
address@hidden:david@@foobar.com}. This is actually what ``smart folders'' are
+all about: simply put everything in one mail folder and dynamically
+create searches instead of splitting. This is more flexible, since you
+can dynamically change your folders any time you want to. This also
+implies that you will usually read your mails in the @code{nnmairix}
+groups instead of your ``real'' mail groups.
+
+There is one problem, though: say you got a new mail from
address@hidden@@foobar.com}; it will now show up in two groups, the
+``real'' group (your INBOX, for example) and in the @code{nnmairix}
+search group (provided you have updated the mairix database). Now you
+enter the @code{nnmairix} group and read the mail. The mail will be
+marked as read, but only in the @code{nnmairix} group---in the ``real''
+mail group it will be still shown as unread.
+
+You could now catch up the mail group (@pxref{Group Data}), but this is
+tedious and error prone, since you may overlook mails you don't have
+created @code{nnmairix} groups for. Of course, you could first use
address@hidden (@pxref{nnmairix keyboard
+shortcuts}) and then read the mail in the original group, but that's
+even more cumbersome.
+
+Clearly, the easiest way would be if marks could somehow be
+automatically set for the original article. This is exactly what
address@hidden propagation} is about.
+
+Marks propagation is deactivated by default. You can activate it for a
+certain @code{nnmairix} group with
address@hidden (bound to @kbd{G b
+p}). This function will warn you if you try to use it with your default
+search group; the reason is that the default search group is used for
+temporary searches, and it's easy to accidentally propagate marks from
+this group. However, you can ignore this warning if you really want to.
+
+With marks propagation enabled, all the marks you set in a @code{nnmairix}
+group should now be propagated to the original article. For example,
+you can now tick an article (by default with @kbd{!}) and this mark should
+magically be set for the original article, too.
+
+A few more remarks which you may or may not want to know:
+
address@hidden nnmairix-propagate-marks-upon-close
+Marks will not be set immediately, but only upon closing a group. This
+not only makes marks propagation faster, it also avoids problems with
+dangling symlinks when dealing with maildir files (since changing flags
+will change the file name). You can also control when to propagate marks
+via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for
+details).
+
+Obviously, @code{nnmairix} will have to look up the original group for every
+article you want to set marks for. If available, @code{nnmairix} will first use
+the registry for determining the original group. The registry is very
+fast, hence you should really, really enable the registry when using
+marks propagation. If you don't have to worry about RAM and disc space,
+set @code{gnus-registry-max-entries} to a large enough value; to be on
+the safe side, choose roughly the amount of mails you index with mairix.
+
address@hidden nnmairix-only-use-registry
+If you don't want to use the registry or the registry hasn't seen the
+original article yet, @code{nnmairix} will use an additional mairix
+search for determining the file name of the article. This, of course, is
+way slower than the registry---if you set hundreds or even thousands of
+marks this way, it might take some time. You can avoid this situation by
+setting @code{nnmairix-only-use-registry} to t.
+
+Maybe you also want to propagate marks the other way round, i.e. if you
+tick an article in a "real" mail group, you'd like to have the same
+article in a @code{nnmairix} group ticked, too. For several good
+reasons, this can only be done efficiently if you use maildir. To
+immediately contradict myself, let me mention that it WON'T work with
address@hidden, since @code{nnmaildir} stores the marks externally and
+not in the file name. Therefore, propagating marks to @code{nnmairix}
+groups will usually only work if you use an IMAP server which uses
+maildir as its file format.
+
address@hidden nnmairix-propagate-marks-to-nnmairix-groups
+If you work with this setup, just set
address@hidden to @code{t} and see what
+happens. If you don't like what you see, just set it to @code{nil} again. One
+problem might be that you get a wrong number of unread articles; this
+usually happens when you delete or expire articles in the original
+groups. When this happens, you can recreate the @code{nnmairix} group on the
+back end using @kbd{G b d}.
+
address@hidden nnmairix tips and tricks
address@hidden nnmairix tips and tricks
+
address@hidden
address@hidden
+Checking Mail
+
address@hidden nnmairix-update-groups
+I put all my important mail groups at group level 1. The mairix groups
+have group level 5, so they do not get checked at start up (@pxref{Group
+Levels}).
+
+I use the following to check for mails:
+
address@hidden
+(defun my-check-mail-mairix-update (level)
+ (interactive "P")
+ ;; if no prefix given, set level=1
+ (gnus-group-get-new-news (or level 1))
+ (nnmairix-update-groups "mairixsearch" t t)
+ (gnus-group-list-groups))
+
+(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update)
address@hidden lisp
+
+Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix}
+server. See the doc string for @code{nnmairix-update-groups} for
+details.
+
address@hidden
+Example: search group for ticked articles
+
+For example, you can create a group for all ticked articles, where the
+articles always stay unread:
+
+Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use
address@hidden:f} as query and do not include threads.
+
+Now activate marks propagation for this group by using @kbd{G b p}. Then
+activate the always-unread feature by using @kbd{G b r} twice.
+
+So far so good---but how do you remove the tick marks in the @code{nnmairix}
+group? There are two options: You may simply use
address@hidden (bound to @kbd{$ u}) to remove
+tick marks from the original article. The other possibility is to set
address@hidden to @code{t}, but see the above
+comments about this option. If it works for you, the tick marks should
+also exist in the @code{nnmairix} group and you can remove them as usual,
+e.g. by marking an article as read.
+
+When you have removed a tick mark from the original article, this
+article should vanish from the @code{nnmairix} group after you have updated the
+mairix database and updated the group. Fortunately, there is a function
+for doing exactly that: @code{nnmairix-update-groups}. See the previous code
+snippet and the doc string for details.
+
address@hidden
+Dealing with auto-subscription of mail groups
+
+As described before, all @code{nnmairix} groups are in fact stored on
+the mail back end in the form @samp{zz_mairix-<NAME>-<NUMBER>}. You can
+see them when you enter the back end server in the server buffer. You
+should not subscribe these groups! Unfortunately, these groups will
+usually get @emph{auto-subscribed} when you use @code{nnmaildir} or
address@hidden, i.e. you will suddenly see groups of the form
address@hidden pop up in your group buffer. If this happens to you,
+simply kill these groups with C-k. For avoiding this, turn off
+auto-subscription completely by setting the variable
address@hidden to @code{nil} (@pxref{Filtering New
+Groups}), or if you like to keep this feature use the following kludge
+for turning it off for all groups beginning with @samp{zz_}:
+
address@hidden
+(setq gnus-auto-subscribed-groups
+
"^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*")
address@hidden lisp
+
address@hidden itemize
+
address@hidden nnmairix caveats
address@hidden nnmairix caveats
+
address@hidden
address@hidden
+You can create a secondary @code{nnml} server just for nnmairix, but then
+you have to explicitly set the corresponding server variable
address@hidden to @code{nil}. Otherwise, new mail might get
+put into this secondary server (and would never show up again). Here's
+an example server definition:
+
address@hidden
+(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil))
address@hidden lisp
+
+(The @code{nnmaildir} back end also has a server variabe
address@hidden, but its default value is @code{nil}, so you don't
+have to explicitly set it if you use a @code{nnmaildir} server just for
+mairix.)
+
address@hidden
+If you use the Gnus registry: don't use the registry with
address@hidden groups (put them in
address@hidden). Be @emph{extra careful} if
+you use @code{gnus-registry-split-fancy-with-parent}; mails which are
+split into @code{nnmairix} groups are usually gone for good as soon as
+you check the group for new mail (yes, it has happened to me...).
+
address@hidden
+Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix}
+groups (you shouldn't be able to, anyway).
+
address@hidden
+If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize
address@hidden groups (though I have no idea what happens if you do).
+
address@hidden
+mairix does only support us-ascii characters.
+
address@hidden
address@hidden uses a rather brute force method to force Gnus to
+completely reread the group on the mail back end after mairix was
+called---it simply deletes and re-creates the group on the mail
+back end. So far, this has worked for me without any problems, and I
+don't see how @code{nnmairix} could delete other mail groups than its
+own, but anyway: you really should have a backup of your mail
+folders.
+
address@hidden
+All necessary information is stored in the group parameters
+(@pxref{Group Parameters}). This has the advantage that no active file
+is needed, but also implies that when you kill a @code{nnmairix} group,
+it is gone for good.
+
address@hidden
address@hidden nnmairix-purge-old-groups
+If you create and kill a lot of @code{nnmairix} groups, the
+``zz_mairix-*'' groups will accumulate on the mail back end server. To
+delete old groups which are no longer needed, call
address@hidden Note that this assumes that you don't
+save any ``real'' mail in folders of the form
address@hidden<NAME>-<NUMBER>}. You can change the prefix of
address@hidden groups by changing the variable
address@hidden
+
address@hidden
+The following only applies if you @emph{don't} use the mentioned patch
+for mairix (@pxref{Propagating marks}):
+
+A problem can occur when using @code{nnmairix} with maildir folders and
+comes with the fact that maildir stores mail flags like @samp{Seen} or
address@hidden by appending chars @samp{S} and @samp{R} to the message
+file name, respectively. This implies that currently you would have to
+update the mairix database not only when new mail arrives, but also when
+mail flags are changing. The same applies to new mails which are indexed
+while they are still in the @samp{new} folder but then get moved to
address@hidden when Gnus has seen the mail. If you don't update the database
+after this has happened, a mairix query can lead to symlinks pointing to
+non-existing files. In Gnus, these messages will usually appear with
+``(none)'' entries in the header and can't be accessed. If this happens
+to you, using @kbd{G b u} and updating the group will usually fix this.
+
address@hidden itemize
+
@iftex
@iflatex
@chapter Message
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r102651: gnus.texi (Filtering New Groups): Mention.,
Katsumi Yamaoka <=