| 1 |
.\"if n .pl +(135i-\n(.pu) |
| 2 |
.de Id |
| 3 |
.ds Rv \\$3 |
| 4 |
.ds Dt \\$4 |
| 5 |
.. |
| 6 |
.Id $Id: procmailsc.man,v 1.15 2001/08/04 06:08:22 guenther Exp $ |
| 7 |
.TH PROCMAILSC 5 \*(Dt BuGless |
| 8 |
.rn SH Sh |
| 9 |
.de SH |
| 10 |
.br |
| 11 |
.ne 11 |
| 12 |
.Sh "\\$1" |
| 13 |
.. |
| 14 |
.rn SS Ss |
| 15 |
.de SS |
| 16 |
.br |
| 17 |
.ne 10 |
| 18 |
.Ss "\\$1" |
| 19 |
.. |
| 20 |
.rn TP Tp |
| 21 |
.de TP |
| 22 |
.br |
| 23 |
.ne 9 |
| 24 |
.Tp \\$1 |
| 25 |
.. |
| 26 |
.rn RS Rs |
| 27 |
.de RS |
| 28 |
.na |
| 29 |
.nf |
| 30 |
.Rs |
| 31 |
.. |
| 32 |
.rn RE Re |
| 33 |
.de RE |
| 34 |
.Re |
| 35 |
.fi |
| 36 |
.ad |
| 37 |
.. |
| 38 |
.de Sx |
| 39 |
.PP |
| 40 |
.ne \\$1 |
| 41 |
.RS |
| 42 |
.. |
| 43 |
.de Ex |
| 44 |
.RE |
| 45 |
.PP |
| 46 |
.. |
| 47 |
.na |
| 48 |
.SH NAME |
| 49 |
procmailsc \- procmail weighted scoring technique |
| 50 |
.SH SYNOPSIS |
| 51 |
.RB [ * ] |
| 52 |
.B "w^x condition" |
| 53 |
.ad |
| 54 |
.SH DESCRIPTION |
| 55 |
In addition to the traditional true or false conditions you can specify |
| 56 |
on a recipe, you can use a weighted scoring technique to decide if |
| 57 |
a certain recipe matches or not. When weighted scoring is used in a |
| 58 |
recipe, then the final score for that recipe must be positive for it |
| 59 |
to match. |
| 60 |
|
| 61 |
A certain condition can contribute to the score if you allocate it |
| 62 |
a `weight' |
| 63 |
.RB ( w ) |
| 64 |
and an `exponent' |
| 65 |
.RB ( x ). |
| 66 |
You do this by preceding the condition (on the same line) with: |
| 67 |
.RS |
| 68 |
.B w^x |
| 69 |
.RE |
| 70 |
Whereas both |
| 71 |
.B w |
| 72 |
and |
| 73 |
.B x |
| 74 |
are real numbers between -2147483647.0 and 2147483647.0 inclusive. |
| 75 |
|
| 76 |
.SH "Weighted regular expression conditions" |
| 77 |
The first time the regular expression is found, it will add |
| 78 |
.I w |
| 79 |
to the score. The second time it is found, |
| 80 |
.I w*x |
| 81 |
will be added. The third time it is found, |
| 82 |
.I w*x*x |
| 83 |
will be added. The fourth time |
| 84 |
.I w*x*x*x |
| 85 |
will be added. And so forth. |
| 86 |
|
| 87 |
This can be described by the following concise formula: |
| 88 |
.Sx 4 |
| 89 |
n |
| 90 |
n k\-1 x \- 1 |
| 91 |
w * Sum x = w * \-\-\-\-\-\-\- |
| 92 |
k=1 x \- 1 |
| 93 |
.Ex |
| 94 |
It represents the total added score for this condition if |
| 95 |
.B n |
| 96 |
matches are found. |
| 97 |
|
| 98 |
Note that the following case distinctions can be made: |
| 99 |
.TP 8 |
| 100 |
x=0 |
| 101 |
Only the first match will contribute w to the score. Any subsequent |
| 102 |
matches are ignored. |
| 103 |
.TP |
| 104 |
x=1 |
| 105 |
Every match will contribute the same w to the score. The score grows |
| 106 |
linearly with the number of matches found. |
| 107 |
.TP |
| 108 |
0<x<1 |
| 109 |
Every match will contribute less to the score than the previous one. |
| 110 |
The score will asymptotically approach a certain value (see the |
| 111 |
.B NOTES |
| 112 |
section below). |
| 113 |
.TP |
| 114 |
1<x |
| 115 |
Every match will contribute more to the score than the previous one. |
| 116 |
The score will grow exponentially. |
| 117 |
.TP |
| 118 |
x<0 |
| 119 |
Can be utilised to favour odd or even number of matches. |
| 120 |
.PP |
| 121 |
If the regular expression is negated (i.e., matches if it isn't found), |
| 122 |
then |
| 123 |
.B n |
| 124 |
obviously can either be zero or one. |
| 125 |
.SH "Weighted program conditions" |
| 126 |
If the program returns an exitcode of EXIT_SUCCESS (=0), then the total |
| 127 |
added score will be |
| 128 |
.BR w . |
| 129 |
If it returns any other exitcode (indicating failure), the total added |
| 130 |
score will be |
| 131 |
.BR x . |
| 132 |
.PP |
| 133 |
If the exitcode of the program is negated, then, the exitcode will |
| 134 |
be considered as if it were a virtual number of matches. Calculation |
| 135 |
of the added score then proceeds as if it had been a normal regular |
| 136 |
expression with |
| 137 |
.B n=`exitcode' |
| 138 |
matches. |
| 139 |
.SH "Weighted length conditions" |
| 140 |
If the length of the actual mail is |
| 141 |
.B M |
| 142 |
then: |
| 143 |
.Sx 1 |
| 144 |
* w^x > L |
| 145 |
.Ex |
| 146 |
will generate an additional score of: |
| 147 |
.Sx 4 |
| 148 |
x |
| 149 |
/ M \e |
| 150 |
w * | \-\-\- | |
| 151 |
\e L / |
| 152 |
.Ex |
| 153 |
And: |
| 154 |
.Sx 1 |
| 155 |
* w^x < L |
| 156 |
.Ex |
| 157 |
will generate an additional score of: |
| 158 |
.Sx 4 |
| 159 |
x |
| 160 |
/ L \e |
| 161 |
w * | \-\-\- | |
| 162 |
\e M / |
| 163 |
.Ex |
| 164 |
.PP |
| 165 |
In both cases, if L=M, this will add w to the score. In the former case |
| 166 |
however, larger mails will be favoured, in the latter case, smaller |
| 167 |
mails will be favoured. Although x can be varied to fine-tune the |
| 168 |
steepness of the function, typical usage sets x=1. |
| 169 |
.SH MISCELLANEOUS |
| 170 |
You can query the final score of all the conditions on a recipe from the |
| 171 |
environment variable |
| 172 |
.BR $= . |
| 173 |
This variable is set |
| 174 |
.I every |
| 175 |
time just after procmail has parsed all conditions on a recipe (even if the |
| 176 |
recipe is not being executed). |
| 177 |
.SH EXAMPLES |
| 178 |
The following recipe will ditch all mails having more than 150 lines in the |
| 179 |
body. |
| 180 |
The first condition contains an empty regular expression which, because |
| 181 |
it always matches, is used to give our score a negative offset. |
| 182 |
The second condition then matches every line in the mail, and consumes |
| 183 |
up the previous negative offset we gave (one point per line). In the end, |
| 184 |
the score will only be positive if the mail contained more than 150 lines. |
| 185 |
.Sx 5 |
| 186 |
:0 Bh |
| 187 |
* \-150^0 |
| 188 |
* 1^1 ^.*$ |
| 189 |
/dev/null |
| 190 |
.Ex |
| 191 |
Suppose you have a priority folder which you always read first. The next |
| 192 |
recipe picks out the priority mail and files them in this special folder. |
| 193 |
The first condition is a regular one, i.e., it doesn't contribute to the |
| 194 |
score, but simply has to be satisfied. The other conditions describe things |
| 195 |
like: john and claire usually have something important to say, meetings |
| 196 |
are usually important, replies are favoured a bit, mails about Elvis |
| 197 |
(this is merely an example :\-) are favoured (the more he is mentioned, the |
| 198 |
more the mail is favoured, but the maximum extra score due to Elvis will |
| 199 |
be 4000, no matter how often he is mentioned), lots of quoted lines are |
| 200 |
disliked, smileys are appreciated (the score for those will reach a maximum |
| 201 |
of 3500), those three people usually don't send |
| 202 |
interesting mails, the mails should preferably be small (e.g., 2000 bytes long |
| 203 |
mails will score \-100, 4000 bytes long mails do \-800). |
| 204 |
As you see, if some of the uninteresting people send mail, then the mail |
| 205 |
still has a chance of landing in the priority folder, e.g., if it is about |
| 206 |
a meeting, or if it contains at least two smileys. |
| 207 |
.Sx 11 |
| 208 |
:0 HB |
| 209 |
* !^Precedence:.*(junk|bulk) |
| 210 |
* 2000^0 ^From:.*(john@home|claire@work) |
| 211 |
* 2000^0 ^Subject:.*meeting |
| 212 |
* 300^0 ^Subject:.*Re: |
| 213 |
* 1000^.75 elvis|presley |
| 214 |
* \-100^1 ^> |
| 215 |
* 350^.9 :\-\e) |
| 216 |
* \-500^0 ^From:.*(boss|jane|henry)@work |
| 217 |
* \-100^3 > 2000 |
| 218 |
priority_folder |
| 219 |
.Ex |
| 220 |
If you are subscribed to a mailinglist, and just would like to read |
| 221 |
the quality mails, then the following recipes could do the trick. |
| 222 |
First we make sure that the mail is coming from the mailinglist. |
| 223 |
Then we check if it is from certain persons of whom we value |
| 224 |
the opinion, or about a subject we absolutely want to know everything |
| 225 |
about. If it is, file it. Otherwise, check if the ratio of quoted lines |
| 226 |
to original lines is at most 1:2. If it exceeds that, ditch the mail. |
| 227 |
Everything that survived the previous test, is filed. |
| 228 |
.Sx 15 |
| 229 |
:0 |
| 230 |
^From [email protected] |
| 231 |
{ |
| 232 |
:0: |
| 233 |
* ^(From:.*(paula|bill)|Subject:.*skiing) |
| 234 |
mailinglist |
| 235 |
|
| 236 |
:0 Bh |
| 237 |
* 20^1 ^> |
| 238 |
* \-10^1 ^[^>] |
| 239 |
/dev/null |
| 240 |
|
| 241 |
:0: |
| 242 |
mailinglist |
| 243 |
} |
| 244 |
.Ex |
| 245 |
For further examples you should look in the |
| 246 |
.BR procmailex (5) |
| 247 |
man page. |
| 248 |
.SH CAVEATS |
| 249 |
Because this speeds up the search by an order of magnitude, |
| 250 |
the procmail internal egrep will always search for the leftmost |
| 251 |
.I shortest |
| 252 |
match, unless it is determining what to assign to |
| 253 |
.BR MATCH , |
| 254 |
in which case it searches the leftmost |
| 255 |
.I longest |
| 256 |
match. |
| 257 |
E.g. for the leftmost |
| 258 |
.I shortest |
| 259 |
match, by itself, the regular expression: |
| 260 |
.TP |
| 261 |
.B .* |
| 262 |
will always match a zero length string at the same spot. |
| 263 |
.TP |
| 264 |
.B .+ |
| 265 |
will always match one character (except newlines of course). |
| 266 |
.SH "SEE ALSO" |
| 267 |
.na |
| 268 |
.nh |
| 269 |
.BR procmail (1), |
| 270 |
.BR procmailrc (5), |
| 271 |
.BR procmailex (5), |
| 272 |
.BR sh (1), |
| 273 |
.BR csh (1), |
| 274 |
.BR egrep (1), |
| 275 |
.BR grep (1), |
| 276 |
.hy |
| 277 |
.ad |
| 278 |
.SH BUGS |
| 279 |
If, in a length condition, you specify an |
| 280 |
.B x |
| 281 |
that causes an overflow, procmail is at the mercy of the |
| 282 |
.BR pow (3) |
| 283 |
function in your mathematical library. |
| 284 |
.PP |
| 285 |
Floating point numbers in `engineering' format (e.g., 12e5) are not accepted. |
| 286 |
.SH MISCELLANEOUS |
| 287 |
As soon as `plus infinity' (2147483647) is reached, any subsequent |
| 288 |
.I weighted |
| 289 |
conditions will simply be skipped. |
| 290 |
.PP |
| 291 |
As soon as `minus infinity' (-2147483647) is reached, the condition will |
| 292 |
be considered as `no match' and the recipe will terminate early. |
| 293 |
.SH NOTES |
| 294 |
If in a regular expression weighted formula |
| 295 |
.BR 0<x<1 , |
| 296 |
the total added score for this condition will asymptotically approach: |
| 297 |
.Sx 3 |
| 298 |
w |
| 299 |
\-\-\-\-\-\-\- |
| 300 |
1 \- x |
| 301 |
.Ex |
| 302 |
In order to reach half the maximum value you need |
| 303 |
.Sx 3 |
| 304 |
\- ln 2 |
| 305 |
n = \-\-\-\-\-\-\-\- |
| 306 |
ln x |
| 307 |
.Ex |
| 308 |
matches. |
| 309 |
.SH AUTHORS |
| 310 |
Stephen R. van den Berg |
| 311 |
.RS |
| 312 |
<[email protected]> |
| 313 |
.RE |
| 314 |
Philip A. Guenther |
| 315 |
.RS |
| 316 |
<[email protected]> |
| 317 |
.RE |
| 318 |
.\".if n .pl -(\n(.tu-1i) |
| 319 |
.rm SH |
| 320 |
.rn Sh SH |
| 321 |
.rm SS |
| 322 |
.rn Ss SS |
| 323 |
.rm TP |
| 324 |
.rn Tp TP |
| 325 |
.rm RS |
| 326 |
.rn Rs RS |
| 327 |
.rm RE |
| 328 |
.rn Re RE |