[SACVS] CVS: spamassassin/lib/Mail/SpamAssassin Conf.pm,1.252,1.253

Update of /cvsroot/spamassassin/spamassassin/lib/Mail/SpamAssassin
In directory sc8-pr-cvs1:/tmp/cvs-serv8212/lib/Mail/SpamAssassin

Modified Files:
        Conf.pm 
Log Message:
clean up configuration
- now "podchecker" clean
- add sub-headings for user preferences and moved some options around
- move "tflags" to privileged settings


Index: Conf.pm
===================================================================
RCS file: /cvsroot/spamassassin/spamassassin/lib/Mail/SpamAssassin/Conf.pm,v
retrieving revision 1.252
retrieving revision 1.253
diff -b -w -u -d -r1.252 -r1.253
--- Conf.pm     16 Sep 2003 00:31:34 -0000      1.252
+++ Conf.pm     17 Sep 2003 20:26:38 -0000      1.253
@@ -74,7 +74,9 @@
 
 =head1 USER PREFERENCES
 
-=over 4
+The following options can be used in both site-wide (C<local.cf>) and
+user-specific (C<user_prefs>) configuration files to customize how
+SpamAssassin handles incoming email messages.
 
 =cut
 
@@ -339,6 +341,10 @@
     # Simplifies regexps below...
     1 while s/^(\S+)\-(\S+)/$1_$2/g;
 
+=head2 VERSION OPTIONS
+
+=over 4
+
 =item require_version n.nn
 
 Indicates that the entire file, from this line on, requires a certain version
@@ -394,6 +400,12 @@
       next;
     }
 
+=back
+
+=head2 WHITELIST AND BLACKLIST OPTIONS
+
+=over 4
+
 =item whitelist_from add@xxxxxxxx
 
 Used to specify addresses which send mail that is often tagged (incorrectly) as
@@ -583,6 +595,12 @@
       $self->add_to_addrlist ('blacklist_to', split (' ', $1)); next;
     }
 
+=back
+
+=head2 SCORING OPTIONS
+
+=over 4
+
 =item required_hits n.nn   (default: 5)
 
 Set the number of hits required before a mail is considered spam.  C<n.nn> can
@@ -646,6 +664,12 @@
     next;
   }
 
+=back
+
+=head2 MESSAGE TAGGING OPTIONS
+
+=over 4
+
 =item rewrite_subject { 0 | 1 }        (default: 0)
 
 By default, the subject lines of suspected spam will not be tagged.  This can
@@ -841,17 +865,145 @@
       next;
     }
 
-=item skip_rbl_checks { 0 | 1 }   (default: 0)
+=item report_charset CHARSET           (default: unset)
 
-By default, SpamAssassin will run RBL checks.  If your ISP already does this
-for you, set this to 1.
+Set the MIME Content-Type charset used for the text/plain report which
+is attached to spam mail messages.
 
 =cut
 
-    if (/^skip_rbl_checks\s+(\d+)$/) {
-      $self->{skip_rbl_checks} = $1+0; next;
+    if (/^report_charset\s*(.*)$/) {
+      $self->{report_charset} = $1; next;
     }
 
+=item report ...some text for a report...
+
+Set the report template which is attached to spam mail messages.  See the
+C<10_misc.cf> configuration file in C</usr/share/spamassassin> for an
+example.
+
+If you change this, try to keep it under 78 columns. Each C<report>
+line appends to the existing template, so use C<clear_report_template>
+to restart.
+
+Tags can be included as explained above.
+
+=cut
+
+    if (/^report\b\s*(.*?)\s*$/) {
+      my $report = $1;
+      if ( $report =~ /^"(.*?)"$/ ) {
+        $report = $1;
+      }
+
+      $self->{report_template} .= "$report\n"; next;
+    }
+
+=item clear_report_template
+
+Clear the report template.
+
+=cut
+
+    if (/^clear_report_template$/) {
+      $self->{report_template} = ''; next;
+    }
+
+=item report_contact ...text of contact address...
+
+Set what _CONTACTADDRESS_ is replaced with in the above report text.
+By default, this is 'the administrator of that system', since the hostname
+of the system the scanner is running on is also included.
+
+=cut
+
+    if (/^report_contact\s+(.*?)\s*$/) {
+      $self->{report_contact} = $1; next;
+    }
+
+=item unsafe_report ...some text for a report...
+
+Set the report template which is attached to spam mail messages which contain a
+non-text/plain part.  See the C<10_misc.cf> configuration file in
+C</usr/share/spamassassin> for an example.
+
+Each C<unsafe-report> line appends to the existing template, so use
+C<clear_unsafe_report_template> to restart.
+
+Tags can be used in this template (see above for details).
+
+=cut
+
+    if (/^unsafe_report\b\s*(.*?)$/) {
+      my $report = $1;
+      if ( $report =~ /^"(.*?)"$/ ) {
+        $report = $1;
+      }
+
+      $self->{unsafe_report_template} .= "$report\n"; next;
+    }
+
+=item clear_unsafe_report_template
+
+Clear the unsafe_report template.
+
+=cut
+
+    if (/^clear_unsafe_report_template$/) {
+      $self->{unsafe_report_template} = ''; next;
+    }
+
+=item spamtrap ...some text for spamtrap reply mail...
+
+A template for spam-trap responses.  If the first few lines begin with
+C<Xxxxxx: yyy> where Xxxxxx is a header and yyy is some text, they'll be used
+as headers.  See the C<10_misc.cf> configuration file in
+C</usr/share/spamassassin> for an example.
+
+Unfortunately tags can not be used with this option.
+
+=cut
+
+    if (/^spamtrap\s*(.*?)$/) {
+      my $report = $1;
+      if ( $report =~ /^"(.*?)"$/ ) {
+        $report = $1;
+      }
+      $self->{spamtrap_template} .= "$report\n"; next;
+    }
+
+=item clear_spamtrap_template
+
+Clear the spamtrap template.
+
+=cut
+
+    if (/^clear_spamtrap_template$/) {
+      $self->{spamtrap_template} = ''; next;
+    }
+
+=item describe SYMBOLIC_TEST_NAME description ...
+
+Used to describe a test.  This text is shown to users in the detailed report.
+
+Note that test names which begin with '__' are reserved for meta-match
+sub-rules, and are not scored or listed in the 'tests hit' reports.
+
+Also note that by convention, rule descriptions should be limited in
+length to no more than 50 characters.
+
+=cut
+
+    if (/^describe\s+(\S+)\s+(.*)$/) {
+      $self->{descriptions}->{$1} = $2; next;
+    }
+
+=back
+
+=head2 LANGUAGE OPTIONS
+
+=over 4
+
 =item ok_languages xx [ yy zz ... ]            (default: all)
 
 Which languages are considered OK to receive mail in.  SpamAssassin will try to
@@ -1072,175 +1224,11 @@
       $self->{ok_locales} = $1; next;
     }
 
-=item describe SYMBOLIC_TEST_NAME description ...
-
-Used to describe a test.  This text is shown to users in the detailed report.
-
-Note that test names which begin with '__' are reserved for meta-match
-sub-rules, and are not scored or listed in the 'tests hit' reports.
-
-Also note that by convention, rule descriptions should be limited in
-length to no more than 50 characters.
-
-=cut
-
-    if (/^describe\s+(\S+)\s+(.*)$/) {
-      $self->{descriptions}->{$1} = $2; next;
-    }
-
-=item tflags SYMBOLIC_TEST_NAME [ { net | nice | learn | userconf } ... ]
-
-Used to set flags on a test.  These flags are used in the score-determination
-back end system for details of the test's behaviour.  The following flags can
-be set:
-
-=over 4
-
-=item  net
-
-The test is a network test, and will not be run in the mass checking system
-or if B<-L> is used, therefore its score should not be modified.
-
-=item  nice
-
-The test is intended to compensate for common false positives, and should be
-assigned a negative score.
-
-=item  userconf
-
-The test requires user configuration before it can be used (like language-
-specific tests).
-
-=item  learn
-
-The test requires training before it can be used.
-
 =back
 
-=cut
-
-    if (/^tflags\s+(\S+)\s+(.+)$/) {
-      $self->{tflags}->{$1} = $2; next;
-      next;     # ignored in SpamAssassin modules
-    }
-
-
-=item report_charset CHARSET           (default: unset)
-
-Set the MIME Content-Type charset used for the text/plain report which
-is attached to spam mail messages.
-
-=cut
-
-    if (/^report_charset\s*(.*)$/) {
-      $self->{report_charset} = $1; next;
-    }
-
-=item report ...some text for a report...
-
-Set the report template which is attached to spam mail messages.  See the
-C<10_misc.cf> configuration file in C</usr/share/spamassassin> for an
-example.
-
-If you change this, try to keep it under 78 columns. Each C<report>
-line appends to the existing template, so use C<clear_report_template>
-to restart.
-
-Tags can be included as explained above.
-
-=cut
-
-    if (/^report\b\s*(.*?)\s*$/) {
-      my $report = $1;
-      if ( $report =~ /^"(.*?)"$/ ) {
-        $report = $1;
-      }
-
-      $self->{report_template} .= "$report\n"; next;
-    }
-
-=item clear_report_template
-
-Clear the report template.
-
-=cut
-
-    if (/^clear_report_template$/) {
-      $self->{report_template} = ''; next;
-    }
-
-=item report_contact ...text of contact address...
-
-Set what _CONTACTADDRESS_ is replaced with in the above report text.
-By default, this is 'the administrator of that system', since the hostname
-of the system the scanner is running on is also included.
-
-=cut
-
-    if (/^report_contact\s+(.*?)\s*$/) {
-      $self->{report_contact} = $1; next;
-    }
-
-=item unsafe_report ...some text for a report...
-
-Set the report template which is attached to spam mail messages which contain a
-non-text/plain part.  See the C<10_misc.cf> configuration file in
-C</usr/share/spamassassin> for an example.
-
-Each C<unsafe-report> line appends to the existing template, so use
-C<clear_unsafe_report_template> to restart.
-
-Tags can be used in this template (see above for details).
-
-=cut
-
-    if (/^unsafe_report\b\s*(.*?)$/) {
-      my $report = $1;
-      if ( $report =~ /^"(.*?)"$/ ) {
-        $report = $1;
-      }
-
-      $self->{unsafe_report_template} .= "$report\n"; next;
-    }
-
-=item clear_unsafe_report_template
-
-Clear the unsafe_report template.
-
-=cut
-
-    if (/^clear_unsafe_report_template$/) {
-      $self->{unsafe_report_template} = ''; next;
-    }
-
-=item spamtrap ...some text for spamtrap reply mail...
-
-A template for spam-trap responses.  If the first few lines begin with
-C<Xxxxxx: yyy> where Xxxxxx is a header and yyy is some text, they'll be used
-as headers.  See the C<10_misc.cf> configuration file in
-C</usr/share/spamassassin> for an example.
-
-Unfortunately tags can not be used with this option.
-
-=cut
-
-    if (/^spamtrap\s*(.*?)$/) {
-      my $report = $1;
-      if ( $report =~ /^"(.*?)"$/ ) {
-        $report = $1;
-      }
-      $self->{spamtrap_template} .= "$report\n"; next;
-    }
-
-=item clear_spamtrap_template
-
-Clear the spamtrap template.
-
-=cut
+=head2 NETWORK TEST OPTIONS
 
-    if (/^clear_spamtrap_template$/) {
-      $self->{spamtrap_template} = ''; next;
-    }
+=over 4
 
 =item use_dcc ( 0 | 1 )                (default: 1)
 
@@ -1456,6 +1444,17 @@
       $self->{use_bayes} = $1; next;
     }
 
+=item skip_rbl_checks { 0 | 1 }   (default: 0)
+
+By default, SpamAssassin will run RBL checks.  If your ISP already does this
+for you, set this to 1.
+
+=cut
+
+    if (/^skip_rbl_checks\s+(\d+)$/) {
+      $self->{skip_rbl_checks} = $1+0; next;
+    }
+
 =item rbl_timeout n            (default: 15)
 
 All RBL queries are made at the beginning of a check and we try to read the
@@ -1527,6 +1526,12 @@
       $self->{dns_available} = ($1 or "test"); next;
     }
 
+=back
+
+=head2 LEARNING OPTIONS
+
+=over 4
+
 =item auto_whitelist_factor n  (default: 0.5, range [0..1])
 
 How much towards the long-term mean for the sender to regress a message.
@@ -1543,6 +1548,7 @@
 mean; C<factor> = 0 mean just use the calculated score.
 
 =cut
+
     if (/^auto_whitelist_factor\s+(.*)$/) {
       $self->{auto_whitelist_factor} = $1; next;
     }
@@ -1595,7 +1601,7 @@
       $self->{bayes_auto_learn_threshold_spam} = $1+0; next;
     }
 
-=item bayes_ignore_header      
+=item bayes_ignore_header header_name
 
 If you receive mail filtered by upstream mail systems, like
 a spam-filtering ISP or mailing list, and that service adds
@@ -1608,6 +1614,7 @@
        bayes_ignore_header X-Upstream-SomethingElse
 
 =cut
+
     if (/^bayes_ignore_header\s+(.*)$/) {
       push (@{$self->{bayes_ignore_headers}}, $1); next;
     }
@@ -1642,6 +1649,11 @@
       $self->{bayes_learn_during_report} = $1+0; next;
     }
 
+=back
+
+=head2 DEPRECATED OPTIONS
+
+=over 4
 
 =item always_add_headers { 0 | 1 }      (default: 1)
 
@@ -1832,7 +1844,7 @@
 
 =back
 
-=head1 SETTINGS
+=head1 PRIVILEGED SETTINGS
 
 These settings differ from the ones above, in that they are considered
 'privileged'.  Only users running C<spamassassin> from their procmailrc's or
@@ -1980,6 +1992,7 @@
 single A record containing a bitmask of results.
 
 =cut
+
     if (/^header\s+(\S+)\s+(?:rbl)?eval:(.*)$/) {
       my ($name, $fn) = ($1, $2);
 
@@ -2017,6 +2030,7 @@
 Define a body eval test.  See above.
 
 =cut
+
     if (/^body\s+(\S+)\s+eval:(.*)$/) {
       $self->add_test ($1, $2, TYPE_BODY_EVALS);
       next;
@@ -2037,6 +2051,7 @@
 points of the URI, and will also be faster.
 
 =cut
+
 # we don't do URI evals yet - maybe later
 #    if (/^uri\s+(\S+)\s+eval:(.*)$/) {
 #      $self->add_test ($1, $2, TYPE_URI_EVALS);
@@ -2060,6 +2075,7 @@
 Define a raw-body eval test.  See above.
 
 =cut
+
     if (/^rawbody\s+(\S+)\s+eval:(.*)$/) {
       $self->add_test ($1, $2, TYPE_RAWBODY_EVALS);
       next;
@@ -2082,6 +2098,7 @@
 Define a full-body eval test.  See above.
 
 =cut
+
     if (/^full\s+(\S+)\s+eval:(.*)$/) {
       $self->add_test ($1, $2, TYPE_FULL_EVALS);
       next;
@@ -2124,6 +2141,42 @@
       next;
     }
 
+=item tflags SYMBOLIC_TEST_NAME [ { net | nice | learn | userconf } ... ]
+
+Used to set flags on a test.  These flags are used in the score-determination
+back end system for details of the test's behaviour.  The following flags can
+be set:
+
+=over 4
+
+=item  net
+
+The test is a network test, and will not be run in the mass checking system
+or if B<-L> is used, therefore its score should not be modified.
+
+=item  nice
+
+The test is intended to compensate for common false positives, and should be
+assigned a negative score.
+
+=item  userconf
+
+The test requires user configuration before it can be used (like language-
+specific tests).
+
+=item  learn
+
+The test requires training before it can be used.
+
+=back
+
+=cut
+
+    if (/^tflags\s+(\S+)\s+(.+)$/) {
+      $self->{tflags}->{$1} = $2; next;
+      next;     # ignored in SpamAssassin modules
+    }
+
 ###########################################################################
     # SECURITY: allow_user_rules is only in affect until here.
     #
@@ -2131,7 +2184,7 @@
 
 =back
 
-=head1 PRIVILEGED SETTINGS
+=head1 ADMINISTRATOR SETTINGS
 
 These settings differ from the ones above, in that they are considered 'more
 privileged' -- even more than the ones in the SETTINGS section.  No matter what
@@ -2140,7 +2193,6 @@
 
 =over 4
 
-
 =item test SYMBOLIC_TEST_NAME (ok|fail) Some string to test against
 
 Define a regression testing string. You can have more than one regression test
@@ -2288,6 +2340,7 @@
 not have any execute bits set (the umask is set to 111).
 
 =cut
+
     if (/^auto_whitelist_file_mode\s+(.*)$/) {
       $self->{auto_whitelist_file_mode} = $1; next;
     }
@@ -2301,6 +2354,7 @@
 not have any execute bits set (the umask is set to 111).
 
 =cut
+
     if (/^bayes_file_mode\s+(.*)$/) {
       $self->{bayes_file_mode} = $1; next;
     }
@@ -2312,6 +2366,7 @@
 increases database size by about a factor of 8 to 10.
 
 =cut
+
     if (/^bayes_use_hapaxes\s+(.*)$/) {
       $self->{bayes_use_hapaxes} = $1; next;
     }
@@ -2324,6 +2379,7 @@
 in corpus size etc.
 
 =cut
+
     if (/^bayes_use_chi2_combining\s+(.*)$/) {
       $self->{bayes_use_chi2_combining} = $1; next;
     }
@@ -2336,6 +2392,7 @@
 only occur once a day.
 
 =cut
+
     if (/^bayes_journal_max_size\s+(\d+)$/) {
       $self->{bayes_journal_max_size} = $1; next;
     }
@@ -2348,6 +2405,7 @@
 equivalent to a 8Mb database file.
 
 =cut
+
     if (/^bayes_expiry_max_db_size\s+(\d+)$/) {
       $self->{bayes_expiry_max_db_size} = $1; next;
     }
@@ -2359,6 +2417,7 @@
 database surpasses the bayes_expiry_max_db_size value.
 
 =cut
+
     if (/^bayes_auto_expire\s+(\d+)$/) {
       $self->{bayes_auto_expire} = $1; next;
     }
@@ -2393,6 +2452,7 @@
 The authorized username to connect to the above DSN.
 
 =cut
+
     if(/^user_scores_sql_username\s+(\S+)$/) {
       $self->{user_scores_sql_username} = $1; next;
     }
@@ -2402,6 +2462,7 @@
 The password for the database username, for the above DSN.
 
 =cut
+
     if(/^user_scores_sql_password\s+(\S+)$/) {
       $self->{user_scores_sql_password} = $1; next;
     }
@@ -2411,6 +2472,7 @@
 The table user preferences are stored in, for the above DSN.
 
 =cut
+
     if(/^user_scores_sql_table\s+(\S+)$/) {
       $self->{user_scores_sql_table} = $1; next;
     }
@@ -2425,6 +2487,7 @@
 Default: C<username>.
 
 =cut
+
     if(/^user_scores_sql_field_username\s+(\S+)$/) {
       $self->{user_scores_sql_field_username} = $1; next;
     }
@@ -2434,6 +2497,7 @@
 The name of the preference that you're looking for.  Default: C<preference>.
 
 =cut
+
     if(/^user_scores_sql_field_preference\s+(\S+)$/) {
       $self->{user_scores_sql_field_preference} = $1; next;
     }
@@ -2443,6 +2507,7 @@
 The name of the value you're looking for.  Default: C<value>.
 
 =cut
+
     if(/^user_scores_sql_field_value\s+(\S+)$/) {
       $self->{user_scores_sql_field_value} = $1; next;
     }
@@ -2454,6 +2519,7 @@
 systems.  Default: C<spamassassin>.
 
 =cut
+
     if(/^user_scores_sql_field_scope\s+(\S+)$/) {
       $self->{user_scores_sql_field_scope} = $1; next;
     }



-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf