		Bogofilter -- fast Bayesian spam filtering

Summary:

0. Important
1. What is Bogofilter?
2. Documentation
3. Installing Bogofilter
4. How to contribute
5. How to request features
6. Building & Installing Bogofilter from Source Tarball or Git
  a. Downloading
  b. Building & Installing
  c. Configuring
  d. Changing Bogofilter
7. License


0. IMPORTANT
------------

If you are updating a database driver from one major release version (of the
database) to the next, you may need to dump all your wordlist databases
*before* the upgrade of the database library and then re-load them after the
database version upgrade.  The bogoutil utility can dump and load databases,
so you can:

FOR EACH wordlist (replace .db by the DB-specific suffix, f.i. .lmdb!)
bogoutil -d path/to/wordlist.db >path/to/wordlist.txt

THEN upgrade your database library and reinstall bogofilter
(or install bogofilter with an entirely different database)

THEN FOR EACH wordlist (again, replace the suffix):
bogoutil -l path/to/wordlist.db <path/to/wordlist.txt

This is needed for LMDB upgrades from 0.9.x to 1.0, and for many
Oracle/Berkeley DB upgrades!


If you are using bogofilter with the Berkeley DB data base library,
do read the doc/README.db file, it contains important information.
It no longer is the default database because the new owner makes it
immensely hard to obtain patches for the database drivers and has
changed licensing conditions.


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

Bogofilter is 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":

  https://www.linuxjournal.com/article/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. Installing 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


4. How to contribute
--------------------

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

Bugs can be reported via the bogfilter mailing list or through the
issue trackers:
https://gitlab.com/bogofilter/bogofilter/issues
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 file it to one of the issue trackers (Gitlab preferred).


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. Building & Installing Bogofilter from Source Tarball or Git
--------------------------------------------------------------

  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 Subversion repository on SourceForge.  To download the latest Git
  source, cd to the directory to which you wish to download and type
  EITHER ONE of the following commands:

  git clone https://gitlab.com/bogofilter/bogofilter.git
  OR
  git clone git://git.code.sf.net/p/bogofilter/git bogofilter-git

  b. Building & Installing
  ------------------------

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

  cd bogofilter-1.2.5	[change to project directory]
  ./configure		[add configure options as required]
  make all check
  make install		[as root]

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

  cd bogofilter		[change to project directory]
  autoreconf -i 
  ./configure		[add configure options as required]
  make check
  make install		[as root]

  Be sure to read README.git for additional preparations required.

  configure as shipped in a tarball does not have these requirements.

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

  After using configure and make check to see that bogofilter works on
  your computer, you might wish to further customize bogofilter for your use.

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

  --prefix=PREFIX         install architecture-independent files in PREFIX
			  [default: /usr/local]
  --with-database=ENGINE  Choose database engine
                          {db|qdbm|sqlite3|tokyocabinet|kyotocabinet|lmdb}
  			  [default: db]
  CPPFLAGS=-I/opt/csw/include
			  Choose additional include file path /opt/csw/include
  LDFLAGS=-L/opt/csw/lib  Ditto, for library files

  TROUBLE with finding how to link a library?  In some cases, the .pc files
  to use with pkg-config are broken for your operating system.  bogofilter
  can try to guess how to link, in that case, add PKG_CONFIG=false
  to your ./configure command line and retry.

  Also, some of the help options from configure only apply if it is actually
  using pkg-config (which you can override as in the previous paragraph),
  and some only apply if it tries to find libraries without pkg-config.

  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 and autoconf.

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


7. License
----------

Bogofilter is offered under the GNU General Public License,
see the COPYING file for details. Note that some parts, especially in
the contrib/ section or scripts, may be under a different license.
