Current version: 0.1

About

Nuush is a shell script that lets you to keep track of your web feeds and read them on your terminal.

Nuush is free and unencumbered public domain software. For more information, see http://unlicense.org/

Features

Summary of the main features:

Formats supported

Nuush supports well-formed Atom, RDF and RSS feeds.

Examples of feeds supported:

Configurability

The keys used to interact with the script, as well as the browser(s) and the location of the generated files, can be changed in the configuration file.

Tags and frequencies

You can specify tags for your feeds. Then, you can view and/or print only feeds with a specific tag.

You have to declare a frequency (daily, weekly, biweekly, monthly) with which you'd like to update feeds. This comes handy when you know that a feed is not updated frequently.

Dependencies

Besides basic utilities usually available on unix-like systems (grep, sed, date), you'll need XMLStarlet and a text-based web browser. If you want to generate PDFs then you'll need groff and ps2pdf.

Generate a PDF of your feeds

Look at the sample:
http://chr.tx0.org/files/nuush-paper.pdf

Multiple browser support

The script needs a web browser to format the feeds, because feeds tend to be formatted, more and more, with HTML instead of plain text. So, instead of trying to figure out wich feed is plain text and wich HTML, everything is piped throuh a text-based web browser. You can choose which one. The most common are Lynx, ELinks and w3m.

You can specify an alternate browser. This is useful in two contexts: 1) if you want to open a link in a background window, you can use screen (in this case the alternate browser could be, e.g., 'screen elinks'); 2) if you run nuush on your local machine, you can choose a local browser.

You can always use a local browser to follow the links in your feeds, even if you are connected to a remote server. You'll need a web space on that server, so that you can write a redirect page that you'll open with your local browser. (See the credits section below.)

Import and/or export feeds with OPML

OPML is a file format generally used for exchanging lists of feeds between aggregators. The time needed to import a list of 100 feeds is roughly 16 seconds.[note:import]

Export is not yet implemented.

Readability

(This is currently in the next branch: https://github.com/chr/nuush/tree/next.)

Sometimes (actually very often) articles are surrounded by a lot of (more or less) unrelated features: menus, ads, widgets, etc. This implies that reading an article can be a pain. Luckily people have thought about this issue and have come up with various solutions. Nuush can open a clean version of articles in your browser, by using an external filter. It uses a server version of Arc90's Readability. You'll need to add to your configuration file a variable which indicates where is the readability filter. By default it's:

readability='http://chr.tx0.org/pub/readability?url='

When you want to read a notice by cleaning it first, you'll need to press $key_strip (s by default) or $key_stripalt (S by default; this is similar to the alternative browser feature). The article will go through http://chr.tx0.org/pub/readability: it will be processed by a PHP script which will return a clean version of the article. You are encouraged to set up your own readability script. If you want to do so, and want some help contact me.

Screenshots/screencast

Screenshots

1) [ 9] Slashdot
2) [ 6] The Register
3) [ 4] VoxEU
4) [ 3] WB - Blogs
5) [ 3] YUI Blog
6) [ ?] 43 Folders
>> 















Fig. 1: Initial screen.
1) [ 8] Slashdot
2) [ 6] The Register
3) [ 4] VoxEU
4) [ 3] WB - Blogs
5) [ 3] YUI Blog
6) [ ?] 43 Folders
7) [ 5] AIER's Research Commentaries
>> 2
 1) ALK CoPilot Live 8
 2) US to cede control of ICANN?
 3) UK webhosts in champagne throwing cat fight
 4) Google hits Android dev with cease-and-desist letter
 5) IBM punts fixed-cost BlackBerry support plan
 6) Tech trendsetters reveal all
>> 







Fig. 2: Feed contents
4) [ 3] WB - Blogs
5) [ 3] YUI Blog
6) [ ?] 43 Folders
7) [ 5] AIER's Research Commentaries
>> 2
 1) ALK CoPilot Live 8
 2) US to cede control of ICANN?
 3) UK webhosts in champagne throwing cat fight
 4) Google hits Android dev with cease-and-desist letter
 5) IBM punts fixed-cost BlackBerry support plan
 6) Tech trendsetters reveal all
>> 2

US to cede control of ICANN?

    Toothless global panel awaits

  The US government has reportedly agreed to cede control over ICANN once
  its current pact with the internet oversight body expires next week.


>> 

Fig. 3: Feed item
1) [ 9] Slashdot
2) [ 6] The Register
3) [ 4] VoxEU
4) [ 3] WB - Blogs
5) [ 3] YUI Blog
6) [ ?] 43 Folders
>> a
Feed title (e.g., My feed)
>> AIER's Research Commentaries
Feed URL (e.g., http://example.net/feed.xml)
>> http://www.aier.org/research/commentaries?format=feed&type=atom
Feed frequency (d=daily, w=weekly, b=biweekly, m=monthly)
>> b
Feed tag (e.g., blogs)
>> 






Fig. 4: Feed addition

Screencast

You can see nuush at work at nuush-screencast.html (flash: 1.2M).

Download

Nuush is available at the following location:
http://github.com/chr/nuush/raw/master/nuush

You can clone the repository:
$ git clone git://github.com/chr/nuush.git

Documentation

Installation

As for installation, all you have to do is downloading the script and making it executable. For instance:

$ wget --no-check-certificate https://github.com/chr/nuush/raw/master/nuush
$ chmod u+x nuush

Note that the --no-check-certificate makes wget ignore github's SSL certificate, but you can go there with a browser.

If you downloaded it somewhere in your $PATH, you can run it directly

$ nuush

otherwhise, you'll need to invoke it like

$ ./nuush

Interactive use

After you invoke nuush, it will display the feeds list and their status like in Fig. 1 (when you run it the first time it generates a sample feeds list with two subscriptions). Let's call this the main screen. By default, all you feeds are loaded. You can list only those with a specific tag by typing t (this is the default key for $key_tag). If you want to display only a specific category of feeds in a persistent way, you can give a value to the variable $tag in the configuration file.

If you've already read some feeds, the number in brackets indicates how many items are unread (the maximum number of new feeds displayed is controlled with $MAXITEMS). Instead, if you have a feed that you haven't selected before a '?' will be present (that's the case of 43 Folders in Fig. 1). Indeed, when you select a feed from the list (typing its number, present on the left of the main screen) it's downloaded if it wasn't present before, or its items become visible. This is the case in Fig. 2 (the feed screen), where The Register's feed was selected.

You can then select one of the items displayed in the feed screen, like in Fig. 3. You can then: select another item (with its number); list the remaining items (the default key, $key_list, is l);[note:read] visit the relative URL (with the default or alternate web browser, which default keys are, respectively, g and G, defined by $key_browser and $key_browseralt), or write it to a web page (the default key, $key_writeurl, is w, and the web page is defined by $file_html); leave the feed screen or exit completely (defaults keys are, respectively. q and Q, defined by $key_quit and $key_quitall).

You can also refresh or update the feed or all the feeds. The former action downloads the feed only if is older than the frequency you specified for it, while the latter downloads the feed no matter how old/recent it is. The keys are f, F, u and U. The difference is that the lower case letters act only on the current feed, while the uppecase letters on all your feeds (or, actually, on those present in the main screen). Similarly, you can generate a PDF of the current feed (with p, default for $key_print) or all the feeds (with P, default for $key_printall).

The feeds list is a plain text file. It's default location is ~/.nuush/feed_list.txt. It's format is like:

Title: My feed 1
URL: http://blog.example.com/feed.atom
Freq: w
Tag: blog

Title: My feed 2
URL: http://another.example.org/dir/feed.rss
Freq: d
Tag: news,tech

Every feed block (Title: + URL: + Freq: + Tag: ) must be separated by (at least) a newline. You can change some information in feed_list.txt, add a new feed, or import an OPML, from the main screen by typing a, c, or i, respectively (default for $key_add, $key_change, and $key_import).

Here is a table with all default keybindings.

Key nameKey defaultMain menuFeed menu
key_addaAdd a feed to the list
key_browsergGo to selected feed item URL
key_browseraltGSame as above, but with $browser_alt
key_changecChange feed info (Title, URL, tag, frequency)
key_delfeeddDelete a feed
key_importiImport feeds from an OPML file
key_listlShow feed items
key_mark_readrMark all items as read
key_printpPrint feeds items to a PDF filePrint the current selected feed items to a PDF file
key_printallPSame as above, but for all itemsSame as above, but for all items
key_quitqQuit nuushQuit feed menu and go to main menu
key_quitallQQuit nuushQuit nuush
key_refreshfDownload only the feeds older than their frequencyXXX
key_refreshallF
key_tagtShow only the ites tagged with chosen tag
key_updateuDownload all the feeds, no matter the frequencyXXX
key_updateallU
key_writeurlwWrite the current feed item URL to an HTML redirect file

There may or may not be other features. Look at the source and play with it.

Non-interactive use

You can invoke the script without opening the text interface (that's non-interactive) like:

nuush -i $file
Import an OPML file
nuush -p [$tag]
Generate a PDF file of yor feeds (if you select a $tag, print only the feeds with that tag, otherwise print all the feeds).
nuush -t $tag
Make nuush opens the main screen with the feeds tagged with $tag (OK, non-interactive is not correct…)
nuush -r [$tag]
Reload your feeds (all if you don't specify a $tag)
nuush -s [$tag]
Synchronise your feeds (all if you don't specify a $tag)

Note: Change $file and $tag for real names of files or tags!

FAQ

Why?
Probably the question is Why yet another feed reader?. Well, for various reasons I prefer to use CLI apps (and if you are reading this there are good chances that you think the same). This cuts out GUI feed readers. [For feeds that usually have images or videos (e.g., http://www.xkcd.com/atom.xml), I use Opera's built-in feed reader]. There are very good alternatives, specially Newsbeuter and Snownews. Unfortunately (at least before I began to write the first lines of Nuush) the former doesn't (didn't?) run on NetBSD and the latter has (had?) problems with atom feeds (actually there was another issue, but I can't remember exactly what it was).
Isn't Nuush too slow?
Maybe, but it's not a big problem. It's slow only when you update your feed list, that is when you use $key_update (u by default). In that case, you'll force a download of all your subscriptions. That's why it's better you specify a frequency for your feeds and use $key_refresh (f by default): you will download only feeds older than Freq (1, 7, 15, 30 days). If you really want to update your feed list, you should consider running Nuush in a (daily) cronjob as: nuush -u (you probably will need to specify the full path where Nuush can be found), or nuush -u yourTag if you want to update feeds tagged with yourTag.
What's #!/usr/bin/env bash ?
That's a shebang that makes the script locate where bash is on your system. It's an attempt to make Nuush portable across various systems. For instance, on NetBSD (with packages installed via pkgsrc), Bash can be found at /usr/pkg/bin/bash, while on Debian it's on /bin/bash.
Bash?
Mmh, yes… and I even prefer ksh. However, it's more likely that: 1) Bash is installed on more systems; 2) Bash is Bash. With the latter point I mean that ksh could be pdksh, ksh88, ksh93. Nuush has been tested on ksh93. Actually, until recently, it was a ksh93 script.

Acknowledgments

Misc

Issues

RSS support

Even though RSS is supported, it's preferable that you choose Atom or RDF, if you can. All date-times in RSS conform to the Date and Time Specification of RFC 822[note:spec]. It means that a typical date is something like Sat, 07 Sep 2002 00:00:01 GMT, that is not easily sortable. Because of that, RSS feeds need to be pre-adjusted before they can be sorted, and this slightly slows down the updates. On the contrary, Atom and RDF have sane date formats.[note:exslt-date] Anyway, with the suggestion made above in mind, feel free to choose whichever format you want.

date(1)

Your date(1) program needs to understand the -d option, that is needed to pass the RSS date format in order to replace it with an epoch time stamp. That option seems to be a GNU extension. If your date(1) doesn't understand the -d option you can modify the source and use gdate(1).

Alternatives

If you are looking for a console feed reader, there are various good alternatives out there. For instance:

You could be also interested in programs that retrive feeds and send it to a mail file. Some examples:

TODO

There's a wiki page if you want to suggest something or give feedback.


Notes

[note:import] A file with 100 feeds was imported 5 times and the average results were:

real    0m15.57s
user    0m6.18s
sys     0m3.08s

[note:spec] http://cyber.law.harvard.edu/rss/rss.html

[note:read] When you press $KEY_LIST you will see only the remaining new articles listed. In fact when you read an article, it's marked read, and the script is configured to display only unread articles. This can be see as a feature (as I do) or as an issue.

[note:exslt-date] XMLStarlet supports the date and time extension in EXSLT, but, again (and as far as I know), RSS-type date formats are not compatible with it.