Merge branch 'upstream'

[pkg/t-prot.git] / t-prot.1

diff --git a/t-prot.1 b/t-prot.1
index 00ee120188c8b17e8a928807604a8a1fa728cf62..a503ce0e875cbf6647b1f04f5ab2d214d7d8fe13 100644 (file)
--- a/t-prot.1
+++ b/t-prot.1
@@ -1,14 +1,14 @@
-.\" $Id: t-prot.1,v 1.115 2005/05/13 00:06:10 jochen Exp $
+.\" $Id: t-prot.1,v 1.134 2009/08/24 01:44:27 jochen Exp $

 .\"
 .\"

-.TH T-PROT "1" "May 2005" "T-PROT"
+.TH T-PROT "1" "August 2009" "T-PROT"

 .SH NAME
 t-prot \- TOFU Protection - Display Filter for RFC 2822 messages
 .SH SYNOPSIS
 .BI "t-prot [" OPTIONS "]..."
 .SH DESCRIPTION
 .PP
 .SH NAME
 t-prot \- TOFU Protection - Display Filter for RFC 2822 messages
 .SH SYNOPSIS
 .BI "t-prot [" OPTIONS "]..."
 .SH DESCRIPTION
 .PP

-This program is a filter which shall improve the readability for
-messages (emails and usenet postings) by *hiding* some annoying parts,
+This program is a filter to improve the readability of
+messages (emails and usenet posts) by *hiding* some annoying parts,

 e.g. mailing list footers, signatures, and TOFU (see definition below),
 as well as squeezing sequences of blank lines or punctuation.
 .br
 e.g. mailing list footers, signatures, and TOFU (see definition below),
 as well as squeezing sequences of blank lines or punctuation.
 .br


@@ -63,7 +63,7 @@ is specified.
 .TP
 .BR "\-\-bigq" [=n[,x]]
 "shrink big quotes":
 .TP
 .BR "\-\-bigq" [=n[,x]]
 "shrink big quotes":

-Blocks of quotes with more than n lines will be shrinked to x lines.
+Blocks of quotes with more than n lines will be shrunk to x lines.

 Defaults are 30 for n and 10 for x.
 .TP
 .B "\-\-body"
 Defaults are 30 for n and 10 for x.
 .TP
 .B "\-\-body"


@@ -114,7 +114,7 @@ to only three dots or marks, respectively.
 .TP
 .B "\-\-ftr\-ad"
 "enable aggressive ad footer matching":
 .TP
 .B "\-\-ftr\-ad"
 "enable aggressive ad footer matching":

-With this option enabled t-prot makes footer detection really greedy: We
+With this option enabled, t-prot makes footer detection really greedy: We

 assume that commercial email providers aren't even frightened to append
 changing texts *under* their ads which are appended to the message body.
 Because these texts even have changing lengths we simply detect the
 assume that commercial email providers aren't even frightened to append
 changing texts *under* their ads which are appended to the message body.
 Because these texts even have changing lengths we simply detect the


@@ -143,6 +143,10 @@ Works similar to --ftr-ad, just that it is intended for mailing list footers.
 This requires a directory with footer files to be given with option
 .BR "\-L" =DIRECTORY.
 .TP
 This requires a directory with footer files to be given with option
 .BR "\-L" =DIRECTORY.
 .TP

+.B "\-\-groupwise"
+"delete Groupwise style TOFU":
+Hides TOFU as produced by Novell Groupwise.
+.TP

 .B "\-h, \-\-help"
 "help":
 Displays a short help text with a summary on all options, and exits.
 .B "\-h, \-\-help"
 "help":
 Displays a short help text with a summary on all options, and exits.


@@ -159,7 +163,8 @@ wrapped around by some MUAs which are known as "Kammquoting" in German.
 .IR NOTE :
 This option is considered stable by now. However, sometimes Kammquotes
 should have been removed but weren't. Please send a bug report if this
 .IR NOTE :
 This option is considered stable by now. However, sometimes Kammquotes
 should have been removed but weren't. Please send a bug report if this

-happens to you (after carefully reading the BUGS file, that is).
+happens to you (after carefully reading the BUGS and REPORTING BUGS
+section of this man page, that is).

 .IP
 Please also note that enabling this option is quite a performance hit.
 .TP
 .IP
 Please also note that enabling this option is quite a performance hit.
 .TP


@@ -262,12 +267,21 @@ and
 .B mutt
 locales of the recent stable versions of those programs, earlier versions
 might not work well with a recent version of t-prot. There are patches available
 .B mutt
 locales of the recent stable versions of those programs, earlier versions
 might not work well with a recent version of t-prot. There are patches available

-to make t-prot fit into environments with old
+to make t-prot fit into environments with some other

 .B mutt
 and
 .B gnupg
 versions.
 .TP
 .B mutt
 and
 .B gnupg
 versions.
 .TP

+.BR "\-M, \-\-mua" =MUA
+"mail user agent":
+Turn on special treatment for some mail user agents. (Right now only 
+.BR mutt (1)
+is supported, but more might be added in future.)
+.IR Caveat :
+If your MUA is supported by this feature you must ensure t-prot makes
+use of it when called from within your MUA to work as desired.
+.TP

 .B "\-m"
 "Microsoft TOFU":
 Hides TOFU as given by some Microsoft mailers. (You all surely know these
 .B "\-m"
 "Microsoft TOFU":
 Hides TOFU as given by some Microsoft mailers. (You all surely know these


@@ -291,14 +305,9 @@ Requires
 .BR "\-Mmutt" " and"
 .BR "\-m" .
 .TP
 .BR "\-Mmutt" " and"
 .BR "\-m" .
 .TP

-.BR "\-M, \-\-mua" =MUA
-"mail user agent":
-Turn on special treatment for some mail user agents. (Right now only 
-.BR mutt (1)
-is supported, but more might be added in future.)
-.IR Caveat :
-If your MUA is supported by this feature you must ensure t-prot makes
-use of it when called from within your MUA to work as desired.
+.BR "\-\-max\-lines" =x
+Maximum number of lines a message body may count. If the body is longer
+than x lines, the message will not be processed but printed unmodified.

 .TP
 .BR "\-o" =FILE
 "output file":
 .TP
 .BR "\-o" =FILE
 "output file":


@@ -341,13 +350,13 @@ You may specify your own bounce message to be returned when we try to deliver
 an email and bounce it because there is TOFU inside.
 .TP
 .B \-\-pgp\-move
 an email and bounce it because there is TOFU inside.
 .TP
 .B \-\-pgp\-move

-Move pgp verification output to bottom; requires
+Move PGP verification output to bottom; requires

 .BR "\-Mmutt" .
 .TP
 .B \-\-pgp\-move\-vrf
 .BR "\-Mmutt" .
 .TP
 .B \-\-pgp\-move\-vrf

-Move pgp verification outout to bottom only if verification shows a good signature
+Move PGP verification outout to bottom only if verification shows a good signature

 and the signature could be verified as authentic (using a trust path). If there is
 and the signature could be verified as authentic (using a trust path). If there is

-any problem with the signature, the pgp output should not be moved so the user is
+any problem with the signature, the PGP output should not be moved so the user is

 more likely to notice. Requires
 .BR "\-Mmutt" .
 .sp
 more likely to notice. Requires
 .BR "\-Mmutt" .
 .sp


@@ -358,7 +367,7 @@ we cannot always detect if the check was interrupted. Though t-prot tries
 to be smart, there will be false positives.
 .TP
 .B \-\-pgp\-short
 to be smart, there will be false positives.
 .TP
 .B \-\-pgp\-short

-Hide non-relevant pgp key uids; requires
+Hide non-relevant PGP key uids; requires

 .BR "\-Mmutt" .
 .TP
 .B "\-r"
 .BR "\-Mmutt" .
 .TP
 .B "\-r"


@@ -422,7 +431,7 @@ between mailing lists or with undetected signature attempts.
 .TP
 .B "\-v, \-\-version"
 "version info":
 .TP
 .B "\-v, \-\-version"
 "version info":

-Prints the current version number and release date, and exit.
+Prints the current version number and release date, and exits.

 .SH ENVIRONMENT
 The environment variables
 .IR LC_ALL ,
 .SH ENVIRONMENT
 The environment variables
 .IR LC_ALL ,


@@ -432,6 +441,32 @@ and
 are read and respected when interpreting output by mutt or gnupg
 (unless they are overruled by the --locale option). T-prot's own
 output is English regardless of any locale setting.
 are read and respected when interpreting output by mutt or gnupg
 (unless they are overruled by the --locale option). T-prot's own
 output is English regardless of any locale setting.

+.SH EXIT STATUS
+On program exit, t-prot uses exit codes from
+.I /usr/include/sysexits.h
+and thus behaves in a manner that sendmail and others understand when
+calling t-prot.
+.sp
+Currently, the codes used are
+.RS 20
+.PD 0
+.TP
+EX_OK
+.TP
+EX_USAGE
+.TP
+EX_DATAERR
+.TP
+EX_UNAVAILABLE
+.TP
+EX_SOFTWARE
+.TP
+EX_IOERR
+.PD
+.RE
+.sp
+If, however, perl fails to compile and execute t-prot, perl's normal
+exit codes will be returned.

 .SH TOFU?
 TOFU is an abbreviation which mixes German and English words;
 it expands to "text oben, full-quote unten" which means
 .SH TOFU?
 TOFU is an abbreviation which mixes German and English words;
 it expands to "text oben, full-quote unten" which means


@@ -444,6 +479,21 @@ even when it is not required. Some editing of messages is desired.
 Please point these people to the page 
 .I http://www.river.com/users/share/etiquette/edit.html
 - thank you!
 Please point these people to the page 
 .I http://www.river.com/users/share/etiquette/edit.html
 - thank you!

+.SH PERFORMANCE
+There are several ways to fine-tune t-prot's performance:
+.PP
+Some command line options are quite grave a performance hit -- do not
+use -k and especially --ms-smart if you are content without them.
+.PP
+Checking for special footers is very costly as well. Put as few footer
+files as absolutely needed in any footer directory.
+.PP
+All PGP related options are eating up lots of CPU time. Try to avoid them
+on unsigned and unencrypted messages.
+.PP
+When calling t-prot from within mutt, you might use mutt's folder-hook
+and message-hook facilities to turn options on only when needed, e.g. to
+set up a different footer directory for each mailing list folder.

 .SH TROUBLESHOOTING
 .TP
 .IR Q :
 .SH TROUBLESHOOTING
 .TP
 .IR Q :


@@ -503,9 +553,9 @@ Text coming now is not.
 Written by Jochen Striepe <t-prot@tolot.escape.de>.
 .SH COPYRIGHT
 All of the documentation and software included in the t-prot releases
 Written by Jochen Striepe <t-prot@tolot.escape.de>.
 .SH COPYRIGHT
 All of the documentation and software included in the t-prot releases

-is copyrighted by Jochen Striepe.
+is copyrighted by Jochen Striepe (except when explicitly stated otherwise).

 .PP
 .PP

-Copyright \(co 2001-2005 Jochen Striepe. All rights reserved.                     
+Copyright \(co 2001-2009 Jochen Striepe. All rights reserved.                     

 .PP
 Redistribution and use, with or without modification, are permitted
 provided that the following conditions are met:
 .PP
 Redistribution and use, with or without modification, are permitted
 provided that the following conditions are met:


@@ -546,20 +596,20 @@ his script on many usenet postings.
 You can get the latest version from
 .IR http://www.escape.de/users/tolot/mutt/ .
 .SH BUGS
 You can get the latest version from
 .IR http://www.escape.de/users/tolot/mutt/ .
 .SH BUGS

+There is a problem when mutt gives a PGP verified or even a multipart
+message to t-prot: The information where the PGP encrypted/signed data
+or even attachments begin and end is plainly embedded in the text, not
+really cleanly recognizeable for t-prot. The problem should be worked
+around by now, please send a bug report if it does not work for you.
+.SH "REPORTING BUGS"

 Please note that t-prot development happens on
 .BR "current stable perl versions only" . 
 If you do run t-prot on earlier (or unstable) perl versions, you might
 encounter perl compiler bugs (or funny t-prot behaviour). One solution
 is to upgrade your perl, another is simply to write a bug report. If
 you do not run a current perl version, please include this information
 Please note that t-prot development happens on
 .BR "current stable perl versions only" . 
 If you do run t-prot on earlier (or unstable) perl versions, you might
 encounter perl compiler bugs (or funny t-prot behaviour). One solution
 is to upgrade your perl, another is simply to write a bug report. If
 you do not run a current perl version, please include this information

-in your bug report. Thank you.
+in your bug report.

 .PP
 .PP

-There is a problem when mutt gives a PGP verified or even a multipart
-message to t-prot: The information where the PGP encrypted/signed data
-or even attachments begin and end is plainly embedded in the text, not
-really cleanly recognizeable for t-prot. The problem should be worked
-around by now, please send a bug report if it does not work for you.
-.SH "REPORTING BUGS"

 Please do
 .I not
 report a bug if
 Please do
 .I not
 report a bug if


@@ -602,9 +652,12 @@ See the TODO file for more information.
 and the part about "display_filter", 
 .BR perl (1),
 .BR aliases (5),
 and the part about "display_filter", 
 .BR perl (1),
 .BR aliases (5),

+.sp

 RFCs 2045-2049 and 2822,
 RFCs 2045-2049 and 2822,

+.sp

 .I http://got.to/quote/
 .I http://got.to/quote/

-(German language), 
+(German language),
+.br

 .I http://www.river.com/users/share/etiquette/edit.html
 (the Learn To Edit Messages HowTo has found a new home).
 
 .I http://www.river.com/users/share/etiquette/edit.html
 (the Learn To Edit Messages HowTo has found a new home).