If you just want to try NewsFeed out, no installation is necessary at all. Simply untar the file, cd to the directory and run ./newsfeed. As Python can find packages in the current working directory as well as the global locations, everything should work as expected.
If you want to install the program globally or under your home directory, please choose one of the following two methods:
Method A (automatic install): Use the distutils approach. Untar the file and then do python setup.py install. See the distutils documentation for installation options like directory paths.
Method B (manual install):
If you want auto-subscription to work you have to consult your web browser documentation on how to add a handler for specific MIME types or keywords, see below.
NewsFeed uses the Universal Feed Parser by Mark Pilgrim for the fetching, parsing, and autodiscovery of feeds. Slightly outdated versions of these modules are included in the distribution for ease of use, but newer versions should work as well.
The NewsFeed main window features a familiar three-pane layout similar to many email programs, where in the left vertical pane the newsfeeds and active searches are listed, with buttons right below to move the active feed up and down in the list. Behind the entries the number of unread items in the feed is shown in parentheses. Empty feeds or feeds that did not update correctly the last time (e.g., because of a server timeout) are put in square brackets. Right below the buttons is the progress bar, which is white normally, but shows a green bar when an update is in progress.
Right next to the feed list is the items list for the selected feed, with newest items at the top. Items that were already displayed are shown slightly indented and in parentheses, whereas new, unread items are shown without indentation. If available, the column right next to the one with the subject lines shows the time stamps for the individual messages, or if not available, for the feed.
Below the topic list is the main text area where the description of the selected item is displayed. In the top right corner is again the date as supplied by the feed if available, while in the lower right corner the download date is shown in local time. The article headline is clickable and will open the browser that is set in the BROWSER shell environment variable. (Dillo is a good choice for a browser in this context, as it starts up very fast and displays most pages quite nicely.) Alternatively, pressing o or Return opens the current item. The headline will turn violet if has been visited in the browser. Finaly, the URI of the item is printed in a red font below the text.
Note that window positions and sizes are saved when you move or resize the windows. For the helper windows, this does not work if you close them with their close buttons, you have to do 'Accept' or 'Save', respectively.
In the content pane, directly above the item title there is a toolbar (as of v1.7) that contains buttons labeled "back" (Key < or Key [) and "forward" (Key > or Key ]) for navigating between read items in the standard web browser fashion.
Pressing q quits the application, while the Escape key cancels an update in progress (alternatively click the X next to the progress bar). Escape can also be used to dismiss the info and search windows.
Additionally, the up and down cursor keys go the previous/next item in the feed, while the left and right cursor keys jump to the previous/next feed. Finally, pressing v jumps to the history ("Recently Visited") feed.
The "Important Items" feed contains items that were marked as important, either by using the "Mark" button in the item pane toolbar or by using the keyboard shortcut n. Items in this feed never expire and subject lines of flagged items are prepended with "!!!". You can use the keyboard shortcut N (i.e. Shift-n) to jump to this feed.
The font size in the item description pane can be adjusted with the "Smaller" and "Larger" buttons from the item toolbar, or using the keyboard shortcuts + and -.
The keyboard shortcut i iconifies the application (or puts it in the dock on Mac OS X), h opens the homepage of the feed (as given by the URL under "Home:" in the Channel Info window).
"Export" writes the currently selected item to a file and calls an application with the filename as an argument. Lines 55 to 62 in newsfeed.py show how to set this up using template substitution. You can use this feature e.g. to
Next to the export button, there is a button labeled "t-digger" which opens the Talk Digger page for the selected item in the default browser (keyboard shortcut t).
This button is enabled by default but can be disabled on line 80 of newsfeed.py.
Custom refresh intervals are implemented as a an item in the refresh interval popup menu in the subscription info box, "Custom". The number of minutes this interval corresponds to is set on line 72 of newsfeed.py in the variable custom_interval. By default this is set to .333, i.e. about 20 seconds.
If you want to try the auto-discovery of feeds, enter an URL under "Home:" in the Channel Info window and click "Auto-Detect RSS Feed" (or just hit Return if your are confident :-). After a few seconds, one or more auto-detected feeds will appear in the feed list if the operation is successful. The temporary feed names are prepended with question marks, which tells NewsFeed to look for a feed name in the feed itself and use that.
Please also note that the Tkinter bindings to the Tk widget set tend to leak memory, depending on the version of the bindings used. In other words, the amount of memory occupied by NewsFeed may grow over time, even if it is mostly idling. Therefore it may not be a good idea to leave NewsFeed running for a prolonged period of time (days, weeks, or so) in a memory-starved or multi-user environment.
There is a basic console interface (e.g. for running via SSH) which can be activated with a command line option: newsfeed --nogui. Select a feed from the list by its number, then optionally select an item to open it in the browser. Use "0" to go back or exit.
If these environment variables are not set, builtin defaults will be used.
By default, the configuation as well as the cached data is stored in ~/.newsfeed, while in ~/.newsfeed.pid the PID of the currently running NewsFeed instance is stored. Finally, ~/.newsfeed.addfeed contains new URIs from the helper script and should be processed (and then deleted) by the main program.
As the entire program state is stored in the platform-independent ~/.newsfeed file, one can sync NewsFeed to a different machine or restore a previous state by copying / moving /renaming ~/.newsfeed.
Earlier versions of NewsFeed (up to 1.5.2) used only one copy of the configuration/cache file. In the unlikely event that the computer crashed while NewsFeed was in the midst of saving its state, the file could become corrupted.
As of NewsFeed 1.6, the configuration file is versioned, that is, older versions with the extensions .1, .2, .3, etc. are kept in case something goes wrong with the main file.
This versioning mechanism is fully automatic and also features automatic recovery, meaning that if the main configuration file is unreadable for some reason, NewsFeed looks for older revisions of the file and uses the most recent version.
If required, the number of old revisions to keep (which defaults to three) can be set on line 75 in newsfeed.py. Also note that, as opposed to the numbering scheme in VMS, lower extensions denote more recent versions.
As of v2.6, NewsFeed also looks for the file newsfeed_defaults.py—first in the current working directory, then in the directory where newsfeed.py resides, then in the usual module search path—and tries to import it. This file may contain definitions of global variables which override the assignments at the top of newsfeed.py.
So for instance, you could have a newsfeed_defaults.py that contains:
digger = False custom_interval = 1 browser_cmd = "konqueror %s &" config_file = "/Users/martin/Public/testfile" fontscaling = 1.2 ask_before_deletion = False
It would cause NewsFeed to
This feature is mainly meant to facilitate keeping NewsFeed together with Python/Tk and a lightweight web browser on a removable medium such as a USB flash drive. In this case, newsfeed_defaults.py should be in the same directory as the other Python scripts and minimally contain new definitions for browser_cmd (to point to the browser on the USB drive) and config_file (for NewsFeed to store its setting and cache on the drive as well).
In principle, getting auto-subscription, i.e. the appearance of new feeds in NewsFeed when you click on them in the browser, to work would consist in defining add_feed.py as a handler for files with ".rss" extensions. Now, apart from the fact that some feeds have an ".xml" entension, browsers decide on which program to use by MIME type.
Ideally, HTTP servers would be configured to send the MIME type "application/xml+rss" for files with "rss" extensions. Unfortunately, most are not, sending "text/xml" or even "text/plain" instead. This complicates auto-subscription unnecessarily, because Mozilla likes to handle the latter types internally.
Alternative solutions have been discussed at length, for instance prepending a "feed:" to the URI or replacing the "http://" with a "feed://". The add_feed.py script supports all these mechanisms, but since there exists no standard way of auto-subscription right now, expect problems, at least with some servers.
Given that Python is a byte-compiled language and that functional constructs are used heavily by the program, NewsFeed may become sluggish if the individual feeds have a lot of items. In that event, reducing the time for which items are cached may be a good idea for feeds with many new items per day (see bsize.py).
NewsFeed is not multithreaded, so it is perhaps advisable to simply leave it alone while it is updating (as indicated by the white/green status bar in the lower left corner), at least on high-latency internet connections.
Generally, having searches in the feed list slows the program down. Thus, for maximum performace, delete searches when you do not need them anymore.
Finally, make sure you are running the latest version of Python itself. Python v2.5 for example performs much better than v2.4 or v2.3.