Added subject_macro; Tweaked check order; Fixed some warnings

1 files changed, 64 insertions, 14 deletions

diff --git a/doc/INSTRUCTION b/doc/INSTRUCTION
index ef0cdc6..e55fdef 100644
--- a/doc/INSTRUCTION
+++ b/doc/INSTRUCTION
@@ -23,19 +23,21 @@ order:
 
 [trusted settings]
 
+[subject macros]
+
 [domain settings]
 
-Note it is *highly* recommended to set .kbsrc to be only readable by the
-user - this is as passwords are stored in there.
+It is *highly* recommended to set .kbsrc to be only readable by the user - this
+is as passwords are stored in there.
 
 Blank lines and text proceeded with a hash (#) are ignored.
 
 Each token is delimited with white space - if the value you want to use
 includes spaces, simple quote them (with either single or double quotes).
 
-Note that escapes aren't used (to make regular expression writing easier), so
-if you want to include a quote in a string, simply use the other sort of quote.
-If you want both, sorry, you're stuck!
+Escapes aren't used (to make regular expression writing easier), so if you want
+to include a quote in a string, simply use the other sort of quote.  If you
+want both, sorry, you're stuck!
 
 To see an example kbsrc file, see kbsrc in the src directory.
 
@@ -89,12 +91,13 @@ And understand the following variables:
 			Defaults to off.
 
     blockhtml <on|off>	Whether messages that are pure HTML (content part just
-    			reported as "text/html" are blocked.
+    			reported as "text/html" are blocked.  Also blocks
+			messages with an empty, or missing, content type.
 			Defaults to off.
 
     testmode <on|off>	Whether things will be really deleted, or just
-    			the actions logged.  Note that the log is still
-			filled out as if the deletion occured.
+    			the actions logged.  The log is still filled out as if
+			the deletion occured.
 			Defaults to off, though it is recommended to use this
 			for early runs to ensure your rules are not too harsh
 			(or too easy for that matter).
@@ -119,12 +122,47 @@ other tests.
     }
 
 
+Subject Macros
+==============
+
+This command is simply to ease the writing of regular expressions where you
+want to match expressions where numbers or alternative characters are
+often used to try and fool filters:
+
+    subject_macro <source string> <replacement string>
+
+e.g.
+
+    subject_macro "i" "[i1!l]"	# Common spam spellings for 'i'
+    subject_macro "e" "[e3]"
+    subject_macro "s" "[s5]"
+    ...
+    ...
+    disallow_subject " ?free movies ?"
+
+Subject macros are only expanded one time - if the result of an expansion
+includes another macro, that will not be expanded.  Also remember
+that macros are case sensitive - this allows easy constructions like this
+which would break if the 'i' in the '[]' was expanded:
+
+    set casesense off
+    ...
+    ...
+    subject "i" "[i1!l]"
+    ...
+    ...
+    disallow_subject "i...[I12]"
+
+Even though it's not obvious from the examples above, the source string can
+be any number of characters.
+
+
 Domain settings
 ===============
 
-These define the rules applied to a certain domain.  Note the order these
-appear in is important, as the first match when checking domain names will
-be used.
+These define the rules applied to a certain domain.  The order domains
+appear in is important, as the first match found when checking domain names
+will be used.
 
     domain <regular expression>
     {
@@ -147,9 +185,21 @@ always let through.
 The block_subject means that subjects that match that regular expression are
 always blocked and deleted.
 
-Note that multiple allow_subject and block_subject commands can be in one
-domain.
+Multiple allow and block commands can be in one domain.
+
+The commands inside a domain can appear in any order, but the checks are always
+done in this order:
+
+1. If a trusted domain, allow message.
+2. If a trusted user, allow message.
+3. If an HTML message and these are blocked, delete message.
+4. If the domain is not matched in a domain command, allow message.
+5. If the subject is allowed for the domain, allow message.
+6. If the username is blocked for the domain, delete message.
+7. If the subject is disallowed for the domain, delete message.
+8. Delete the message if the default is to block.
+
 
 
 -------------------------------------------------------------------------------
-$Id: INSTRUCTION,v 1.3 2003-12-07 01:46:44 ianc Exp $
+$Id: INSTRUCTION,v 1.4 2003-12-08 02:20:14 ianc Exp $