plutopluto

commit

596595f84cdccb06fb5f07064c1a1e685958dd07

parent

2d01cab7b13b8a3ae693629edc3e473945ae513b

Author

Tobias Bengfort <tobias.bengfort@posteo.de>

Date

2023-12-21 10:09

convert README to markdown

Diffstat

5 files changed, 147 insertions, 163 deletions

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

@@ -1,53 +0,0 @@
    1    -1 1.2.0 (2915-12-24)
    2    -1 ------------------
    3    -1 
    4    -1 -   Fix python3 support
    5    -1 -   Add ``--version`` flag
    6    -1 
    7    -1 
    8    -1 1.1.0
    9    -1 -----
   10    -1 
   11    -1 -   Adapt to changed youtube API.
   12    -1 -   Search for config in more places, e.g. ``~/.plutopluto.cfg``.
   13    -1 
   14    -1 
   15    -1 1.0.2
   16    -1 -----
   17    -1 
   18    -1 Changes
   19    -1 ```````
   20    -1 
   21    -1 -   The full post title is now included as `title` attribute on the source
   22    -1     link.
   23    -1 -   On parse error, the server part returns a 500 status instead of an empty
   24    -1     object.  Also, less parse errors sould occur.
   25    -1 
   26    -1 Bugs
   27    -1 ````
   28    -1 
   29    -1 -   Fix visited link color.
   30    -1 -   Feeds that do not provide timestamps will be shown in the right order.
   31    -1     This is accomplished by useing current time for each item and subtracting
   32    -1     n seconds from the nth entry.
   33    -1 
   34    -1 
   35    -1 1.0.1
   36    -1 -----
   37    -1 
   38    -1 Bugs
   39    -1 ````
   40    -1 
   41    -1 -   Change to python package to fix installation.
   42    -1 
   43    -1 
   44    -1 1.0.0
   45    -1 -----
   46    -1 
   47    -1 JavaScript/python rewrite.
   48    -1 
   49    -1 
   50    -1 0.0.0
   51    -1 -----
   52    -1 
   53    -1 Initial PHP implementation.

diff --git a/CHANGES.md b/CHANGES.md

@@ -0,0 +1,39 @@
   -1     1 # 1.2.0 (2915-12-24)
   -1     2 
   -1     3 -   Fix python3 support
   -1     4 -   Add `--version` flag
   -1     5 
   -1     6 # 1.1.0
   -1     7 
   -1     8 -   Adapt to changed youtube API.
   -1     9 -   Search for config in more places, e.g. `~/.plutopluto.cfg`.
   -1    10 
   -1    11 # 1.0.2
   -1    12 
   -1    13 ## Changes
   -1    14 
   -1    15 -   The full post title is now included as [title]{.title-ref} attribute
   -1    16     on the source link.
   -1    17 -   On parse error, the server part returns a 500 status instead of an
   -1    18     empty object. Also, less parse errors sould occur.
   -1    19 
   -1    20 ## Bugs
   -1    21 
   -1    22 -   Fix visited link color.
   -1    23 -   Feeds that do not provide timestamps will be shown in the right
   -1    24     order. This is accomplished by useing current time for each item and
   -1    25     subtracting n seconds from the nth entry.
   -1    26 
   -1    27 # 1.0.1
   -1    28 
   -1    29 ## Bugs
   -1    30 
   -1    31 -   Change to python package to fix installation.
   -1    32 
   -1    33 # 1.0.0
   -1    34 
   -1    35 JavaScript/python rewrite.
   -1    36 
   -1    37 # 0.0.0
   -1    38 
   -1    39 Initial PHP implementation.

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

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

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

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

diff --git a/setup.py b/setup.py

@@ -7,7 +7,7 @@ from setuptools import setup
    7     7 DIRNAME = os.path.abspath(os.path.dirname(__file__))
    8     8 rel = lambda *parts: os.path.abspath(os.path.join(DIRNAME, *parts))
    9     9 
   10    -1 README = open(rel('README.rst')).read()
   -1    10 README = open(rel('README.md')).read()
   11    11 INIT = open(rel('plutopluto', '__init__.py')).read()
   12    12 VERSION = re.search("__version__ = '([^']+)'", INIT).group(1)
   13    13