umpf.1 done

diff --git a/umpf.1 b/umpf.1
new file mode 100644 (file)
index 0000000..e696e6e
--- /dev/null
+++ b/umpf.1
@@ -0,0 +1,200 @@
+.TH "umpf" 1 
+.SH NAME
+umpf \- universal mail processing filter
+.SH SYNOPSIS
+.B umpf
+[-c config_file] [-m default_mailbox]
+.SH 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.
+.SH OPTIONS
+.TP
+.B \-c "\|file\^"
+Set an alternative location of the config file.
+.TP
+.B \-m "\|file\^"
+Set an alternative location of the default mailbox.
+.SH CONFIGURATION
+The program reads a config file (default location is 
+.I ~/.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 
+.I /var/mail/login
+, program needs setgid to be able to use it).
+.SS VARIABLES
+Variables can be specified in the config file. Their identifiers must start
+with the letter 
+.B "$"
+, 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.
+.SS AUTOMATIC VARIABLES
+Config file recognizes these automatic variables:
+.TP
+.B $MAIL_LEN
+refers to the length of the e-mail, including headers
+.TP
+.B $LAST_EXIT_CODE
+refers to the exit code of last external program executed (actions filter or
+pipe can be used to do it)
+.TP
+.B $LAST_OUTPUT
+refers to the output of last external program executed by action pipe
+.SS 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.
+.SS ASSIGNMENTS
+Assignment is specified in a following way:
+.P
+.B Lvalue = Rvalue ;
+.P
+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 
+.B .
+, 
+.B +
+, 
+.B -
+, 
+.B * 
+and 
+.B /
+, operation 
+.B . 
+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 parentheses.
+.SS ACTIONS
+Actions are specified with an arrow operator. Plain
+.TP
+.B -> ;
+means "deliver the e-mail to the default mailbox and exit".
+.TP
+.B -> expression ;
+means "deliver the e-mail the mailbox specified behind arrow and exit"
+.TP
+.B -> pipe expression ;
+means "pipe the e-mail to the external program specified behind pipe
+keyword". Output of the program is stored in 
+.B $LAST_OUTPUT
+variable, its exit code is stored in 
+.B $LAST_EXIT_CODE
+variable.
+.TP
+.B -> filter expression
+means "pipe the e-mail to the external program and replace it with output of the program". All the headers variables, 
+.B $MAIL_LEN
+and 
+.B $LAST_EXIT_CODE
+are set accordingly.
+.TP
+.B -> discard ;
+means just "discard the email and exit". 
+.TP
+.B -> mail expression ;
+means "forward the e-mail to the address specifed behind the mail keyword and exit"
+.TP -1
+If action fails, the e-mail is delivered to the default mailbox.
+.P
+Some of the actions (delivery or forwarding an e-mail) can have keyword copy
+in front of the arrow, ie.
+.P
+.B copy -> "mailbox";
+.P
+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.
+.SS CONDITIONS
+Conditional execution of commands can be specified in a following way:
+.P
+.B if (condition) { ... }
+.P
+.B if (condtion) { ... } else { ... }
+.P
+.B if (condition) { ... } else if { ... } [ else { ... } ]
+.P
+where the condition can be a constant, a variable or an expression consisting
+of following operations:
+.TP
+.B & 
+is binary boolean and
+.TP
+.B |
+is binary boolean or
+.TP
+.B ^ 
+is binary boolean xor
+.TP
+.B !
+is unary boolean not
+.TP -1
+A variable or a constant has a boolean value 0, if its value is either "" or
+"0" and 1 otherwise.
+.P
+Expressions can be compared using following binary relations.
+.P
+String comparisons:
+.P
+.TP
+.B ~~ 
+means "matches" (left operand should be string, right one can be a perl compatible regular expression)
+.TP
+.B !~ 
+means "does not match"
+.TP -1
+Integer comparisons (does not make sense on strings):
+.TP
+.B ==
+means "is equal to"
+.TP
+.B !=
+means "is not equal to"
+.TP
+.B <
+means "is lesser than"
+.TP
+.B >
+means "is greater than"
+.TP
+.B <=
+means "is lesser or equal than"
+.TP
+.B >=
+means "is greater or equal than"
+.TP -1
+Parentheses can be used to specify a precedence. Boolean operations have greater priority than relation operations.
+.SS COMMENTS
+All the text behind a hash character up to the end of the line is ignored.
+.SH EXIT STATUS
+.TP 
+.B 0
+Success
+.TP
+.B 1
+Failure
+.TP
+.B EX_TEMPFAIL
+Temporary OS failure
+.SH BUGS
+Aer prsenet.
+.SH TODO
+IMAP support.
+.SH AUTHOR
+Anicka <anicka@anicka.net>
+.SH RESOURCES
+Current version of the program can be downloaded at 
+.B http://www.anicka.net/umpf
+.SH COPYING
+The program can be used according to the terms of GPL, version 2.

diff --git a/umpf.man b/umpf.man
deleted file mode 100644 (file)
index c214596..0000000
--- a/umpf.man
+++ /dev/null
@@ -1,126 +0,0 @@
-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>