agg.1

   1 .TH AGG 1 2011-04-04 agg "the news aggregator"
   2
   3 .SH NAME
   4 .B agg
   5 \- the news aggregator
   6
   7 .SH SYNOPSIS
   8 cat feed.rss |
   9 .B agg
  10
  11 .SH DESCRIPTION
  12 .B agg
  13 reads a news feed (currently RSS only) from stdin and
  14 creates or updates its filesystem representation.
  15
  16 .SH FILE SYSTEM
  17 .B agg
  18 creates or updates the following directory structure in the
  19 current working directory:
  20
  21 .nf
  22         $FEED_NAME
  23         |-- $ITEM_1
  24         |-- $ITEM_2
  25         |-- ...
  26         `-- $ITEM_N
  27
  28 .SH USAGE
  29 .B agg
  30 uses the mtime of files and directories to represent dates
  31 of publication.
  32
  33 If the feed directory does not exist,
  34 .B agg
  35 will create it and store all items in the feed there.
  36 The mtimes of the files will be set to the corresponding
  37 date of publication, the mtime of the feed directory will
  38 be set to the date of publication of the most recent item.
  39
  40 If the feed directory already exists (e.g. on subsequent
  41 runs),
  42 .B agg
  43 checks the mtime of the feed directory and only fetches
  44 items with a newer date of publication, again setting the
  45 mtimes for the items fetched in this run. The mtime of the
  46 feed directory will be set to the date of publication of
  47 the most recent item that was fetched in this run.
  48
  49 If an item does not have a publication date, it is set to
  50 the UNIX timestamp 0.
  51
  52 By manually changing the mtime of the feed directory, you
  53 can make agg either skip unfetched items or refetch old
  54 ones.
  55
  56 To avoid unintentionally changing the mtime and thus
  57 skipping items, you can use a tiny wrapper called
  58 .B nomtime.
  59
  60 .SH BUGS
  61
  62 .IP * 2
  63 Supports only RSS.
  64 .IP * 2
  65 Uses fixed size buffers to simplify code. May lead
  66 cut-off news texts or links. The chances for this to
  67 happen are low and without much consequences.
  68 .IP * 2
  69 Assumes items are ordered descending by publication date
  70 (newest items on top). Processing is stopped as soon as an
  71 old item is encountered.
  72 .IP * 2
  73 Assumes items only change if their publication date
  74 changes. Again, for simplicity.
  75 .IP * 2
  76 Creation of a "sub-feed" directory if the channel contained
  77 an element that had a title tag but is not an item.
  78 .IP * 2
  79 Supports only dates that have their time zone formatted as
  80 +xxxx, not as their abbreviation.
  81 .IP * 2
  82 Item titles may conflict, especially if they were too long
  83 and have been cutted.
  84 .IP * 2
  85 Items will always be (over-) written in the order they are
  86 placed in the feed.
  87 .IP * 2
  88 HTML output is formatted badly.
  89 .IP * 2
  90 Standard mtime for items without pubDate should be now().
  91 .IP * 2
  92 Only tested on GNU/Linux.
  93
  94 .SH REPOSITORY
  95
  96 .nf
  97 git://repo.or.cz/agg.git
  98 http://www.repo.or.cz/w/agg.git
  99 .fi
 100
 101 .SH HOMEPAGE
 102
 103 http://programmers.at/work/on/agg
 104
 105 .SH LICENSE
 106
 107 Copyright (C) 2011 Andreas Waidler <arandes@programmers.at>
 108
 109 Permission to use, copy, modify, and/or distribute this
 110 software for any purpose with or without fee is hereby
 111 granted, provided that the above copyright notice and this
 112 permission notice appear in all copies.
 113
 114 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
 115 ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
 116 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
 117 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 118 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 119 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 120 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 121 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
 122 USE OR PERFORMANCE OF THIS SOFTWARE.