<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="bogotune.1">
<refmeta>
<refentrytitle>bogotune</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">Bogofilter Reference Manual</refmiscinfo>
<refmiscinfo class="source">Bogofilter</refmiscinfo>
</refmeta>

  <refnamediv id="name">
    <refname>bogotune</refname>
    <refpurpose> find optimum parameter settings for
    <application>bogofilter</application> </refpurpose>
  </refnamediv>

  <refsynopsisdiv id="synopsis">
    <cmdsynopsis>
      <command>bogotune</command> 
	 <arg>-v</arg>
	 <arg>-c <replaceable>config</replaceable></arg>
	 <arg>-C</arg>
	 <arg>-d <replaceable>dir</replaceable></arg>
	 <arg>-D</arg>
	 <arg>-r <replaceable>value</replaceable></arg>
	 <arg>-T <replaceable>value</replaceable></arg>
	 <arg choice="plain">-n <replaceable>okfile</replaceable> [[-n]
	     <replaceable>okfile</replaceable> [...]]</arg>
	 <arg choice="plain">-s <replaceable>spamfile</replaceable>
	     [[-s] <replaceable>spamfile</replaceable> [...]]</arg>
	 <arg>-M <replaceable>file</replaceable> </arg>
      </cmdsynopsis>

    <cmdsynopsis>
      <command>bogotune</command> <arg>-h</arg>
    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1 id="description">
    <title>DESCRIPTION</title>

    <para><application>Bogotune</application> tries to find optimum
    parameter settings for <application>bogofilter</application>.  It
    needs at least one set each of spam and non-spam messages.  The
    production wordlist is normally used, but it can be directed to
    read a different wordlist, or to build its own from half the
    supplied messages.</para> 

    <para>In order to produce useful results,
    <application>bogotune</application> has minimum message count
    requirements.  The wordlist it uses must have at least 2,000 spam
    and 2,000 non-spam in it and the message files must contain at
    least 500 spam and 500 non-spam messages.  Also, the ratio of spam
    to non-spam should be in the range 0.2 to 5.  If you direct
    <application>bogotune</application> to build its own wordlist, it
    will use the half the input or 2000 messages (whichever is larger)
    for the wordlist.</para>

    <para>Message files may be in mbox, maildir, or MH folder or any
    combination.  Msg-count files can also be used, but not mixed with
    other formats.</para> </refsect1>

  <refsect1 id="options">
    <title>OPTIONS</title>

    <para>The <option>-h</option> option prints the help message and exits.</para>

    <para>The <option>-v</option> option increases the verbosity
    level.  Level 1 displays the scan output in detail instead of using a progress meter.</para>

    <para>The <option>-c</option> <replaceable>filename</replaceable>
    option tells <application>bogofilter</application> to read the
    config file named.  </para>

    <para>The <option>-C</option> option prevents <application>bogotune</application> from
    reading a configuration file.</para>

    <para>The <option>-d</option> <replaceable>dir</replaceable>
    option specifies the directory for the database.  See the
    ENVIRONMENT section for other directory setting options.</para>

    <para>The <option>-D</option> option tells
    <application>bogotune</application> to build a wordlist in memory
    using the input messages.  The messages are read and divided into
    two groups.  The first group is used to build a wordlist (in ram)
    and the second is used for tuning.  To meet the minimum
    requirements of 2000 messages in the wordlist and 500 messages for
    testing, when <option>-D</option> is used, there must be 2500
    non-spam and 2500 spam in the input files.  If there are enough
    messages (more than 4000), they will be split evenly between
    wordlist and testing.  Otherwise, they will be split
    proportionately.</para>

    <para>The <option>-n</option> option tells
    <application>bogotune</application> that the following argument
    is a file (or folder) containing non-spam. Since version 1.0.3,
    multiple arguments to the <option>-n</option> option can be given.
    All non-option arguments until the next <option>-s</option> option
    will be treated as though they had been preceded by
    <option>-n</option></para>

    <para>The <option>-s</option> option tells
    <application>bogotune</application> that the following argument
    is a file (or folder) containing spam. It can be repeated as often
    as necessary. Since version 1.0.3, multiple arguments to the
    <option>-s</option> can be given. All non-option arguments until the
    next <option>-n</option> option will be treated as though they had
    been preceded by <option>-s</option>.</para>

    <para>The <option>-r <replaceable>value</replaceable></option>
    option tells <application>bogotune</application> to use the
    following parameter as the robx value.</para>

    <para>The <option>-T <replaceable>value</replaceable></option>
    option tells <application>bogotune</application> to use the
    following parameter as fp target value.</para>

    <para>The <option>-M <replaceable>file</replaceable></option>
    option tells <application>bogotune</application> to convert the
    file to message count format.  This format provides a sorted list
    of each message's unique tokens, along with their ham and spam
    counts.  Sorting hides the sense of the messages quite
    effectively, thus protecting privacy.  The message-count format
    allows <application>bogotune</application> and
    <application>bogofilter</application> to score messages quickly
    without needing the original token database.  </para>

</refsect1>

<refsect1 id='environment'><title>ENVIRONMENT</title>

    <para><application>Bogofilter</application> uses a database directory,
    which can be set in the config file.  If not set there,
    <application>bogofilter</application> will use the value of
    <envar>BOGOFILTER_DIR</envar>.  Both can be overridden by the
    <option>-d<replaceable>dir</replaceable></option> option.  If none
    of that is available, <application>bogofilter</application> will use
    directory <filename>$HOME/.bogofilter</filename>.</para>

</refsect1>

<refsect1>
<title>Bugs</title>
<para><application>Bogotune</application> is not particularly robust when presented with garbage input. 
</para>
</refsect1>

  <refsect1 id="author">
    <title>AUTHOR</title>
    <para>The <application>bogofilter</application> developer team.</para>
    <para>
       For updates, see <ulink url="http://bogofilter.sourceforge.net/">
       the bogofilter project page</ulink>.
    </para>
  </refsect1>

<refsect1 id="also">
    <title>SEE ALSO </title>
    <para>bogofilter(1), bogolexer(1), bogoupgrade(1), bogoutil(1)</para>
</refsect1>
</refentry>