rssbiff: check for new RSS feeds

rssbiff is a fork of imapbiff 2.0

   This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   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.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

Copyright (C) 2000 Michael Arndt (imapbiff)
Copyright (C) 2007,2008,2010 Enrique D. Bosch 'presi'


Current Version: 1.0

What is rssbiff?
-----------------
rssbiff is a small perl/tk program that notifies you of new items in a
RSS/Atom feed by HTTP. It uses images similar to those of the classic xbiff 
program. It works similar to xbiff, except it is only used to check for 
RSS/Atom feeds. When rssbiff is executed it set all items as read (unless
you set -a/allnew option), from that moment if a new item arrive it will beep 
and raise the flag. Whenever it is querying the HTTP server, a "?" is displayed
to indicate that it is checking for messages.

rssbiff is a fork of imapbiff 2.0 (it's based on its sources).

Requirements
------------
- perl.
- The Tk perl module (DOES NOT come with most perl installations).
- The Getopt module (comes with most perl installations).
- The IO perl module (comes with most perl installations).
- The XML::Feed module for retrieving and parsing feeds.
- The DateTime::Infinite module

Installation
------------
Check the first line of rssbiff to see if it is pointing at the correct
location of your perl interpreter. If not, change this line so that it
contains a correct path to perl.

Usage
-----
You can either pass command line arguments to rssbiff, or use a .rssbiffrc
file in your home directory. The format of the .rssbiffrc file is:

url <HTTP server URL>
sleep <number of seconds to sleep between checks>
nobeep
nodecor (overrides window manager frame/decoration)
tip (add a tip [popup] miniwindow shows number of messages when mouse is over)
pos <X>x<Y> (initial X,Y position)
png_checking   <file> (PNG icon while checking, default: check.png)
png_post       <file> (PNG icon when there is new posts, default: up.png)
png_nopost     <file> (PNG icon when there is no new posts, default: down.png)
allnew (set all existing posts as unread)

Example .rssbiffrc:

url http://my.feed.example.org/rss
sleep 600

This would retrieve posts at http://my.feed.host.org/rss every 600 seconds.

You can also specify command line options, which override the .rssbiffrc
options: 

-d
  debug mode: in this mode, rssbiff will not run as a daemon, but rather print
  out debugging messages to the terminal you start it from.
-q 
  quiet mode: do not beep when you have new messages. Identical to having a
  line with "nobeep" on it in the .rssbiffrc file.
-u <url>
  use <url> as the HTTP server for retrieving the feed. No default, this must be 
  specified either in the .rssbiffrc or on the command line.
-s <sleep>
  sleep: sleep for <sleep> seconds between checks.  Defaults to 120 seconds.
-c <file>
  Use alternative config file
-n
  Overrides window manager frame/decoration. Equivalent to "nodecor" config 
  option.
-t
  Add a popup small window when mouse is over that shows number of unread 
  mails. Equivalent to "tip" config option.
-a
  Set all exiting posts as unread so the flag will be up as soon as rssbiff
  is executed. Equivalent to "allnew" config option.

While rssbiff is running, you can use the mouse buttons for the folllowing:

Button 1 (left): click on the pixmap with button 1 to tell rssbiff you have
read all the posts (with your favourite RSS reader), this will lower the
flag. If any new post arrive, the flag will go up again.

Button 2 (middle): click on the pixmap with button 2 to exit from rssbiff.

Button 3 (right): click on the pixmap with button 3 to initiate an immediate
check of your feed.

Media files
-----------
The images for the mailbox are colored versions of xbiff bitmaps under X11 
license.

To-do
-----
- Get prettier pixmaps!
- Save rssbiff state between executions