Readme for AmphetaDesk "Mailer" Modification
2002-09-24

For installation instructions, jump to the 'Instructions' below. 
Otherwise, keep reading to get some of the background for this 
modification.

AmphetaDesk is a great application for keeping up with various 
news and RSS feeds. I've built up a list of about 50 channels 
that I follow and even created a hack to store my master channel 
list on an FTP server.

I created the AmphetaMailer mod to solve a couple of problems:
- Send the updates to me automatically (I'm already in e-mail all 
  day so this made sense)
- Only send new items once so I don't need to manually filter 
  through everything I've already seen

The changes to AmphetaDesk.pm were fairly extensive. Basically, I 
ripped out everything related to serving up web pages and the UI 
loop. Instead, it simply loads the latest channels, then formats 
them into an HTML e-mail message (copied from the default 
template). When I first implemented this, I sent one e-mail 
message per channel. This turned into too many messages, so now 
it combines them all into a single (but larger) message.

To prevent channel items from being sent more than once, it 
computes an MD5 digest for each item (based on title + link + 
description). This array of digest values is saved to a file (one 
per channel) for future use. While scanning through each item, 
the old digest values are checked. If the item is new or if any 
of the three fields change (even slightly), its digest won't be 
found and it will be added to the e-mail.

There is probably a better way to remove the duplicates, but in 
practice this works quite well.

Changes were made from the AmphetaDesk v0.93 Windows 
distribution. I hope that the changes are platform-independent, 
but I've only been able to test this code under Windows.

This mod requires the following modules which may or may not be 
present in a standard Perl distribution:
  Mail::Sendmail
  HTML::Entities
  Digest::MD5

Instructions:

1. Download AmphetaDesk v0.93 (http://www.disobey.com/amphetadesk/)
2. Expand AmphetaDesk into desired location
3. Replace AmphetaDesk.pm and Utilities.pm with the ones provided 
   here (saving copies of the original ones, of course!)
4. Edit mySettings.xml, changing the 'mail' options near the end;
   a sample one is included in the ZIP
5. Run AmphetaDesk.pl manually or set it up as a cron job for regular 
   updates

Search for 'AmphetaMailer' comment marking each change in the 
source code.

If anyone else finds this useful, please let me know. Future 
improvements should probably include:
- Option for plain text or HTML e-mail message
- Clean up and reduce size of HTML e-mail messages
- Consider how to handle malformed feeds, perhaps with a more
  liberal parsing mode
- Either move code into separate modules or just create a new
  top-level Perl script to drive everything (thus minimize the
  hacking and leave a working copy of AmphetaDesk around)
- Error handling (add some)

Brian Cantoni <brian at cantoni.org>
www.cantoni.org/projects/AmphetaDesk.html