Update documentation for recent changes.

diff --git a/minc b/minc
index 34f50ef23535aa964acfb09b3d967e813dfb978a..a36357a3f019698a69c55adec2a15776b09f9a94 100755 (executable)
--- a/minc
+++ b/minc
@@ -18,11 +18,19 @@ B<minc> B<-h>
 
 B<minc> incorporates mail from a maildir to a mh folder hierarchy.  It
 takes mail from a maildir folder (not a maildir folder hierarchy),
 
 B<minc> incorporates mail from a maildir to a mh folder hierarchy.  It
 takes mail from a maildir folder (not a maildir folder hierarchy),

-optionally checks for spam with a user-defined spam-checking function,
-and optionally filters mail into separate mh folders.
-
-The filtering is quite sophisticated, as it is done using real Perl
-matching (m//) commands.
+running each message through regular expression based filter and hook
+functions to determine in which folder to store it or whether it's
+spam.  Post-processing hooks may be applied to each message.
+
+As it processes each message, B<minc> prints a line for each message
+similar to B<inc(1)> and B<scan(1)>.  This line includes the folder
+and message number in which the message was stored, the last 'From'
+header, and the last 'Subject' header.  These fields are truncated to
+fit in the user's terminal (see COLUMNS in B<ENVIRONMENT> below) in
+the following proportions: folder (0.1), message number (0.0625), from
+header (0.175).  Any of these may be overridden with $SCAN_P_FOLDER,
+$SCAN_P_MESSAGE, or $SCAN_P_FROM.  The subject always fills out the
+rest of the line.

 
 =cut
 
 
 =cut
 


@@ -57,7 +65,7 @@ my @SPAM;
 =item B<-d>
 
 Dump (using Data::Dumper) the FILTERS list and exit.  This is useful
 =item B<-d>
 
 Dump (using Data::Dumper) the FILTERS list and exit.  This is useful

-for testing the syntax of .mincfilter.
+for testing the syntax of .minc.

 
 =item B<-h>
 
 
 =item B<-h>
 


@@ -104,9 +112,14 @@ our $run = !$norun;
 
 =over 4
 
 
 =over 4
 

+=item COLUMNS
+
+How many columns the user's terminal can hold, used to print scan
+lines for each processed message.  Defaults to 80.
+

 =item HOME
 
 =item HOME
 

-Where configuration files (.mincfilter) are found.  Also,
+Where the configuration file (.minc) is found.  Also,

 $HOME/Maildir is used for the maildir if MAILDIR is not set.
 
 =item MAILDIR
 $HOME/Maildir is used for the maildir if MAILDIR is not set.
 
 =item MAILDIR


@@ -132,33 +145,16 @@ if (not $MAILDIR) {
 
 =over 4
 
 
 =over 4
 

-=item $HOME/.mincfilter
-
-This file is Perl code (included via the 'require' directive) which is
-expected to define the FILTERS list.
+=item $HOME/.minc

 
 

-=item $HOME/.mincspam
-
-If this file exists, B<minc> will include it with the expectation that
-it will define a B<spam_check> function.  This function takes a
-message filename as an argument and returns 1 if the message is spam,
-else 0.  If this file does not exist, B<minc> will define a simple
-function that always returns 0.
-
-One of B<minc>'s global variables is available to the user-defined
-B<spam_check> function: $run.  This boolean should be honored;
-B<spam_check> should only take real action (i.e. removing or creating
-files, running external programs, etc.) if $run is non-zero.
+This file is Perl code (included via the 'require' directive) which
+may define the FILTERS list, @start_hooks, @filter_hooks,
+@post_store_hooks, and @stop_hooks.

 
 

-This file may also declare two other functions: B<spam_start_hook> and
-B<spam_stop_hook>.  The former is passed no arguments and is expected
-to return a list.  This list is a "baton" that will also be passed to
-B<spam_check> and B<spam_stop_hook>.  It can hold anything
-B<spam_check> will need to do its job, whether network sockets, pipes,
-or whatever.
+=item `mhpath +`/.folders

 
 

-XXX: need more details about the spam-handling process; for now read
-the code.
+B<minc> adds all folders it filters into to this file, which is used
+by lukem's B<new(1)> (XXX need a link).

 
 =item `mhpath +`/logs/minc.log
 
 
 =item `mhpath +`/logs/minc.log
 


@@ -687,14 +683,13 @@ __END__
 
 =head1 THE FILTERS STRUCTURE
 
 
 =head1 THE FILTERS STRUCTURE
 

-The user's .mincfilter file must define the @FILTERS structure.  This
-structure is an array.  Each element of @FILTERS is a filter.  A
-filter is itself an array.  The first element of a filter is a string,
-the name of the header this filter acts upon.  The header name is not
-case-sensitive.  Each subsequent element of a filter is a pair (i.e. a
-two-element array): first, a regular expression B<minc> uses to
-determine whether this filter matches or not, and second, an
-expression which B<minc> evaluates to get the folder name.
+Each element of @FILTERS is a filter.  A filter is itself an array.
+The first element of a filter is a string, the name of the header this
+filter acts upon.  The header name is not case-sensitive.  Each
+subsequent element of a filter is a pair (i.e. a two-element array):
+first, a regular expression B<minc> uses to determine whether this
+filter matches or not, and second, an expression which B<minc>
+evaluates to get the folder name.

 
 B<minc> decides where to store a message by iterating over the
 @FILTERS array.  It tests each regexp of each filter against all
 
 B<minc> decides where to store a message by iterating over the
 @FILTERS array.  It tests each regexp of each filter against all


@@ -717,6 +712,31 @@ header are matched against a collection of headers related to (and
 including) the To.  Which headers to use is determined by a regular
 expression borrowed from procmail.
 
 including) the To.  Which headers to use is determined by a regular
 expression borrowed from procmail.
 

+=head1 HOOKS
+
+Filter hooks take a reference to a hash of batons, a reference to a
+hash of headers, and the message filename as arguments.  It returns
+undef to decline filtering of this message (thus falling back to
+subsequent filter hooks, and finally @FILTERS), or the name of the
+folder to store this message into.
+
+One of B<minc>'s global variables is available to the user-defined
+hooks: $run.  This boolean should be honored; hooks should only take
+real action (i.e. removing or creating files, running external
+programs, etc.) if $run is non-zero.
+
+The baton hash is created simply from the start hooks; if the hook
+returns at least one defined value, this value is used as the key and
+all other return values are put into a list reference as the value.
+This hash is then passed by reference to all filter, post-store, and
+stop hooks.
+
+Post store hooks take a reference to a hash of batons, a reference to
+a hash of headers, the folder this message was stored in, and its new
+message number.
+
+XXX: need more details about the hook process; for now read the code.
+

 =head1 EXAMPLES
 
 @FILTERS = (
 =head1 EXAMPLES
 
 @FILTERS = (


@@ -752,8 +772,7 @@ apache.org subdomain, with mailing lists hosted there.  So, given a
 list such as dev@httpd.apache.org, this filter will create the folder
 name l/apache/httpd/dev.
 
 list such as dev@httpd.apache.org, this filter will create the folder
 name l/apache/httpd/dev.
 

-For an example B<spam_check> function, see
-L<http://pretzelnet.org/cvs/dotfiles/.mincspam>
+XXX Need hook examples.

 
 =head1 AUTHORS
 
 
 =head1 AUTHORS