NAME

rss2mail2 - an RSS aggregator that delivers feeds as plain text email

SYNOPSIS

    # add a feed
    rss2mail2 -add test_feed -uri http://example.com/index.rss
    # add a feed getting the name from the feed file
    rss2mail2 -add http://example.com/index.rss
    # edit feed details
    rss2mail2 -edit test_feed -uri http://example.com/index.atom
    # list all feeds
    rss2mail2 -list
        test_feed: http://example.com/index.rdf
    # fetch feeds
    rss2mail2
    # delete a feed
    rss2mail2 -del test_feed
    # fetch a feed once
    rss2mail2 -fetch http://example.com/index/rss
    # get a summary of the common options
    rss2mail2 -help
    # get the version of rss2mail2
    rss2mail2 -Version

Both the add and edit options also support the --auto option which will attempt to find an RSS feed at the supplied URI. It also copes with feeds in the Atom format.

DESCRIPTION

rss2mail2 is an RSS aggregator for those that like to get all their information delivered to their inbox. It runs through your list of feeds and sends you one mail per updated feed containing all the new and updated items in that feed. Optionally it will provide you with a universal style diff of the updated feeds.

Any HTML will be converted to plain text and to keep things simple it will, by default, strip out pretty much anything that isn't plain text. If you have Perl 5.8 then any Unicode content should be fine. If you have an earlier version of Perl rss2mail2 will try to do the right thing but if it doesn't know what that is it will replace the character with a space.

rss2mail2 tries to do the right thing with missing feeds or changes in feed location. If you try to subscribe to a URL that isn't there then it won't subscribe. If the URL for a feed stops working then it will keep trying for a user configurable number of attempts (this defaults to 30) and then unsubscribe. If the feed moves but provides a permanent redirect then it will update the URL accordingly. If it does unsubscribe from a feed then a notice to that effect will appear as an item in that feed. It also spits out errors on STDERR.

OPTIONS

rss2mail2 can be called with the following options:

-add feed_name

Add a feed with feed_name as the name of the feed.

If feed_name begins with http then rss2mail will assume you've given it the address of a feed file and attempt to fetch it. It will then extract the name from that file, assuming it's a valid feed file.

Alternatively you can supply your own name and supply the location of the feed using the uri option.

-edit feed_name

Changes the location of feed_name. You need to pass the new feed location with the uri option.

-uri feed_location

Used with the add and edit options to supply the location of the feed.

-auto

If called with either the add or edit options then it will try and guess the feed location from the URI passed to the uri option.

This works with the auto naming behaviour of add.

-delete feed_name

Deletes feed_name and all entries from the database.

-list

Lists all the feeds and their locations.

-opml

Outputs an OPML file with details of all the feeds. It only provides the name of the feed and the URL of the feed file but should be enough if you want to move your subscriptions to another feed reader that supports OPML import. This does require the optional XML::OPML module.

-fetch feed_location

Performs a one time fetch of the feed at feed_location.

-help

Prints out a usage message summarising commonly used options.

-items

Send one email per item instead of an email per feed.

-cleanup

Deletes old entries. By default any entry older than 30 days is deleted. See the CONFIGURATION for how to alter this.

-print_mail

Instead of sending the mails just print them out to STDOUT. Only really useful for debugging.

-Version

Display the version number of rss2mail2 and exit.

-Debug level

If set to greater than 0 then rss2mail2 will spew out a whole load of debugging information. You'll probably never want to use this. If set to 3 or above you'll get an awful lot of information.

All of the above options have a short form consisting of only the first letter of the option so add can also be called as -a and edit as -e.

CONFIGURATION

rss2mail2 looks for a configuration file called .rss2mail2rc in the users home directory or, if that doesn't exist, in /etc/rss2mail2rc. If neither of these exists it spits out an error message and quits.

The configuration file should be readable by AppConfig but in case you can't be bothered to read the docs for that an example config file looks like this:

    base_dir = ${HOME}/.rss2mail2
    mail_to = ${USER}
    mail_to = struan
    mail_to = bob
    mail_from = rss2mail2@example.com
    oldest = 30
    dsn  = dbi:SQLite:dbname=${HOME}/.rss2mail2/rss.db

This example will mail struan and bob and use an SQLite database located in ~/.rss2mail2/rss2mail.db to store feed data. Any files it needs to save will also be stored in ~/.rss2mail2 and the mails will use rss@example.com as a From address. The oldest option is used when you use the -cleanup option and means that feed entries older than 30 days will be purged from the database.

Probably all you really need to change is mail_to and mail_from. As above if you want to sent the mails to multiple people you should have multiple mail_to options in the file with one email address each.

If you prefer to receive a mail for each item in the feed then you can either add a line with mail_per_feed on it to the config file or run rss2mail2 with the -i option.

If you don't like the diffs then you can turn them off by adding a line with no_diffs.

The only other option you can set is max_not_found which configures how many times in a row fetching a feed fails before it is deleted. The default is 30.

Sample procmail recipe:

       :0:
       * ^From: rss2mail2
       * ^Subject: [a-z_]+:
       * ^Subject: \/[a-z_]+
       rss/$MATCH

CAVEATS

It should be noted that the diffs may not be ideal as the limitations of Text::Diff hold. Most notably it's not good with changes in whitespace.

Feed auto discovery currently picks the first available feed.

REQUIRES

What would the world be without a raft of dependencies?

XML::Feed

Text::Autoformat

LWP

AppConfig

MIME::Lite

MIME::Tools

List::Util

HTML::FormatText::WithLinks

Text::Diff

Exception::Class

DBI, DBD::SQLite

Class::DBI, Class::DBI::SQLite, Class::DBI::BaseDSN

Plus of course all the dependencies that they require.

Just run it and install modules till it stops complaining.

rss2mail2 will use the following modules if they are available:

HTML::Lint

This is used to improve the HTML to text processing

XML::OPML

This is used to spit out the feed list in OPML format.

AUTHOR

Struan Donald <code@exo.org.uk>, http://exo.org.uk/

COPYRIGHT

Copyright 2002-2006 Struan Donald.

LICENSE

Same terms as Perl itself

SEE ALSO

procmail(1)