Org-feed.el: improve documentation

doc/ChangeLog

@@ -1,3 +1,7 @@
+2009-03-27  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (RSS Feeds): New section.
+
 2009-03-21  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* orgcard.tex:  Document M-e and M-a navigate

doc/org.texi

@@ -236,6 +236,7 @@ Deadlines and scheduling
 Capture
 
 * Remember::                    Capture new tasks/ideas with little interruption
+* RSS Feeds::                   Getting input from RSS feeds
 * Attachments::                 Add files to tasks.
 
 Remember
@@ -5367,10 +5368,11 @@ related to a task (@i{attachments}) in a special directory.
 
 @menu
 * Remember::                    Capture new tasks/ideas with little interruption
+* RSS Feeds::                   Getting input from RSS feeds
 * Attachments::                 Add files to tasks.
 @end menu
 
-@node Remember, Attachments, Capture, Capture
+@node Remember, RSS Feeds, Capture, Capture
 @section Remember
 @cindex @file{remember.el}
 
@@ -5653,7 +5655,52 @@ Use the refile interface to jump to a heading.
 Jump to the location where @code{org-refile} last moved a tree to.
 @end table
 
-@node Attachments,  , Remember, Capture
+@node RSS Feeds, Attachments, Remember, Capture
+@section RSS feeds
+
+Org has the capablity to add and change entries based on information found in
+RSS feeds.  You could use this to make a task out of each new podcast in a
+podcast feed.  Or you could use a phone-based note-creating service on the
+web to import tasks into Org.
+
+To access feeds, you need to configure the variable @code{org-feed-alist}.
+The docstring of this variable has detailed information.  Here is just an
+example:  
+
+@example
+(setq org-feed-alist
+      '(("ReQall"
+         "http://www.reqall.com/user/feeds/rss/a1b2c3....."
+         "~/org/feeds.org" "ReQall Entries")
+@end example
+
+will configure that new items from the feed provided by @file{reqall.com}
+will result in new entries in the file @file{~/org/feeds.org} under the
+heading @samp{ReQall Entries}, whenever the following command is used:
+
+@table @kbd
+@kindex C-c C-x g
+@item C-c C-x g
+Collect items from the feeds configured in @code{org-feed-alist} and act upon
+them.
+@kindex C-c C-x G
+@item C-c C-x G
+Prompt for a feed name and go to the inbox configured for this feed.
+@end table
+
+Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
+it will store information about the status of items in the feed, to avoid
+adding the same item several times.  You should add @samp{FEEDSTATUS} to the
+list of drawers in the file where you collect feed data:
+
+@example
+#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
+@end example
+
+For more information, see the file header of @file{org-feed.el} and the
+docstring of @code{org-feed-alist}.
+
+@node Attachments,  , RSS Feeds, Capture
 @section Attachments
 @cindex attachments
 

lisp/org-feed.el

@@ -24,15 +24,15 @@
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
 ;;; Commentary:
-
+;;
 ;;  This module allows to create and change entries in an Org-mode
 ;;  file triggered by items in an RSS feed.  The basic functionality is
-;;  geared toward simply adding items found in a feed as outline nodes
-;;  in an Org file, but using hooks, other actions can be performed
-;;  including changing entries based on changes of items in the feed.
+;;  geared toward simply adding new items found in a feed as outline nodes
+;;  to an Org file.  Using hooks, arbitrary actions can be triggered for
+;;  new or changed items.
 ;;
 ;;  Selecting feeds and target locations
-;;  -----------------------------------
+;;  ------------------------------------
 ;;
 ;;  This module is configured through a single variable, `org-feed-alist'.
 ;;  Here is an example, using a notes/tasks feed from reQall.com.
@@ -45,14 +45,15 @@
 ;;  With this setup, the command `M-x org-feed-update-all' will
 ;;  collect new entries in the feed at the given URL and create
 ;;  entries as subheadings under the "ReQall Entries" heading in the
-;;  file "~/org.feeds.org".  You can then change and even move these
-;;  entries, and they will not be added again (see below).
-
-;;  In addition to these standard elements, additional keyword-value
-;;  pairs are possible as part of a feed setting.  For example, here
-;;  we de-select entries with a title containing
-;;       "reQall is typing what you said"
-;;  using the `:filter' argument:
+;;  file "~/org.feeds.org".  Each feed needs to have its own heading.
+;;
+;;  Besides these standard elements that need to be specified for each
+;;  feed,, keyword-value pairs can set additional options.  For example,
+;;  to de-select transitional entries with a title containing
+;;
+;;                   "reQall is typing what you said",
+;;
+;;  you could use the `:filter' argument:
 ;;
 ;;    (setq org-feed-alist
 ;;          '(("ReQall"
@@ -60,7 +61,7 @@
 ;;             "~/org/feeds.org" "ReQall Entries"
 ;;             :filter my-reqall-filter)))
 ;;
-;;     (defun my-reqall-filter (e)
+;;    (defun my-reqall-filter (e)
 ;;       (if (string-match "reQall is typing what you said"
 ;;                         (plist-get e :title))
 ;;           nil
@@ -68,28 +69,24 @@
 ;;
 ;;  See the docstring for `org-feed-alist' for more details.
 ;;
+;;
 ;;  Keeping track of previously added entries
 ;;  -----------------------------------------
 ;;
 ;;  Since Org allows you to delete, archive, or move outline nodes,
-;;  org-feed.el needs to keep track of which feed items have been added
-;;  before, so that they will not be added again.  For this, org-feed.el
+;;  org-feed.el needs to keep track of which feed items have been handled
+;;  before, so that they will not be handled again.  For this, org-feed.el
 ;;  stores information in a special drawer, FEEDSTATUS, under the heading
-;;  that received the input of the feed.  For this reason, each feed must
-;;  have its own headline in an Org file.  You should add FEEDSTATUS
+;;  that received the input of the feed.  You should add FEEDSTATUS
 ;;  to your list of drawers in the files that receive feed input:
 ;;
-;;    #+DRAWERS: PROPERTIES LOGBOOK FEEDSTATUS
+;;       #+DRAWERS: PROPERTIES LOGBOOK FEEDSTATUS
 ;;
 ;;  Acknowledgments
 ;;  ----------------
 ;;
 ;;  org-feed.el is based on ideas by Brad Bozarth who implemented a
-;;  similar mechanism using shell and awk scripts, and who in this
-;;  way made me for the first time look into an RSS feed, showing
-;;  how simple this really was.  Because I wanted to include a
-;;  solution into Org with as few dependencies as possible, I
-;;  reimplemented his ideas in Emacs Lisp.
+;;  similar mechanism using shell and awk scripts.
 
 ;;; Code:
 
@@ -559,18 +556,7 @@ containing the properties `:guid' and `:item-full-text'."
 
 (provide 'org-feed)
 
-;;; org-feed.el ends here
-
 ;; arch-tag: 0929b557-9bc4-47f4-9633-30a12dbb5ae2
 
+;;; org-feed.el ends here
 
-;1. parse all items
-;2. filter with user filter
-;3. Remove GUIDs that we have already *added* before
-;4. Format, using user or built-in formatter
-;5. add new items
-;6. Store the guids from step 2, after the filtering
-;   This means that the feed could go back, have the entry
-;   pass the filter, and then it will be added.;
-
-					;Each item will be added once, when it first passes the filter.