README

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