README

   1 rawdog: RSS Aggregator Without Delusions Of Grandeur
   2 Adam Sampson <ats@offog.org>
   3
   4 rawdog is a feed aggregator. It supports most common feed formats,
   5 including all versions of RSS and Atom using feedparser. It runs from
   6 cron, collects articles from a number of feeds, and generates a static
   7 HTML page listing the newest articles in date order. It supports
   8 per-feed customizable update times, and uses ETags, Last-Modified, gzip
   9 compression, and RFC3229+feed to minimize network bandwidth usage. Its
  10 behaviour is highly customisable using plugins written in Python.
  11
  12 rawdog has the following dependencies:
  13
  14 - Python 2.6 or later (but not Python 3)
  15 - feedparser 5.1.2 or later
  16 - PyTidyLib 0.2.1 or later (optional but strongly recommended)
  17
  18 To install rawdog on your system, use distutils -- "python setup.py
  19 install".  This will install the "rawdog" command and the "rawdoglib"
  20 Python module that it uses internally.  (If you want to install to a
  21 non-standard prefix, read the help provided by "python setup.py install
  22 --help".)
  23
  24 rawdog needs a config file to function. Make the directory ".rawdog" in
  25 your $HOME directory, copy the provided file "config" into that
  26 directory, and edit it to suit your preferences. Comments in that file
  27 describe what each of the options does.
  28
  29 You should copy the provided file "style.css" into the same directory
  30 that you've told rawdog to write its HTML output to. rawdog should be
  31 usable from a browser that doesn't support CSS, but it won't be very
  32 pretty.
  33
  34 When you invoke rawdog from the command line, you give it a series of
  35 actions to perform -- for instance, "rawdog --update --write" tells it
  36 to do the "--update" action (downloading articles from feeds), then the
  37 "--write" action (writing the latest articles it knows about to the HTML
  38 file).
  39
  40 For details of all rawdog's actions and command-line options, see the
  41 rawdog(1) man page -- "man rawdog" after installation.
  42
  43 You will want to run "rawdog -uw" periodically to fetch data and write
  44 the output file. The easiest way to do this is to add a crontab entry
  45 that looks something like this:
  46
  47 0,10,20,30,40,50 * * * *        /path/to/rawdog -uw
  48
  49 (If you don't know how to use cron, then "man crontab" is probably a good
  50 start.) This will run rawdog every ten minutes.
  51
  52 If you want rawdog to fetch URLs through a proxy server, then set your
  53 "http_proxy" environment variable appropriately; depending on your
  54 version of cron, putting something like:
  55
  56 http_proxy=http://myproxy.mycompany.com:3128/
  57
  58 at the top of your crontab should be appropriate. (The http_proxy
  59 variable will work for many other programs too.)
  60
  61 In the event that rawdog gets horribly confused (for instance, if your
  62 system clock has a huge jump and it thinks it won't need to fetch
  63 anything for the next thirty years), you can forcibly clear its state by
  64 removing the ~/.rawdog/state file (and the ~/.rawdog/feeds/*.state
  65 files, if you've got the "splitstate" option turned on).
  66
  67 If you don't like the appearance of rawdog, then customise the style.css
  68 file.  If you come up with one that looks much better than the existing
  69 one, please send it to me!
  70
  71 This should, hopefully, be all you need to know. If rawdog breaks in
  72 interesting ways, please tell me at the email address at the top of this
  73 file.
  74