mekk.feeds / doc / greader2org.txt

=================
greader2org
=================

Initial setup
=================

Install the module and it's prerequisities in a standard way
(easy_install mekk.feeds or python setup.py after manual download). On
Windows you may consider installing lxml and simplejson manually,
using binary modules.

Run

    greader2org

The program will create draft version of the configuration file
(`~/.feeds/feeds.ini` on Linux, similarly named file on Windows) and
prompt you to edit it. Spawn some text editor and save your Google
username and password there (also, consider setting permissions on
this file so it is readable only for you).

Then run

    greader2org init

This command will create the file `~/.feeds/feeds.txt`
with info about all your subscriptions.

Note also that greader2org run without parameters prints
minimal help.

The structure of feeds.txt file
===============================

In it's simplest form the feeds.txt file has the following structure:

    * Devel: Web

    ** SitePoint.com

       feed: http://www.sitepoint.com/recent.rdf

    ** Smashing Magazine

       feed: http://feeds.feedburner.com/SmashingMagazine

    * Apps: Emacs

    ** emacs-fu

       feed: http://emacs-fu.blogspot.com/feeds/posts/default

    ** M-x all-things-emacs

       feed: http://www.emacsblog.org/feed/

Here chapter titles denote folder names, section titles denote feed
names and section bodies contain feed URLs.

A few other marks can be added, here is more sophisticated example:

    * Chess: Forum

    ** Chess-Server.net Forum - All Forums              :private:

       feed: http://forum.chess-server.net/syndication.php?type=atom1.0

    ** ICCF Forum                              :private:disabled:

       feed: http://iccf.com/forum/external.php?type=RSS2
       comment: ICCF important notes

    * Devel: Web

    ** SitePoint.com

       feed: http://www.sitepoint.com/recent.rdf
       postrank_feed: http://feeds.postrank.com/d6e48cfa50dc7f1cb13e8df0ad93b4a6
       level: good

Tags have the following meaning:

  :disabled:  feed (to be) unsubscribed (use to temporarily
              disable feeds you may want to enable back at some
              future)

  :private:   personal feeds (at the moment it just means that the
              feed should never be passed through PostRank filter)

Content can contain the following fields:

  feed:          url (address) of the feed
  postrank_feed: url (address) of the PostRank-filtered feed
  level:         PostRank filtering level (best, great, good, all)
  comment:       any comment/remark

Note: this file is rewritten during "greader2org get". Everything
except folder titles, feed titles, and the fields described above is
lost.

Regular usage
=================

Usual session consists of the following 3 phases (and can
be repeated as often as you like)

Grabbing updates
----------------

Run

   greader2org get

to grab possible updates from Google and save them to feeds.txt.
This script:

- adds to feeds.txt all feeds which are subscribed in Google Reader
  but not present in this file (usually those are recently subscribed
  feeds)

- detects feeds which are no longer subscribed in Reader (likely
  manually unsubscribed) and labels them with :disabled: mark

Note that this command in fact rewrites the file, so only the
elements described above are preserved.

Editing
--------

Edit feeds.txt in your text editor of choice.  Emacs with org-mode is
strongly recommended, but not necessary.

The following edits may make sense:

- changing folder names,
- changing feed titles,
- moving feeds between folders (or to new folders),
- adding comment: comments where useful,
- marking selected feeds as :disabled: (to unsubscribe them),
- removing :disabled: mark (to subscribe such feeds back)
- changing level: (see section about PostRank filtering below)

Uploading
---------

Save the file and run:

    greader2org put

This commands analyses the feeds.txt file, checks it against
current Google Reader subscriptions, and performs the following
edits:

(subscriptions)

- feeds marked as :disabled: are unsubscribed in Google Reader

- feeds present in feeds.txt and not marked as :disabled:, but not
  present in Google Reader are subscribed in Reader (= any feed for
  which :disabled: was cleared is subscribed, just like any feed
  manually added to this file)

- feeds for which postrank filtering level (level) has changed are
  resubsribed using another feed url (this means a loss of read/unread
  state), see below for more information about PostRank filtering

(titles)

- feeds for which the title changed are renamed on Reader
  (without the loss of read/unread state)

(folders)

- feeds moved to another folder are re-tagged (old tag is removed, new
  tag is added,  read/unread state is preserved)

- if folder title changed, or feeds below are re-tagged

PostRank
--------

PostRank service allows one to subscribe to the filtered version of
given feed (so, for example, instead of reading whole feed, you read
only best posts from it). See their website (http://www.postrank.com)
for more details.

greader2org makes it easy to switch between normal subscription and
PostRank filtered subscription, or to change the level of filtering.
To use it:

- perform normal `greader2org get` as described above

- review the file and mark any feed you would not like to publish to
  PostRank as :private: (in particular do it for personal/secret feeds
  in case you use such feeds)

- run the command

     greader2org postrank

  which will add `postrank_feed:` parameter to all feeds for which
  PostRank feed is available

- the command above may report some feeds as unavailable on PostRank,
  if so, register on PostRank and paste those feeds for analysis
  (and rerun `greader2org postrank` on the next day)

- edit the feeds.txt file and set

     level: best

  or

     level: great

  or

     level: good

  for any feed you would like to subscribe filtered (best picks only
  the best articles, good all articles which caused some reader reaction,
  great lies in between)

- execute normal `greader2org put`, which will perform all normal
  changes but also for any feed for which level was set (or changed)
  will unsubscribe the original feed and subscribe the filtered
  feed instead of it 

To stop filtering, just remove `level:` from given feed and 
run `greader2org put`, the filtered feed will be unsubscribed,
and the original feed subscribed.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.