agg.1

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