make manual page out of README

2 files changed, 166 insertions, 161 deletions

diff --git a/README b/README
index 328ef0f..903a0ef 100644
--- a/README
+++ b/README
@@ -1,161 +1 @@
-NAME
-
-    The dovecot antispam pugin.
-
-DESCRIPTION
-
-    The dovecot antispam plugin watches a defined spam folder (defaults to
-    "SPAM"). It works together with a spam system that classifies each
-    message as it is delivered. When the message is classified as spam, it
-    shall be delivered to the spam folder, otherwise via the regular
-    filtering file the user may have (maildrop, sieve, ...). Now the user
-    has everything classified as spam in the special spam folder, everything
-    else where it should be sorted to.
-
-    This is not enough because our spam scanner needs training. We'll
-    occasionally have false positives and false negatives. Now this is the
-    point where the dovecot antispam plugin comes into play. Instead of
-    moving mail into special folders or forwarding them to special mail
-    addresses for retraining, the plugin offers two actions for the user:
-       1. moving mail out of the SPAM folder and
-       2. moving mail into the SPAM folder.
-
-    The dovecot plugin watches these actions (and additionally prohibits
-    APPENDs to the SPAM folder, more for technical reasons than others) and
-    tells the spam classifier that it made an error and needs to re-classify
-    the message (as spam/not spam depending on which way it was moved.)
-
-    The advantage of this approach is that the mail ends up in the right
-    target folder directly and needs not be touched twice.
-
-    When other classifiers like crm114 that have an 'unsure' state are used,
-    the plugin can also help, it supports an 'unsure' folder feature. The
-    unsure folder cannot be written to, but moving out from there into a
-    folder that is considered a spam folder will learn as spam, any other
-    folder (except trashes) will cause learning as not-spam.
-
-INSTALLATION
-
-    First copy the 'defconfig' file to '.config' and edit it as necessary.
-    You need to have the dovecot headers installed and possibly other things
-    depending on the backend you choose. Then, assuming you have configured
-    the INSTALLDIR correctly, simply run 'make install'.
-
-    If you do not wish to use the install target, simply copy the plugin
-    (that is, the file lib90_antispam_plugin.so) to your dovecot imap plugin
-    directory; by default this is /usr/lib/dovecot/modules/imap/ or any dir
-    you have configured (look for the mail_plugin_dir configuration
-    directive.)
-
-    Open your dovecot configuration file (usually /etc/dovecot/dovecot.conf)
-    and add the antispam plugin to the imap protocol section:
-
-    protocol imap {
-      mail_plugins = antispam
-      # mail_plugin_dir = /usr/lib/dovecot/modules/imap
-    }
-
-BACKENDS
-
-    The plugin supports multiple backends, there are currently two working
-    backends included in the distribution:
-
-    dspam executable backend (dspam specific)
-
-        This backend instantly retrains by calling dspam. There are some
-        problems with this approach including
-         (1) it can take a long time during which the IMAP session is
-             blocked
-         (2) when many users retrain many messages at once server load may
-             spike
-
-    email sender backend (spam filter agnostic)
-
-        This backend sends mail to ham@example.com or spam@example.com
-        (actual addresses are configurable) for retraining. This backend can
-        be very fast to set up if you already have a working setup that uses
-        training addresses as recommended by many spam filter setups.
-
-    crm114 executable backend (crm114 specific)
-
-        This backend instantly retrains by calling mailreaver.crm which
-        needs to be configured (defaulting to /bin/false!); the argument
-        --good or --spam is given depending on how mail is moved.
-
-        You need to use the unsure folder option (see below) together with
-        this plugin and deliver unsure mail into an unsure folder, spam mail
-        into a spam folder and other mail regularly.
-
-        Has the same drawbacks as the dspam-exec approach.
-
-
-CONFIGURATION
-
-    Aside from the build-configuration done in the '.config' file, you have
-    the following run-time options (shown along with the default):
-
-    plugin {
-        ##################
-        # GENERIC OPTIONS
-
-        # mail signature (used with any backend requiring a signature)
-        antispam_signature = X-DSPAM-Signature
-
-        # semicolon-separated list of Trash folders (default unset i.e. none)
-        # antispam_trash =
-        # antispam_trash = trash;Trash;Deleted Items
-
-        # semicolon-separated list of spam folders
-        antispam_spam = SPAM
-
-        # semicolon-separated list of unsure folders (default unset i.e. none)
-        # antispam_unsure =
-
-        ###########################
-        # BACKEND SPECIFIC OPTIONS
-        #
-
-        #===================
-        # dspam-exec plugin
-
-        # dspam binary
-        antispam_dspam_binary = /usr/bin/dspam
-
-        # semicolon-separated list of extra arguments to dspam
-        # (default unset i.e. none)
-        # antispam_dspam_args =
-        # antispam_dspam_args = --user;%u  # % expansion done by dovecot
-        # antispam_dspam_args = --mode=teft
-
-        #=====================
-        # mail sending plugin
-
-        # temporary directory
-        antispam_mail_tmpdir = /tmp
-
-        # spam/not-spam addresses (default unset which will give errors)
-        # antispam_mail_spam =
-        # antispam_mail_ham =
-
-        # sendmail binary
-        antispam_mail_tmpdir = /usr/sbin/sendmail
-
-        #===================
-        # crm114-exec plugin
-
-        # mailreaver binary
-        antispam_crm_binary = /bin/false
-        # antispam_crm_binary = /usr/share/crm114/mailreaver.crm
-
-        # semicolon-separated list of extra arguments to dspam
-        # (default unset i.e. none)
-        # antispam_crm_args =
-        # antispam_crm_args = --config=/path/to/config
-
-        # NOTE: you need to set the signature for this backend
-        antispam_signature = X-CRM114-CacheID
-    }
-
-AUTHORS
-
-    Johannes Berg, Frank Cusack, Benedikt Boehm, Andreas Schneider
+Use 'man ./antispam.7'
diff --git a/antispam.7 b/antispam.7
new file mode 100644
index 0000000..8fe3e63
--- /dev/null
+++ b/antispam.7
@@ -0,0 +1,165 @@
+.TH ANTISPAM 7 "15 October 2007" \*(eX
+.SH NAME
+antispam \- The dovecot antispam plugin.
+
+.SH DESCRIPTION
+The dovecot antispam plugin watches a defined spam folder (defaults to
+"SPAM"). It works together with a spam system that classifies each
+message as it is delivered. When the message is classified as spam, it
+shall be delivered to the spam folder, otherwise via the regular
+filtering file the user may have (maildrop, sieve, ...). Now the user
+has everything classified as spam in the special spam folder, everything
+else where it should be sorted to.
+
+This is not enough because our spam scanner needs training. We'll
+occasionally have false positives and false negatives. Now this is the
+point where the dovecot antispam plugin comes into play. Instead of
+moving mail into special folders or forwarding them to special mail
+addresses for retraining, the plugin offers two actions for the user:
+.IP " 1." 4
+moving mail out of the SPAM folder and
+.IP " 2." 4
+moving mail into the SPAM folder.
+
+.PP
+The dovecot plugin watches these actions (and additionally prohibits
+APPENDs to the SPAM folder, more for technical reasons than others) and
+tells the spam classifier that it made an error and needs to re-classify
+the message (as spam/not spam depending on which way it was moved.)
+
+The advantage of this approach is that the mail ends up in the right
+target folder directly and needs not be touched twice.
+
+When other classifiers like crm114 that have an `unsure' state are used,
+the plugin can also help, it supports an `unsure' folder feature. The
+unsure folder cannot be written to, but moving out from there into a
+folder that is considered a spam folder will learn as spam, any other
+folder (except trashes) will cause learning as not-spam.
+
+.SH INSTALLATION
+
+First copy the `defconfig' file to `.config' and edit it as necessary.
+You need to have the dovecot headers installed and possibly other things
+depending on the backend you choose. Then, assuming you have configured
+the INSTALLDIR correctly, simply run `make install'.
+
+If you do not wish to use the install target, simply copy the plugin
+(that is, the file lib90_antispam_plugin.so) to your dovecot imap plugin
+directory; by default this is /usr/lib/dovecot/modules/imap/ or any dir
+you have configured (look for the mail_plugin_dir configuration
+directive.)
+
+Open your dovecot configuration file (usually /etc/dovecot/dovecot.conf)
+and add the antispam plugin to the imap protocol section:
+
+.nf
+protocol imap {
+  mail_plugins = antispam
+  # mail_plugin_dir = /usr/lib/dovecot/modules/imap
+}
+.fi
+
+.SH BACKENDS
+
+The plugin supports multiple backends, there are currently two working
+backends included in the distribution:
+
+.SS dspam executable backend (dspam specific)
+
+This backend instantly retrains by calling dspam. There are some
+problems with this approach including
+(1) it can take a long time during which the IMAP session is blocked
+(2) when many users retrain many messages at once server load may spike
+
+.SS email sender backend (spam filter agnostic)
+
+This backend sends mail to ham@example.com or spam@example.com
+(actual addresses are configurable) for retraining. This backend can
+be very fast to set up if you already have a working setup that uses
+training addresses as recommended by many spam filter setups.
+
+.SS crm114 executable backend (crm114 specific)
+
+This backend instantly retrains by calling mailreaver.crm which
+needs to be configured (defaulting to /bin/false!); the argument
+--good or --spam is given depending on how mail is moved.
+
+You need to use the unsure folder option (see below) together with
+this plugin and deliver unsure mail into an unsure folder, spam mail
+into a spam folder and other mail regularly.
+
+Has the same drawbacks as the dspam-exec approach.
+
+
+.SH CONFIGURATION
+
+Aside from the build-configuration done in the `.config' file, you have
+the following run-time options (shown along with the default):
+
+.nf
+plugin {
+    ##################
+    # GENERIC OPTIONS
+
+    # mail signature (used with any backend requiring a signature)
+    antispam_signature = X-DSPAM-Signature
+
+    # semicolon-separated list of Trash folders (default unset i.e. none)
+    # antispam_trash =
+    # antispam_trash = trash;Trash;Deleted Items
+
+    # semicolon-separated list of spam folders
+    antispam_spam = SPAM
+
+    # semicolon-separated list of unsure folders (default unset i.e. none)
+    # antispam_unsure =
+
+    ###########################
+    # BACKEND SPECIFIC OPTIONS
+    #
+
+    #===================
+    # dspam-exec plugin
+
+    # dspam binary
+    antispam_dspam_binary = /usr/bin/dspam
+
+    # semicolon-separated list of extra arguments to dspam
+    # (default unset i.e. none)
+    # antispam_dspam_args =
+    # antispam_dspam_args = --user;%u  # % expansion done by dovecot
+    # antispam_dspam_args = --mode=teft
+
+    #=====================
+    # mail sending plugin
+
+    # temporary directory
+    antispam_mail_tmpdir = /tmp
+
+    # spam/not-spam addresses (default unset which will give errors)
+    # antispam_mail_spam =
+    # antispam_mail_ham =
+
+    # sendmail binary
+    antispam_mail_tmpdir = /usr/sbin/sendmail
+
+    #===================
+    # crm114-exec plugin
+
+    # mailreaver binary
+    antispam_crm_binary = /bin/false
+    # antispam_crm_binary = /usr/share/crm114/mailreaver.crm
+
+    # semicolon-separated list of extra arguments to dspam
+    # (default unset i.e. none)
+    # antispam_crm_args =
+    # antispam_crm_args = --config=/path/to/config
+
+    # NOTE: you need to set the signature for this backend
+    antispam_signature = X-CRM114-CacheID
+}
+.fi
+
+.SH AUTHORS
+
+Johannes Berg, Frank Cusack, Benedikt Boehm, Andreas Schneider