Files

The default location of your configuration file is the ~/.nrss/config. This can be modified by using the -D or -C flags when you call nrss (changing the directory and the config file paths respectively). This configuration is parsed a line at a time and every argument must be quoted as shown.

add "http://www.digg.com/rss/index.xml" "Digg All"

The second argument is a “handle” it can be anything that you like, but is used to refer to the feed later on.

Setting Feed Attributes

You can also set a number of attributes on a feed. First there is the rate, which determines how often (in minutes) a feed should be updated. Then, there is maxitems which controls how many items will be parsed. Finally, there is show, which controls how many items are shown by default. Showing the maximum number of items or the value set here can be toggled. This is useful for reading fast moving feeds with lots of items, without cluttering the interface.

rate "30" "Slashdot"
maxitems "100" "Digg All"
show "1" "Penny Arcade"

Setting Default Attributes

Each of the above attributes, rate,maxitems,show can be set for all feeds added after these lines.

default_rate "30"
default_maxitems "10"
default_show "5"

Columns

As of 0.3.0, NRSS supports columns. You can specify the number of columns by changing the -c flag when running nrss, or you can set a line in your config like so:

columns "3"

Key Bindings

As of 0.3.0, NRSS supports custom key bindings. There are a number of actions you can bind a key too.

Action Meaning
quit Quit NRSS
next Select Next Item
prev Select Prev Item
next-feed Select Next Feed
prev-feed Select Prev Feed
goto Open Item/Feeds Link in Browser
refresh Refresh Current Feed
refresh-all Refresh All Feeds
mark-all-read Mark All Items Read
default Opens the Reader or Collapses/Uncollapses Feed
toggle-collapse-all Collapse all Feeds*
toggle-expand Expand/Unexpand Feed
toggle-usage Show the usage screen

- Collapse all feeds. The default type is to set a flag which will show all feeds in their collapsed state, but not actually change their state. So, for example, if you have all but your first two feeds open, collapse all feeds, and uncollapse all feeds, your first two feeds will still be closed. Once all feeds are collapsed this way, there is no way to uncollapse a single feed. Because this is may feel counter-intuitive, there is also toggle-set-collapse-all which will set each feed as collapsed, but lose the previous state. Using this function, it is possible to uncollapse a single feed as usual.

There is a difference between Expand and Uncollapse. When a feed is “expanded” the maxitems number of items is shown. When a feed is “collapsed” no items are shown. An “uncollapsed” feed is the usual view, show items are shown. If that sounds confusing, read the attributes section above.

You can modify the binding for each of these actions like so:

key "quit" "z"

Which would bind the z key to quit. For untypable characters (like arrow keys, backspace, home, end, enter, etc.) you can use their NCurses macro name. For example

key "default" "KEY_RETURN"

Will change the key to perform the default action (open the reader, or collapse/uncollapse a feed) to Return/Enter, rather than Space, as it is without any configuration.

In addtion, you can add modifiers like Alt or Control by adding M- and C- (respectively) to the beginning of the key definition. So, for example, to make exitting CTRL-ALT-x instead of just simply q, you could use this:

key "quit" "C-M-q"

There is a listing of the possible KEY_ values in your ncurses.h on your machine, or in `man getch`, which is reproduced here .

Notes on key bindings

As a warning, some keys aren’t mapped onto your keyboard. You can usually tell these keys apart because they have names that you’ve never heard of.

Also, in order for these to work in NRSS, they can’t be swallowed by another program. This sounds obvious, but things like signals sent by some terminals are odd. For example, the traditional CTRL-c to issue a SIGINT. You can bind that to an action in NRSS but it will never be used. This is one of the reasons that NRSS’s default key are all very simple, unmodified letters.

Function keys can be used by specifying KEY_F#, like KEY_F10 or KEY_F2, etc.

KEY_RETURN is a binding in NRSS rather than Ncurses, but it maps to the return key. KEY_ENTER doesn’t seem to work, but it’s included for the sake of completeness.

Filters

NRSS supports filtering the text of titles and descriptions through arbitrary filters. For example, if you read feeds that embed HTML elements into the text, you can run the content through w3m and it will format the HTML correctly. Alternatively, you could merely eliminate the HTML. If you don’t like long descriptions, you can truncate it to a certain number of characters.

For such things I recommend Perl, but any language that can read from standard in and print to standard out can be used to filter. Here is an example of the filters I use.

h2t.pl — Use w3m to format text

#!/usr/bin/perl
use IPC::Open2;
local (*READ, *WRITE);
open2(\*READ, \*WRITE, "/usr/bin/w3m -dump -T text/html");
while(<>) {print WRITE $_}
close(WRITE);
while(<READ>)
{
  s/%/\\%/g;
  s/\(/\\\(/g;
  s/\)/\\\)/g;
  print $_;
}

And for titles, I use this:
titles.pl — Strip out various common escapes

#!/usr/bin/perl
while(<>){
        s/&amp;/&/g;
        s/&quot;/"/g;
        s/&mdash;/-/g;
        s/%/\\%/g;
        s/\(/\\\(/g;
        s/\)/\\\)/g;
        print $_;
}

If you’re not too keen on installing w3m, a simple set of regexes that will attempt to do a bit of formatting and strip out other unwanted things (like escaped & like stuff, weird escaped encoded characters, HTML tags) etc. You can use the following:

simple.pl — Basic formatting and cleanups

#!/usr/bin/perl
use strict;
while (<>) {
  s/%/\\%/g;
  s/<br\s?\/>/\n/g;
  s/<p>(.*)<\/p>/\n\n\1/g;
  s/<\/?(\w)+[^>]*>//g;
  s/&amp;/&/g;
  s/&quot;/"/g;
  s/&mdash;/-/g;
  s/&#[^;]*;//g;
  s/\s*$//g;
  print $_;
}

Of course, the output won’t nearly be as pretty as if you were using a full HTML formatting program like w3m or another text HTML pager.

A note on filters

Perl coders will notice that the above code will escape all (,), and % with a forward slash. This is not necessary but recommended. This will keep the ternary and style of the feed safe from getting confused (these things discussed in the style section).

This functionality is not built in so that you can potentially use the filters to inject style on particular pieces of text. For example changing \*something\* into something

Anyway, the lines in your config to use such scripts are as such.

description_filter "/some/path/someprogram"
title_filter "/some/path/someprogram"

NRSS is not a shell so these lines can’t include pipe redirects, or paths using ~.

Helpers

Apart from filters, NRSS can use two other programs. The first is the browser, which is entirely optional, and will be used if you hit the ‘g’ key. The argument given should include %u which will be replaced by the URL of the link. For example

browser "/usr/bin/firefox %u"

If you use a text based browser that will take over the terminal from NRSS, then you have to tell NRSS to surrender the terminal and wait for the browser to finish before doing anything else.

browser "/usr/bin/elinks %u"
browser_wait "1"

The last helper that NRSS uses is a HTTP fetch program. Generally, this is wget. NRSS will attempt to find wget at compile time and use that path to wget as the default path. If that fails it defaults to the Linux usual path, /usr/bin/wget. If wget is not detected, or if you want to use a fetch program other than wget (curl for example), then you can redefine the program like so:

wget "/somepath/wget -N -q -O \"%p\" -U %a %u"

This shouldn’t usually be necessary. The escapes used above are %p for the path to download it to, %a for the agent string (NRSS-1.0.0) and finally %u for the URL to download.

Note on overriding wget

If you decide to override using wget for another HTTP fetcher, then you should ensure that the program has a quiet mode in which it won’t attempt to write to the screen.