Commits

Marcin Kasperski committed 7af5809

(re)organising docs

  • Participants
  • Parent commits 478cec1

Comments (0)

Files changed (3)

 
-========================
-mekk.feeds (greader2org)
-========================
+===========
+mekk.feeds
+===========
 
-Manage Google Reader subscribtions editing the text file (org-mode
-compatible syntax). You can use it to:
+Helper scripts for heavy RSS user.
 
-- export the list of subscribed feeds to readable text file,
+Content
+=========
 
-- save back to Google changes made in this file (feeds can be 
-  renamed, unsubscribed, moved to other folders)
+Currently the following script is available:
 
-See doc/usage.txt for detailed information, run 
+greader2org
 
-    greader2org
+  Manage Google Reader subscribtions editing the text file (org-mode
+  compatible syntax). You can use it to export the list of subscribed
+  feeds to readable text file, edit this file and save changes
+  back. See `more elaborate description on the blog`_ and 
+  `doc/greader2org.txt`_ within the sources.
 
-for the list of available commands. 
 
-See also `the project page`_.
+Sources
+=========
 
-.. _the project page: http://mekk.waw.pl/mk/projects/reader2org
+The project is `hosted on bitbucket`_.
+
+
+
+.. _more elaborate description on the blog: http://blog.mekk.waw.pl/archives/31-Editing-Google-Reader-subscriptions-with-a-text-editor.html
+
+.. _doc/greader2org.txt: 
+
+.. _hosted on bitbucket: http://bitbucket.org/Mekk/mekk.feeds

File 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.
+
+
+
+
+
+

File doc/usage.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.
-
-
-
-
-
-