-.\" $Id: t-prot.1,v 1.99 2005/04/15 14:03:39 jochen Exp $
+.\" $Id: t-prot.1,v 1.129 2007/03/09 15:05:35 jochen Exp $
.\"
-.TH T-PROT "1" "Apr 2005" "T-PROT"
+.TH T-PROT "1" "December 2006" "T-PROT"
.SH NAME
-t-prot \- TOFU Protection - Display Filter for RFC 822 messages
+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 posts) 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
The filter is written in Perl and relies on input to be a single
-message conforming to RFC 822 or it's successor, RFC 2822. Messages
-conforming to RFCs 2045, 2046 and 2049 should be treated reasonably
-correct.
+message conforming to RFC 822 or its successor, RFC 2822. Messages
+conforming to RFCs 2045-2049 should be treated reasonably correct.
.PP
Already reformatted messages are handled well: the script was
initially designed to cope with the output of the MUA mutt (which
.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"
-Input consists just of the message's body. There are no RFC 822 header
+Input consists just of the message's body. There are no RFC 2822 header
lines.
-.br
+.IP
.IR NOTE :
This does not work with --pgp-short, and multipart messages will not
be detected due to missing headers.
.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
+Because these texts even have changing lengths we simply detect the
lines of the footer *anywhere* in the body of the message and assume that
everything below belongs to the footer. (Man, if life where always that
easy! ;)
.TP
.B "\-k"
"anti Kammquote":
-Tries to fix those broken zig-zag-shaped lines wrapped around by some MUAs
-which are known as "Kammquoting" in German.
-.sp
-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).
+Tries (not too aggressively) to fix those broken zig-zag-shaped lines
+wrapped around by some MUAs which are known as "Kammquoting" in German.
+.IP
+.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 and REPORTING BUGS
+section of this man page, that is).
+.IP
+Please also note that enabling this option is quite a performance hit.
.TP
.BR "\-\-kminl" =n
-Minimum line length for wrapped line detection on Kammquotes. Umm, don't
-know how to explain this well without describing the complete algorithm
-used. Please see the code.
+Minimum line length for wrapped line detection on Kammquotes. For
+details, please see the source code.
.br
Anyway, lower values make the algorithm more aggressive, higher values
make Kammquotes harder to detect. Default is 65.
.BR "\-k" .
.TP
.BR "\-\-kmaxl" =n
-Maximum line length for wrapped line detection on Kammquotes. Umm, don't
-know how to explain this well without describing the complete algorithm
-used. Please see the code.
+Maximum line length for wrapped line detection on Kammquotes. For
+details, please see the source code.
.br
Anyway, higher values make the algorithm more aggressive, lower values
make Kammquotes harder to detect. Default is 80.
.TP
.BR "\-\-kdiff" =n
Minimum length difference between two lines for wrapped line detection on
-Kammquotes. Umm, don't know how to explain this well without describing
-the complete algorithm used. Please see the code.
+Kammquotes. For details, please see the source code.
.br
Anyway, lower values make the algorithm more aggressive, higher values
make Kammquotes harder to detect. Default is 20.
.I "Locale::gettext"
for this feature.
.sp
-.IR Note :
+.IR NOTE :
If you use
.B mutt
or
.B gnupg
with locales, t-prot will only work correctly if you specify the corresponding
-locale string.
+locale string. Alternatively, you can use the environment variables
+.IR LC_ALL ,
+.IR LC_MESSAGES ,
+or
+.I LANG
+to specify the locale string.
.sp
-.IR "Note also" :
+.IR "NOTE also" :
You also have to make sure you are running t-prot
with matching
.B gnupg
.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
+.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
.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":
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
-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
-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
-.IR Note :
+.IR NOTE :
If gpg is terminated before finished (e.g. hitting Ctrl-C, or using
.IR kill (1)),
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
-Hide non-relevant pgp key uids; requires
+Hide non-relevant PGP key uids; requires
.BR "\-Mmutt" .
.TP
.B "\-r"
.BR "\-S" [=n]
"supression of overlong signatures":
Signatures are to be n lines (not including the one containing dash-dash-space)
-or less. If there are more, it is probably not that spirited after all. So
-with this option you trade it for a
+or less. If there are more, it is probably not that spirited after all.
+So with this option you trade it for a
.B truely
nice line.
.br
-If no n is given, default is 4. (\fINote\fR: We do not recommend using a
-value other than 4. Consider this old-fashioned, but we actually do *like*
-RFC conformance.)
+If no n is given, default is 4. (We do not recommend using a value other
+than 4. Consider this old-fashioned, but we actually do *like* RFC
+conformance.)
.sp
-.IR Note :
+.IR NOTE :
The line containing "-- " ist not counted when testing for an overlong
signature, but it is included when displaying how many lines were deleted.
.TP
.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 ,
+.IR LC_MESSAGES ,
+and
+.I LANG
+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
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 :
I want to make my mailing list footer files match more different mailing
-list footers. Can I use regular expressions, or how can I accomplish that?
+list footers. Can I use regular expressions, or how can I accomplish
+that?
.TP
.IR A :
-Nope, regexp's do not work here. The comparison is made by the perl builtin
+Nope, regexp's do not work here. The comparison is made by the perl
+builtin
.IR index ()
function (see
.B perldoc
#v-
.br
Text coming now is not.
-.SH AUTHOR AND COPYRIGHT
+.SH AUTHOR
Written by Jochen Striepe <t-prot@tolot.escape.de>.
-.br
-Copyright \(co 2001-2005 Jochen Striepe.
+.SH COPYRIGHT
+All of the documentation and software included in the t-prot releases
+is copyrighted by Jochen Striepe (except when explicitely stated otherwise).
+.PP
+Copyright \(co 2001-2006 Jochen Striepe. All rights reserved.
+.PP
+Redistribution and use, with or without modification, are permitted
+provided that the following conditions are met:
+.PP
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
.PP
-This is free software; you may use the source to whatever you like.
-Just keep in mind to mention the original source of the script and the manpage
-when you give it away. There is NO warranty; not even for MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.
+2. All advertising materials mentioning features or use of this software
+must display the following acknowledgement:
+.PP
+ This product includes software developed by Jochen Striepe and others.
+.PP
+3. Neither the name of the author nor the names of any contributors may
+be used to endorse or promote products derived from this software without
+specific prior written permission.
+.PP
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH IDEAS AND INSPIRATION
Many good ideas, bug reports and support from (in alphabetical order) Bjoern
Buerger, Bjoern Laessig, Christian Borss, Gerfried Fuchs, Martin Neitzel, Martin
in order to keep the responses to his cancel bot reasonably short. The
entire inspiration for this hack came from the "TOFU protection" line of
his script on many usenet postings.
-.SH AVAILIBILITY
+.SH AVAILABILITY
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
-in your bug report. Thank you.
+in your bug report.
.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.
+Please do
+.I not
+report a bug if
+.br
+ * you found it in the TODO file coming with the distribution. We do
+know those and try to fix them as soon as possible.
+.br
+ * you have an old t-prot version. If you encounter a problem, first
+see if there is a new t-prot version which fixes the issue. If you
+upgraded to the latest version and it still occurs, a bug report is
+just great.
.PP
-There probably are many more bugs in this piece of software. Feel free to
-fix them - it's
-.BR perl ,
-so you have the sources. Ah, and while you're at it, please drop a note to
-the author - thanks in advance!
-.SH "REPORTING BUGS"
-Please send your bug report to <t-prot-bugs@tolot.escape.de>.
+If you noticed a bug when processing a message and want to provide the
+t-prot team with some useful info, please:
+.br
+ * if invoking t-prot by mutt's
+.I display_filter
+facility, just set display_filter to something like
+.IP
+"tee ~/foobar | t-prot <your options>"
+.PP
+and include ~/foobar in the bug report -- this way we might reproduce
+the bug much easier if you are using a different environment than we do.
+.br
+ * provide information on what command line options you use t-prot
+with, what perl version t-prot runs on your system, and what else might
+be important to enable us reproducing the bug.
+.PP
+Send your bug report to
+.IR <t-prot-bugs@tolot.escape.de> .
+Thank you.
.SH TODO
Fix bugs (see the
.I BUGS
section). Beside that, all main features should be implemented by now.
+See the TODO file for more information.
.SH "SEE ALSO"
.BR mutt (1),
.BR muttrc (5)
and the part about "display_filter",
.BR perl (1),
.BR aliases (5),
-RFCs 822, 2045, 2046, 2049, and 2822,
+.sp
+RFCs 2045-2049 and 2822,
+.sp
.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).
projects / pkg / t-prot.git / blobdiff