Revised README file

[David Relson]

Hi,

Y'all asked for a better README.  Here's the result.

Feel free to comment.  

Even better, revise/rewrite/add sections.

David

--------------------------------------------------------------
		Bogofilter -- fast Bayesian spam filtering

# $Id: README,v 1.11 2004/06/27 15:58:58 relson Exp $

Summary:

1. What is Bogofilter?
2. Documentation
3. Building Bogofilter.
4. How to contribute
5. How to request features
6. Installing Bogofilter from source tarball or CVS
  a. Downloading
  b. Installing
  c. Configuring
  d. Changing Bogofilter



1. What is Bogofilter?
----------------------

Bogofilter is a fast Bayesian spam filtering, which implements a fast
Bayesian spam filter along the lines suggested by Paul Graham in his
article "A Plan For Spam":

  http://www.paulgraham.com/spam.html

with algorithmic changes suggested by Gary Robinson in

  http://radio.weblogs.com/0101454/stories/2002/09/16/spamDetection.html

and in "A Statistical Approach to the Spam Problem"

  http://www.linuxjournal.com/article.php?sid=6467

This version improves on the papers by doing smarter lexical analysis.
In particular, hostames and IP addresses are retained as recognition
features rather than broken up. Various kinds of MTA cruft such as
dates and message-IDs are discarded so as not to bloat the word lists.



2. Documentation
----------------

It is recommended, although not necessary, that you install the GNU
Scientific Library (GSL) version 1.4 or newer before configuring
bogofilter. This allows bogofilter to link dynamically against a
system-wide GSL rather than statically against a shipped GSL subset,
conserving memory and disk space.

When installed, there are man pages for bogofilter, bogoutil,
bogolexer, and bogoupgrade.  Additional documentation is in
/usr/share/doc/bogofilter-x.y.z or comparable directory (depending on
your operating system).

If you've installed the source code, the  doc directory and its
subdirectories contain most of bogofilter's documentation.  In it are
a variety of README files, the xml originals for the man pages , and
other documents.  Additionally, many of the directories in the
bogofilter hierarchy have their own README files.

If you use mutt, see the bogofilter(1) manual page for helpful macros
you can add to your .muttrc.



3. Building Bogofilter
----------------------

When updating, check the RELEASE.NOTES files.

For fresh installs, check the rest of this file and the INSTALL file.

You can safely ignore any of these compile time warnings:

warning: unused parameter ...
warning: format not a string literal, argument types not checked



3. How to contribute
--------------------

The best way to contribute to bogofilter is through the bogofilter
mailing list, bogofilter at bogofilter.org.  You can subscribe to it by
sending a message to bogofilter-subscribe at bogofilter.org and
responding to the confirmation message it sends to you.  More
information is available on the bogofilter home page at
http://bogofilter.sourceforge.net 

Bugs can be reported via the bogfilter mailing list or through
http://sourceforge.net/tracker/?atid=499997&group_id=62265&func=browse

If you have code to contribute, please post it on the bogofilter
mailing list or mail it to David Relson (relson at users.sourceforge.net)



5. How to request features
--------------------------

Ask around in the bogofilter mailing list.  The idea may have been
already suggested, considered, accepted, rejected, ...  You won't know
until you ask!

Alternatively, you might want to hack at the code and develop the
feature on your own, which would be great!  You can then send a patch
to the list.



6. Installing Bogofilter from CVS
---------------------------------

  a. Downloading
  --------------

  The most recent version of this software is available at: 

	http://sourceforge.net/projects/bogofilter/

  The latest stable version can be downloaded.  The development source
  is in a CVS repository on SourceForge.  To download the latest cvs
  source, cd to the directory to which you wish to download and type
  the following commands:

  cvs -d:pserver:anonymous at cvs.sourceforge.net:/cvsroot/bogofilter login

  When prompted for a password press the RETURN key.
  After anonymously logging in:

  cvs -z3 -d:pserver:anonymous at cvs.sourceforge.net:/cvsroot/bogofilter
co bogofilter

  b. Installing
  -------------

  To compile and install the standard configuration, use the following
  commands:

  cd bogofilter		[change to project directory]
  ./autogen.sh		[add configure options as required]
  make
  make install		[as root]

  You will need a full set of development tools installed to be able
  to run autogen.sh, including recent automake (1.7) and autoconf
  (2.5X).

  c. Configuring
  --------------

  After using ./autogen.sh, which builds the standard configuration
  and runs "make check" to ensure it works in your environment and on
  your hardware, you might wish to further customize bogofilter for
  your use.

  Running "./configure --help" will list all the configuration
  options.  The most notable ones are:

  --prefix=PREFIX         install architecture-independent files in
PREFIX
			  [default: /usr/local]
  --with-database=ENGINE  Choose database engine {db|tdb|qdbm} 
  			  [default: db]
  --with-libdb-prefix[=DIR]  search for libdb in DIR/include and DIR/lib


  d. Changing Bogofilter
  ----------------------

  If you make modifications to bogofilter, you may need to have a
  recent DocBook XML tool chain, the xmlto program, PassiveTeX and
  XMLTeX, recent versions of automake (1.7) and autoconf (2.5X).

  These requirements do not apply if you are building an unmodified
  tarball.