started writing docs

diff --git a/umpf.man b/umpf.man
new file mode 100644 (file)
index 0000000..c214596
--- /dev/null
+++ b/umpf.man
@@ -0,0 +1,126 @@
+NAME
+umpf - universal mail processing filter
+
+SYNOPSIS
+umpf [-c config_file] [-m default_mailbox]
+ 
+DESCRIPTION
+
+Umpf is a program that reads an e-mail from stdin and according to
+the config file decides, what to do with it. It is possible to forward the
+e-mail, filter it through external program and, of course, deliver it to the
+local mailbox.  IMAP support is planned, but not ready yet.
+
+OPTIONS
+
+-c file
+Set an alternative location of the config file.
+
+-m file
+Set an alternative location of the default mailbox.
+
+CONFIGURATION
+
+The program reads a config file (default location is ~/.umpf) and according
+to the rules provided it decides, what to do with it. If no rule is matched,
+or some action fails, or the config file cannot be parsed, e-mail is
+delivered to the default mailbox (default location is /var/mail/login,
+program needs setgid to be able to use it).
+
+VARIABLES
+
+Variables can be specified in the config file. Their identifiers must start
+with the letter $. Variables have three types that are distinguisghed
+according to the case of the identifiers. Upper case identifiers are reserved
+for automatic variables like message size, it is possible to modify them but
+it is not encouraged. Variables with identifiers starting with an upper-case
+letter but mixed case otherwise correspond to values of e-mail headers,
+assigning to them will change the headers. Variables with identifiers
+starting with a lower case letter are intended for general use. Otherwise,
+variable identifiers are case-insensitive, ie. $abc refers to the same
+variable as $aBc, but not the same as $Abc and all of these variables differ from $ABC.
+
+AUTOMATIC VARIABLES
+
+Config file recognizes these automatic variables:
+$MAIL_LEN refers to the length of the e-mail, including headers
+$LAST_EXIT_CODE refers to the exit code of last external program executed (actions filter or pipe can be used to do it)
+$LAST_OUTPUT refers to the output of last external program executed by action pipe
+
+COMMANDS
+A command is either an action specification or an assignment. All the
+commands must with semicolon. Commands can be grouped in blocks bounded by
+braces.
+
+ASSIGNMENTS
+Assignment is specified in a following way:
+Lvalue = Rvalue;
+Lvalue is a variable identifier. Rvalue can be variable, a constant (constant
+must be given in double quotes) or an expression consisting of variables,
+constants and binary operations .,+, -, * and /. Operation . stands for
+string contatenations, the rest of them are arithmetic operations. Doing
+arithemtic operations makes sense only on integers. Precedence of the operations can be specified using parenthesis.
+
+ACTIONS
+Actions are specified with an arrow operator. Plain
+-> ;
+means "deliver the e-mail to the default mailbox and exit".
+-> expression ;
+means "deliver the e-mail the mailbox specified behind arrow and exit"
+-> pipe expression ;
+means "pipe the e-mail to the external program specified behind pipe keyword". Output of the program is stored in $LAST_OUTPUT variable, its exit code is stored in $LAST_EXIT_CODE variable.
+-> filter expression ;
+means "pipe the e-mail to the external program and replace it with output of the program". All the headers variables, $MAIL_LEN and $LAST_EXIT_CODE are set accordingly.
+-> discard ;
+means just "discard the email and exit". 
+-> mail expression ;
+means "forward the e-mail to the address specifed behind the mail keyword and exit"
+
+If action fails, the e-mail is delivered to the default mailbox.
+
+Some of the actions (delivery or forwarding an e-mail) can have keyword copy in front of the arrow, ie.
+copy -> "mailbox";
+When copy is specified, the program does not exit after doing an action but continues reading the rules. It also does not deliver to default mailbox if action fails.
+
+CONDITIONS
+
+Conditional execution of commands can be specified in a following way:
+
+if (condition) { ... }
+or
+if (condtion) { ... } else { ... }
+
+where condition can be a constant, a variable or an expression consisting of
+following operations:
+& is binary boolean and
+| is binary boolean or
+^ is binary boolean xor
+! is unary boolean not
+
+A variable or a constant has a boolean value 0, if its value is either "" or "0" and 1 otherwise.
+
+Expressions can be compared using following binary relations.
+
+String comparisons:
+~~ means "matches" (left operand should be string, right one can be a perl compatible regular expression)
+!~ means "does not match"
+
+Integer comparisons (does not make sense on strings):
+== means "is equal to"
+!= means "is not equal to"
+< means "is lesser than"
+> means "is greater than"
+<= means "is lesser or equal than"
+>= means "is greater or equal than"
+
+COMMENTS
+All the text behind a hash character up to the end of the line is ignored.
+
+BUGS
+Aer prsenet.
+
+TODO
+IMAP support.
+
+AUTHOR
+Anicka <anicka@anicka.net>