plutopluto

commit

77081d2119ea5524881d708cd813373613a10a88

parent

aad0ca8bc63fb70265ba3d00e60aa8a0cc97dfac

Author

Tobias Bengfort <tobias.bengfort@gmx.net>

Date

2014-09-25 19:54

add README.rst

Diffstat

1 files changed, 107 insertions, 0 deletions

diff --git a/README.rst b/README.rst

@@ -0,0 +1,107 @@
   -1     1 plutopluto - simple feed aggregator
   -1     2 
   -1     3 Overview
   -1     4 --------
   -1     5 
   -1     6 Display posts from multiple feeds::
   -1     7 
   -1     8     plutopluto http://xkcd.com/atom.xml http://what-if.xkcd.com/feed.atom
   -1     9 
   -1    10 Display posts from a feed with multiple pages::
   -1    11 
   -1    12     plutopluto http://staff.tumblr.com/page/{page}/rss
   -1    13 
   -1    14 Load config (with urls) from separate file::
   -1    15 
   -1    16     plutopluto -c config.cfg
   -1    17 
   -1    18 History
   -1    19 -------
   -1    20 
   -1    21 When I stopped using facebook some years ago the only thing I missed was
   -1    22 getting a stream of interesting things. I really like just scrolling along and
   -1    23 look at some pictures, read some discussions and watch some videos.
   -1    24 
   -1    25 So I started to look for alternatives. Pretty fast I realized that I did not
   -1    26 need a social network to a stream. The existing infrastructure of blogs with
   -1    27 RSS or atom feeds was more than enough for anything I wanted.
   -1    28 
   -1    29 The only thing missing was a nice way to display these feeds in a stream. So
   -1    30 this is what I wanted to create: A stream-like feed reader.
   -1    31 
   -1    32 Later I realized there is a second reason why I would want to use plutopluto:
   -1    33 Many blogs suck. Either they look plain ugly or they are unusable slow -- which
   -1    34 happens especially with image-centered blogs.  So I just fire up plutopluto
   -1    35 with the blog's feed and have a nice and clean interface for scrolling through
   -1    36 the content.
   -1    37 
   -1    38 Architecture
   -1    39 ------------
   -1    40 
   -1    41 I originally implemented plutopluto in PHP. This is a rewrite in JavaScript.
   -1    42 
   -1    43 Unfortunately, the cross origin policy prevents JavaScript from accessing
   -1    44 feeds directly. So there is a minimal python server which gets the feeds and
   -1    45 also converts them to JSON. I could have used a 3rd party service like the
   -1    46 `google feed API`_ for this, but I did not want to leak any data to google and
   -1    47 also I already had the required python code from another project.
   -1    48 
   -1    49 The JavaScript code depends on jQuery. However, I wrote a minimal
   -1    50 reimplementation inspired by `jqlite`_ that is used instead. Why? Because it
   -1    51 was fun.
   -1    52 
   -1    53 Design
   -1    54 ------
   -1    55 
   -1    56 The default design is minimalistic and pratical. It is simply a list of post
   -1    57 sorted by time. When you scroll to the bottom, more posts are loaded, so you
   -1    58 can just keep scrolling until no posts are left.  Each post has a header
   -1    59 section with the publication time and the name of the source.  When you click
   -1    60 on the source you go to the original post.
   -1    61 
   -1    62 This design was inspired by `soup.io`_ and is also similar to tumblr.
   -1    63 
   -1    64 Configuration
   -1    65 -------------
   -1    66 
   -1    67 You can configure all `flask related options`_ as well as ``HOST``, ``PORT``
   -1    68 and ``URLS`` in a separate configuration file using ``plutopluto --config
   -1    69 FILE``.  See ``example.cfg`` for an example.
   -1    70 
   -1    71 Some options can be passed to plutopluto directly. See ``plutopluto --help``.
   -1    72 If defined, they take precedence over thos from the config file.
   -1    73 
   -1    74 Extend/Hack
   -1    75 -----------
   -1    76 
   -1    77 Everything about this project is meant to be simple. I am serious about this.
   -1    78 I really want the code to be as easy to understand and extend by as many people
   -1    79 as possible. If you see anything you don't understand: Please create a bug
   -1    80 report.
   -1    81 
   -1    82 FAQ
   -1    83 ---
   -1    84 
   -1    85 Why the name "plutopluto"?
   -1    86     There is some kind of a tradition of feed aggregators called this way:
   -1    87     `planetplanet <http://www.planetplanet.org/>`_,
   -1    88     `moonmoon <http://moonmoon.org/>`_
   -1    89 
   -1    90 What is the favicon?
   -1    91     It's a sad pluto. `When I was a child, pluto was still considered a
   -1    92     planet. <http://plutoisstillaplanetto.me/>`_
   -1    93 
   -1    94 The posts are not sorted correctly
   -1    95     Loading and parsing many feeds takes some time. So when the first posts are
   -1    96     displayed, many feeds have not yet finished. In fact, the first posts are
   -1    97     displayed as soon as the first feed is loaded. So the first few posts will
   -1    98     necessarily originate from the same source.
   -1    99 
   -1   100 The stream always starts with the same source
   -1   101     See previous question.
   -1   102 
   -1   103 
   -1   104 .. _`google feed API`: https://developers.google.com/feed/
   -1   105 .. _`jqlite`: https://github.com/montyjanderson/jqlite
   -1   106 .. _`soup.io`: http://www.soup.io/
   -1   107 .. _`flask related options`: http://flask.pocoo.org/docs/0.10/config/#builtin-configuration-values