Nuush: Command line feed reader (shell script)

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

Formats 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

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]}

Readability

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:

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

Download

Documentation

Installation

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

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

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:

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).

Non-interactive use

Key name	Key default	Main menu	Feed menu
key_add	a	Add a feed to the list
key_browser	g		Go to selected feed item URL
key_browseralt	G		Same as above, but with $browser_alt
key_change	c	Change feed info (Title, URL, tag, frequency)
key_delfeed	d	Delete a feed
key_import	i	Import feeds from an OPML file
key_list	l		Show feed items
key_mark_read	r		Mark all items as read
key_print	p	Print feeds items to a PDF file	Print the current selected feed items to a PDF file
key_printall	P	Same as above, but for all items	Same as above, but for all items
key_quit	q	Quit nuush	Quit feed menu and go to main menu
key_quitall	Q	Quit nuush	Quit nuush
key_refresh	f	Download only the feeds older than their frequency	XXX
key_refreshall	F
key_tag	t	Show only the ites tagged with chosen tag
key_update	u	Download all the feeds, no matter the frequency	XXX
key_updateall	U
key_writeurl	w	Write the current feed item URL to an HTML redirect file

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

FAQ

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

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

[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.

Nuush

About