README

   1 # agg, the news aggregator
   2
   3 ## about
   4
   5 agg is a news aggregator (currently RSS 2.0 only) for
   6 POSIX-compliant systems (currently tested on GNU/Linux
   7 only).
   8
   9 It follows the UNIX philosophy and simply reads a news feed
  10 from stdin and creates or updates a filesystem
  11 representation of that feed.
  12
  13 No command line parameters, no user interface, not even
  14 networking.
  15
  16
  17 ## news
  18
  19 * 2011-06-26 agg-0.3.0 released
  20 * 2011-05-11 agg-0.2.1 released
  21 * 2011-05-10 agg-0.2.0 released
  22 * 2011-04-16 agg-0.1.1 released
  23 * 2011-04-08 agg-0.1.0 released
  24 * 2011-04-01 development started
  25
  26
  27 ## changelog
  28
  29 ### 2011-06-26 agg-0.3.0
  30
  31 * When items have conflicting names, the one with the most
  32   recent publication date will now be stored.
  33 * Items are now allowed to be ordered arbitrarily.
  34 * Properties of items are now allowed to be ordered
  35   arbitrarily.
  36 * Fixed minor bugs in handling broken feeds.
  37
  38 ### 2011-05-11 agg-0.2.1
  39
  40 * Adjusted documentation.
  41 * Fixed install target of makefile.
  42
  43 ### 2011-05-10 agg-0.2.0
  44
  45 * Tests and refactoring.
  46 * New output format, no HTML output anymore.
  47 * Now requiring that title or description of items come
  48   first, and title has to come before description.
  49 * Made nomtime work from outside of feed directory
  50
  51 ### 2011-04-16 agg-0.1.1
  52
  53 * Included proper README.
  54 * Included nomtime in make targets.
  55
  56 ### 2011-04-08 agg-0.1.0
  57
  58 Initial release.
  59
  60
  61 ## dependencies
  62
  63 * libexpat
  64
  65
  66 ## install
  67
  68         make test install
  69
  70 For configuration see Make.config.
  71
  72 Please, run the test suites, they've been written for *you*
  73 and take few seconds on a 500 MHz CPU anyways.
  74
  75
  76 ## faq
  77
  78 ### Writing file names that are are specified in the feed? What about security?
  79
  80 agg removes all slashes from file and directory names
  81 before they are written, so everything ends up where it
  82 belongs. You should run it in a dedicated directory,
  83 though.
  84
  85 ### But a malicious feed could use up all space/inodes.
  86
  87 Depends on your operating system (configuration). It's not
  88 the job of a news aggregator to enforce quotas.
  89
  90 ### Why no download mechanism?
  91
  92 Because it's a news aggregator, not a
  93 download-and-news-aggregation-program.
  94
  95 ### But do I have to download the feed by hand?
  96
  97         wget $URL -O - | agg
  98
  99 ### But it only works on a single feed!
 100
 101         for feed in `cat feeds`; do
 102                 (wget $feed -qO - | agg) &
 103         done
 104
 105 You get the point.
 106
 107 ### Why no user interface?
 108
 109 Because it's a news aggregator, not a
 110 download-and-news-aggregation-and-news-reader-program. The
 111 file system hierarchy is pretty much usable using various
 112 unixoid tools.
 113
 114 Sky is the limit. Feel free to write your own frontend; you
 115 should be able to find mine on my blog.
 116
 117 ### How to fetch only new items from feeds that don't use publication dates?
 118
 119 Not supported by agg itsself, since it would require a
 120 second level storage that contains (hashes of) everything
 121 the agg directory contained -- including items you
 122 explicitly deleted. You can easily build such functionality
 123 on top using a few lines of shell code.
 124
 125 Again, its a news aggregator not a caching program.
 126
 127
 128 ## bugs to be fixed
 129
 130 * Supports only RSS.
 131 * Currently only tested on GNU/Linux.
 132 * Uses fixed size buffers to simplify code. May lead
 133   cut-off news texts. The chances for this to happen are
 134   rather low and without much consequences (you can always
 135   follow the link). If you encounter a link that is larger
 136   than 8KiB, let me know.
 137 * Assumes items only change if their publication date
 138   changes. Again, for simplicity.
 139 * Creation of a "sub-feed" directory if the channel
 140   contained an element that had a title tag but is not an
 141   item.
 142 * Supports only dates that have their time zone formatted
 143   as +xxxx, not as their abbreviation.
 144 * Item titles may conflict, especially if they were too
 145   long and have been cutted. In this case, the item with
 146   the most recent publication date will be stored on the
 147   disk.
 148 * Standard mtime for items without pubDate should be now.
 149 * Sometimes, mtime of feed directory is set to current
 150   time. This seems to happen only when a "new" item is not
 151   already stored locally. If it is, the mtime is not
 152   modfified.
 153
 154
 155 ## authors
 156
 157 * Andreas Waidler <arandes@programmers.at>
 158
 159 ## repo
 160
 161 * git://repo.or.cz/agg.git
 162 * <http://www.repo.or.cz/w/agg.git>
 163
 164 ## homepage
 165
 166 * <http://programmers.at/work/on/agg>
 167
 168 ## download
 169
 170 * <http://programmers.at/work/on/agg/agg-0.3.0.tar.gz>
 171 * <http://programmers.at/work/on/agg/agg-0.2.1.tar.gz>
 172 * <http://programmers.at/work/on/agg/agg-0.2.0.tar.gz>
 173 * <http://programmers.at/work/on/agg/agg-0.1.1.tar.gz>
 174 * <http://programmers.at/work/on/agg/agg-0.1.0.tar.gz>
 175
 176
 177 ## license
 178
 179 Copyright (C) 2011 Andreas Waidler <arandes@programmers.at>
 180
 181 Permission to use, copy, modify, and/or distribute this
 182 software for any purpose with or without fee is hereby
 183 granted, provided that the above copyright notice and this
 184 permission notice appear in all copies.
 185
 186 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
 187 ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
 188 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
 189 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 190 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 191 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 192 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 193 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
 194 USE OR PERFORMANCE OF THIS SOFTWARE.