;-*- outline -*-

"swish++ -- A Mail Indexing System for Humans"

* swish++ + Email
  Swish++ is great for indexing and later, of course, searching and
  retrieving your old emails.

!!! Swish++ searches on a per file basis, so its use only makes sense
    with one-file-per-message systems (like Maildir, gnus nnml, mh ... and
    not with mbox based storage -- use grepmail instead or just switch
    your mail system, especially with a high volume of archived messages)

** Indexing of emails

swish++ provides a specific module for this purpose

*** index example:

pwd = ~/Mail
index++  -v3 -s stop_words  -e 'mail:*' -E 'Incomin*' -E '*~'
./archive ./Ich ./drafts ./maintainer ./maintainer-debian

-e denotes the module, -E excludes file-pattern and -s indicates a
 specific stop word file 

(man index++)  

*** cron

    If you want always "fresh" indexes you need the help of cron.

**** cron sample

41 06 * * * /usr/bin/index++ -s /home/YOU/Mail/stop_words  -e 'mail:*' -E \
'Incomin*' -E '*~' -E '*.alt' \
--config-file=/home/YOU/Mail/swish++.config \
--index-file=/home/YOU/Mail/swish++.index /home/YOU/Mail/archive /home/YOU/Mail/Ich /home/YOU/Mail/drafts /home/YOU/Mail/maintainer 2>&1

"Index every day at 6:41 the mentioned directories (recursively - the
default) use a config-file and create the index in /home/YOU/Mail; use
the mail module (-e 'mail:*') and don't index certain patterns (-E
...)."

	Or put the whole command as a script and execute it from cron:

41 06 * * * /home/YOU/cron_swish++.sh 2>&1
  

*** search example: 
	  >search++ from = mhummel and swish
	  # results: 9
	  100 ./Ich/930 1175 Indexing
	   58 ./selber/254 1110 Bug#88974 ITA: swish++ -- Simple Web Indexing System for 
	   47 ./selber/301 3270 Re: Bug#129390: swish++: index++ gets a segmentation fault           41 ./selber/338 939 Indexing
	   [...]

	   Though this is already quite useful, it doesn't signify the whole
	   comfort. I bet you want to read the rediscovered email with your
	   favorite mail reader. 

	   (for search++ options s. man search++ , of course)


* Mail Reader Integration of swish++

** Integration with emacs + gnus + nnir

*** How to use emacs? 

    Get one year of vacancy and have some kind of remote approach to this digital
    epos.

*** How to use gnus?

    See above ...

*** gnus + nnir + swish++

    In the examples directory you'll find a patched version of nnir.el
    (Maybe the small patch will be included at the time you are reading
    this.)

**** nnml-back-ends and nnir

***** put nnir.el in your load-path

***** Add the following to your ~/.gnus init-file

    (setq nnir-search-engine 'swish++)
    ;;the following are the default values
    (setq  nnir-swish++-program "search++") ; the search executable in Debian
    ;(setq nnir-swish++-index-file "/home/YOU/Mail/swish++.index");
    ;the index location mail is stored in ~/Mail normally -- the default

    (Have a look at Kai's commentaries in nnir.el
    Maybe you have to set 'nnir-mail-back-end' but with nnml -- and
    having nnml as the default gnus-select-method -- the default is
    fine)

***** Interaction within gnus

      Type G G and you will be prompted for a query (enter the same as with plain
      search++ at the command line).

      The search results will form a new group.

      Further try G T and enjoy

** Integration with mutt

   mutt supports the Maildir format and mh
   (http://www.reedmedia.net/misc/mail/mailbox-formats.html and
   http://www.courier-mta.org/mbox-vs-maildir/#intro1) well; you don't
   need to install qmail to be able to work with maildirs, not even
   the MTA needs maildir support s. procmail (even Mail::Audit does
   the right thing, discovering a maildir, and accepts to the
   Maildir/new directory).


*** swishmutt.sh

    (Caveat: You need the procmail package installed -- for the mbox
    formatter)
  
    Copy this script to your ~/bin/ directory (or, of course adapt the
    settings to your needs)
    It's just an example of how you could parse the swish++ results
    for mutt. But checking and adapting the variables it should
    work out of the box. 
    Add something like:
    
    macro index "\ch" "!~/bin/swishmutt.sh\nc=sqmbox.tmp\n"

    folder-hook sqmbox.tmp set sort=mailbox-order


    to your .muttrc file. (Make sure that mutt actually finds the
    temporary mbox : sqmbox.tmp -- the script assumes
    ~/mail/sqmbox.tmp)
    
    The folder-hook is necessary to conserve the search ranking. (The
    mailbox order is OK, so no mess with date_sent and the like.) 

**** Interaction within mutt

     The macro works from within a mail folder. Just press Ctrl-h and
     you will be prompted for a query.
     Then if everything works fine you will enter a temporary mbox
     with the emails ordered corresponding with the search++ results. 
     

MH <mhummel@debian.org>