# $Id: gubby.pod,v 1.21 2004/12/16 16:18:46 cslsublevel3org Exp $

=pod

=head1 NAME

gubby - The procmail new email agent - v0.5.5

=head1 SYNPOSIS

B<gubby> [B<hvcowlVbsH>] [B<BmMpC> value] [B<procmail logfile>]

=head1 DESCRIPTION

Gubby keeps track of I<when> and I<where> procmail delivers your email.

=head1 LONGER DESCRIPTION

Scans a procmail logfile and display a realtime-updated display
of mailboxes and new email.  Reads mailbox contents using a specified
external mailreader (or MUA).

Output is normally displayed in a curses environment, but can also be
printed conveniently to the standard output from the command prompt.

Gubby is a compact, efficient and powerful ``once-and-for-all'' rewrite
of an old shell script.

=head1 GUESSING THE LOGFILE LOCATION

If called without arguments, B<gubby> searches for a procmail
configuration file in I<$HOME/.procmailrc>, scans it for a line
beginning with B<LOGFILE=>, and finally tries to parse the procmail
logfile.

A complaint is filed to stderr if no files are found, and you'll
have to supply the location of the file as a program argument.

=head1 SETTING UP PROCMAIL

For B<gubby> to work, you must enable logging in your procmail configuration
file.  This is done by adding a line such as B<LOGFILE=~/.log-procmail> near the
top.

=head1 OPTIONS

=over 4 

=item B<-h>

Print help and exit.

=item B<-v>

Print version info and exit.

=item B<-c>

Empty logfile and exit.

=item B<-m> I<path>

Specifies which program Gubby calls to read your mailboxes.

=item B<-M> I<path>

Specifies path to your local mailboxes.  If this is set in
your ~/.procmailrc file as B<MAILDIR=...>, then this is the
directory used. (This is only true when no logfile is specified
as a program parameter)

=item B<-p> I<args>

Used with B<-m>.  Specifies program arguments to your mailreader
when Gubby launches it to read a mailbox.  These parameters should
be the one telling your mailreader to "read this mailbox: ...".

For instance, with Mutt, the argument is "-f", and the corresponding
command Gubby will execute when a mailbox is selected for reading
will be:  B<mutt -f mailboxname>

=item B<-C> I<args>

Used with B<-m>.  Specifies which arguments are needed for your
mailprogram to start composing a new mail.

=item B<-o>

Print new mail and exit.

=item B<-w>

Used with B<-o>.  Prints folders in I<wide> listing format, meaning
that mailbox contents (i.e., I<From> and I<Subject> values) are printed
as well.

=item B<-b>

Triggers the terminal bell (beep) on new mail.

This may not be as annoying as it sounds.  Some terminal emulators can
be configured what to do on terminal bells.  For instance, PuTTY (a terminal
emulator) can make the window taskbar flash on bells.

=item B<-s>

Used with B<-b>:  Do not trigger bell when new mail is thrown in /dev/null.

=item B<-H>

Do not show /dev/null as a folder in the view at all.

=item B<-l>

Start Gubby in curses environment. (default)

=item B<-V>

Be verbose:  Send warnings and notices to stderr (I<deprecated>; all errors
are written to stderr).

=back

=head1 RETURN

=over 4 

=item B<0>

Successful exit

=item B<1>

General Error

=back

=over 4

=back

=head1 SIGNALS

Gubby catches SIGSEGV and SIGINT, both causing Gubby to gracefully shut down it's
curses environment before exiting with status 1.

=head1 FILES

=over 4

=item F<$HOME/.procmailrc>

If no logfile is specified as a program parameter, Gubby will try to read I<LOGFILE>
(and, optionally, I<MAILDIR>) from your $HOME/.procmailrc configuration file.  If
that doesn't exist, Gubby will exit with a complaint to stderr.

=back

=head1 EXAMPLES

=over 4

=item B<gubby ~/.log-procmail>

Run gubby and read from ~/.log-procmail

=item B<gubby -m /usr/bin/mutt -M ~/mail/ -p '-f'>

Run gubby on procmail logfile specified in F<$HOME/.procmailrc>, use F</usr/bin/mutt>
as a mailreader.  When a folder is selected, the command F</usr/bin/mutt -f ~/mail/foldername>
will be executed.

=item B<gubby -o>

Read Procmai logfile (finding its path from F<$HOME/.procmailrc>), print its contents in
a formatted and sorted style, and exit.

=item B<gubby>

Try to find Procmail logfile from F<$HOME/.procmailrc> and enter curses environment for
displaying folders. Default mailreader is B<mutt>.

=back

=head1 SEE ALSO

procmail(1),
procmailrc(5),
procmailex(5),
curses(3),
ncurses(3),
gpl(7)

=head1 BUGS

I've had trouble with gubby messing up the screen when going back from
suspended mode.  E.g., enter a folder by hitting enter (usually enters
mutt), start composing a new mail (with e.g. vim) and then suspend
everything with CTRL+Z.  When you do an "fg" again, somehow the screen is
totally messed up.

Other than that, the new "write to logfile" (the 'd'-key in the program
view) does not write correct procmail logfiles, so use this one with
caution.  It's there because it works on MY system, but I need feedback from
users before I'll remove the "experimental" warning.

Other issues:

If B<gubby> has trouble finding your Procmail logfile, be sure to specify
it as the last argument.

If you terminal is messed up, try setting the TERM variable to another value.
On Cygwin, I've had to set TERM=xterm og TERM=xterm-color instead of TERM=cygwin
to get curses to draw to the screen properly.

If you don't get colors, try setting TERM=xterm-colors

If Gubby for some reason can't find your mailboxes, try setting the full path
for your maildirectory as I<MAILDIR=...> in your Procmail rc file.

If you experience any other bugs, let me know!

=head1 ACKNOWLEDGEMENTS

Thanks to Michael Hostbaek for maintaining the FreeBSD port of Gubby.

Thanks to Jone Lima and Arne Kjetil Andersen for suggestions, feedback, testing
and coffee. :)

=head1 NO WARRANTIES

This  program  is  distributed  in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS  FOR  A  PARTICULAR  PURPOSE.
See the GNU General Public License for more details.

=head1 AUTHOR

Christian Stigen Larsen <csl@sublevel3.org>

=head1 GUBBY HOMEPAGE

http://gubby.sourceforge.net

=head1 DATE

December 15th, 2004

=cut