Kicked TODO item.
[agg.git] / README
blobff1d2fc35a9f5428f9279516ed00664ace388f4d
1 # agg, the news aggregator
3 ## about
5 agg is a news aggregator (currently RSS 2.0 only) for
6 POSIX-compliant systems (currently tested on GNU/Linux
7 only).
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.
13 No command line parameters, no user interface, not even
14 networking.
17 ## news
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
27 ## changelog
29 ### 2011-06-26 agg-0.3.0
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.
38 ### 2011-05-11 agg-0.2.1
40 * Adjusted documentation.
41 * Fixed install target of makefile.
43 ### 2011-05-10 agg-0.2.0
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
51 ### 2011-04-16 agg-0.1.1
53 * Included proper README.
54 * Included nomtime in make targets.
56 ### 2011-04-08 agg-0.1.0
58 Initial release.
61 ## dependencies
63 * libexpat
66 ## install
68         make test install
70 For configuration see Make.config.
72 Please, run the test suites, they've been written for *you*
73 and take few seconds on a 500 MHz CPU anyways.
76 ## faq
78 ### Writing file names that are are specified in the feed? What about security?
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.
85 ### But a malicious feed could use up all space/inodes.
87 Depends on your operating system (configuration). It's not
88 the job of a news aggregator to enforce quotas.
90 ### Why no download mechanism?
92 Because it's a news aggregator, not a
93 download-and-news-aggregation-program.
95 ### But do I have to download the feed by hand?
97         wget $URL -O - | agg
99 ### But it only works on a single feed!
101         for feed in `cat feeds`; do
102                 (wget $feed -qO - | agg) &
103         done
105 You get the point.
107 ### Why no user interface?
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.
114 Sky is the limit. Feel free to write your own frontend; you
115 should be able to find mine on my blog.
117 ### How to fetch only new items from feeds that don't use publication dates?
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.
125 Again, its a news aggregator not a caching program.
128 ## bugs to be fixed
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.
155 ## authors
157 * Andreas Waidler <arandes@programmers.at>
159 ## repo
161 * git://repo.or.cz/agg.git
162 * <http://www.repo.or.cz/w/agg.git>
164 ## homepage
166 * <http://programmers.at/work/on/agg>
168 ## download
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>
177 ## license
179 Copyright (C) 2011 Andreas Waidler <arandes@programmers.at>
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.
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.