README

   1 rawdog: RSS Aggregator Without Delusions Of Grandeur
   2 Adam Sampson <azz@us-lot.org>
   3
   4 rawdog is an RSS (and other) feed aggregator, based on Mark Pilgrim's flexible
   5 feed parser. It's just an aggregator; it's not a weblog authoring tool, nor is
   6 it an NNTP gateway, outliner, mailserver or anything else.  rawdog probably
   7 only runs on Unix-like systems.
   8
   9 rawdog requires Python 2.2 or later. It doesn't need any additional
  10 modules to be installed.
  11
  12 rawdog reads articles from a number of feeds and writes out a single
  13 HTML file, based on a template either provided by the user or generated
  14 by rawdog, containing the latest articles it's seen. It uses the ETags
  15 and Last-Modified headers to avoid fetching a file that hasn't changed,
  16 and supports gzip compression to reduce bandwidth when it has. It is
  17 configured from a simple text file; the only state kept between
  18 invocations that can't be reconstructed from the feeds is the ordering
  19 of articles.
  20
  21 To install rawdog on your system, use distutils -- "python setup.py install".
  22 This will install the library modules that rawdog needs, and will install the
  23 "rawdog" binary that you can use to run it. (If you want to install to a
  24 non-standard prefix, read the help provided by "python setup.py install
  25 --help".)
  26
  27 rawdog needs a config file to function. Make the directory ".rawdog" in your
  28 $HOME directory, copy the provided file "config" into that directory, and edit
  29 it to suit your preferences. (Comments in that file describe what each of the
  30 options does.) You should copy the provided file "style.css" into the same
  31 directory that you've told rawdog to write its HTML output to. (rawdog should
  32 be 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 actions
  36 to perform -- for instance, "rawdog --update --write" tells it to do the
  37 "--update" action, then the "--write" action. The actions supported are
  38 as follows:
  39
  40 "--update" (or "-u"): Fetch data from the feeds and store it. This could
  41 take some time if you've got lots of feeds.
  42
  43 "--write" (or "-w"): Write out the HTML output file.
  44
  45 "--list" (or "-l"): List brief information about each of the feeds that
  46 was known about when "--update" was last done.
  47
  48 "--update-feed SOMEURL" (or "-f SOMEURL"), where SOMEURL is the URL of a
  49 known feed: Update that feed immediately, even if its period hasn't
  50 elapsed since it was last updated. This is useful if you're trying to
  51 debug your own feed.
  52
  53 "--config FILE" (or "-c FILE"), where FILE is an absolute path or a path
  54 relative to your .rawdog directory: Read FILE as an additional config
  55 file; any options provided in FILE will override those set in the
  56 default config (with the exception of "feed", which is cumulative).
  57 This is useful if you want rawdog to write two different output files
  58 with different sets of options ("rawdog -u -w -c config2 -w" will first
  59 update and write with the default config, then read config2, then write
  60 again).
  61
  62 "--show-template" (or "-t"): Print the template currently in use to
  63 stdout. This is useful as a starting point if you want to modify your
  64 own template: do "rawdog -t >~/.rawdog/mytemplate" with "template
  65 default" in your config file, and you'll get a copy of the default
  66 template to edit.
  67
  68 There are also the following options which may only be supplied once
  69 (they're read before any of the actions are performed):
  70
  71 "--help": Provide a brief summary of all the options rawdog supports,
  72 and exit.
  73
  74 "--dir DIR" (or "-d DIR"), where DIR is a directory: Use DIR instead of
  75 the $HOME/.rawdog directory. This is useful if you want to have two or
  76 more completely different rawdog setups with different sets of feeds;
  77 just create a directory for each.
  78
  79 You will want to run "rawdog -uw" periodically to fetch data and write
  80 the output file. The easiest way to do this is to add a crontab entry
  81 that looks something like this:
  82
  83 0,10,20,30,40,50 * * * *        /path/to/rawdog -uw
  84
  85 (If you don't know how to use cron, then "man crontab" is probably a good
  86 start.) This will run rawdog every ten minutes.
  87
  88 If you want rawdog to fetch URLs through a proxy server, then set your
  89 "http_proxy" environment variable appropriately; depending on your version of
  90 cron, putting something like:
  91
  92 http_proxy=http://myproxy.mycompany.com:3128/
  93
  94 at the top of your crontab should be appropriate. (The http_proxy variable will
  95 work for many other programs too.)
  96
  97 In the event that rawdog gets horribly confused (for instance, if your system
  98 clock has a huge jump and it thinks it won't need to fetch anything for the
  99 next thirty years), you can forcibly clear its state by removing the
 100 ~/.rawdog/state file.
 101
 102 If you don't like the appearance of rawdog, then customise the style.css file.
 103 If you come up with one that looks much better than the existing one, please
 104 send it to me!
 105
 106 This should, hopefully, be all you need to know. If rawdog breaks in
 107 interesting ways, please tell me at the email address at the top of this file.
 108