rawdog: RSS Aggregator Without Delusions Of Grandeur
Adam Sampson <ats@offog.org>

rawdog is an extensible feed aggregator for Unix-like systems, based on
the Python feedparser module (originally developed by Mark Pilgrim).

(Important: If you're upgrading from rawdog 1.x to rawdog 2.x, please
read the NEWS file to find out how to convert your rawdog state file.)

rawdog requires Python 2.6 or later. rawdog itself doesn't need any
additional modules to be installed, but it uses distutils for
installation, so if you're on a Debian system you'll need to install the
"python-dev" package first.

To install rawdog on your system, use distutils -- "python setup.py
install".  This will install the library modules that rawdog needs, and
will install the "rawdog" command that you can use to run it. (If you
want to install to a non-standard prefix, read the help provided by
"python setup.py install --help".)

rawdog needs a config file to function. Make the directory ".rawdog" in
your $HOME directory, copy the provided file "config" into that
directory, and edit it to suit your preferences. Comments in that file
describe what each of the options does.

You should copy the provided file "style.css" into the same directory
that you've told rawdog to write its HTML output to. rawdog should be
usable from a browser that doesn't support CSS, but it won't be very
pretty.

When you invoke rawdog from the command line, you give it a series of
actions to perform -- for instance, "rawdog --update --write" tells it
to do the "--update" action (downloading articles from feeds), then the
"--write" action (writing the latest articles it knows about to the HTML
file).

For details of all rawdog's actions and command-line options, see the
rawdog(1) man page -- "man rawdog" after installation.

You will want to run "rawdog -uw" periodically to fetch data and write
the output file. The easiest way to do this is to add a crontab entry
that looks something like this:

0,10,20,30,40,50 * * * *        /path/to/rawdog -uw

(If you don't know how to use cron, then "man crontab" is probably a good
start.) This will run rawdog every ten minutes.

If you want rawdog to fetch URLs through a proxy server, then set your
"http_proxy" environment variable appropriately; depending on your
version of cron, putting something like:

http_proxy=http://myproxy.mycompany.com:3128/

at the top of your crontab should be appropriate. (The http_proxy
variable will work for many other programs too.)

In the event that rawdog gets horribly confused (for instance, if your
system clock has a huge jump and it thinks it won't need to fetch
anything for the next thirty years), you can forcibly clear its state by
removing the ~/.rawdog/state file (and the ~/.rawdog/feeds/*.state
files, if you've got the "splitstate" option turned on).

If you don't like the appearance of rawdog, then customise the style.css
file.  If you come up with one that looks much better than the existing
one, please send it to me!

This should, hopefully, be all you need to know. If rawdog breaks in
interesting ways, please tell me at the email address at the top of this
file.