
To build and install this program on Unix-like systems:

    1.  cd to the directory in which you unpacked this distribution.

    2.  Configure the program for your system by running:
            ./configure
        This will create a Makefile and config.h appropriate for
        your system.

    3.  Build the program with:
            make

    4.  Test the results with:
            make check
	    
    5.	Install the program in the default location of
    	.annoyance-filter in your home directory.
	    make install

This program is a user application, not intended to be
installed as a system-wide utility.  The "make install" target
installs the program in a directory named .annoyance-filter
(which it creates if necessary) in the user's home directory. 
Before using the program to filter mail, it must be "trained"
with collections of pre-sorted junk and non-junk mail to create
the dictionary it uses to classify incoming messages.  This
dictionary should be installed in the $HOME/.annoyance-filter
directory as "dict.bin".

To train the program, let's assume you have a collection of
known legitimate mail in a Unix mail folder (just a bunch of
individual mail messages concatenated together in a text file)
called t-mail and a collection of junk in a file named t-junk.
You can scan these files are create your custom dict.bin dictionary
file with:

    ./annoyance-filter --mail t-mail --junk t-junk --prune --write dict.bin
    
and then install the dictionary for classifying incoming mail
with:

    cp -p dict.bin $HOME/.annoyance-filter
    
In the training phase, annoyance-filter can read either Unix mail
folders containing multiple concatenated messages or individual
messages within a directory given as as the --mail or --junk argument.
In either case, folders or messages compressed with gzip will be
automatically expanded.

Now that you have the dictionary created during the training phase,
you can test a message in a file, for example, incoming.txt, with
the command:

    ./annoyance-filter --read dict.bin --test incoming.txt
    
The probability the message is junk will be written to standard
output.  For additional details, including a list of the words
annoyance-filter used to classify the message, specify the
--verbose option before the --test command.

If your experiments with annoyance-filter indicate it's
sufficiently accurate to sort your own mail, see the instructions
for "Integrating with PROCMAIL" in the annoyance-filter.pdf
document; this explains how to deploy annoyance-filter as a
front end to Procmail and use its classifications to direct
Procmail to route messages accordingly.

If you're running on a non-Unix system, at the moment the
entire question of integration of annoyance-filter with
your mail tools is very much a research project.  annoyance-filter
is a standard C++ program--there should be no difficulty building it
on any ISO/IEC 14882 environment.  But the devil is in the
details, and there are lots of details in the typical mail
pipeline for the cloven hoof and pitchfork crowd to seize on.
If you've the expertise required to integrate such a filter into
mail clients which can't run Procmail, why not jump in and help
make this happen?  Send mail to bugs@fourmilab.ch with the text
"annoyance-filter" in the subject line to volunteer.
