NEWSBEUTER(1) | NEWSBEUTER(1) |
NAME¶
newsbeuter - an RSS/Atom feed reader for text terminals
SYNOPSIS¶
newsbeuter [-r] [-e] [-i opmlfile] [-u urlfile] [-c cachefile] [-C configfile] [-X] [-o] [-x <command> ...] [-h]
DESCRIPTION¶
newsbeuter is an RSS/Atom feed reader for text terminals. RSS and Atom are a number of widely-used XML formats to transmit, publish and syndicate articles, for example news or blog articles. Newsbeuter is designed to be used on text terminals on Unix or Unix-like systems such as Linux, BSD or Mac OS X.
OPTIONS¶
-h
-r
-e
-X
-v, -V
-i opmlfile
-u urlfile
-c cachefile
-C configfile
-x command ...
-o
-l loglevel
-d logfile
-E file
-I file
FIRST STEPS¶
After you’ve installed newsbeuter, you can run it for the first time by typing "newsbeuter" on your command prompt. This will bring you the following message:
Error: no URLs configured. Please fill the file /home/ak/.newsbeuter/urls with RSS feed URLs or import an OPML file.
newsbeuter 2.4 usage: ./newsbeuter [-i <file>|-e] [-u <urlfile>] [-c <cachefile>] [-x <command> ...] [-h]
-e export OPML feed to stdout
-r refresh feeds on start
-i <file> import OPML file
-u <urlfile> read RSS feed URLs from <urlfile>
-c <cachefile> use <cachefile> as cache file
-C <configfile> read configuration from <configfile>
-X clean up cache thoroughly
-x <command>... execute list of commands
-o activate offline mode (only applies to Google Reader synchronization mode)
-q quiet startup
-v get version information
-l <loglevel> write a log with a certain loglevel (valid values: 1 to 6)
-d <logfile> use <logfile> as output log file
-E <file> export list of read articles to <file>
-I <file> import list of read articles from <file>
-h this help
This means that newsbeuter can’t start without any configured feeds. To add feeds to newsbeuter, you can either add URLs to the configuration file $HOME/.newsbeuter/urls or you can import an OPML file by running "newsbeuter -i blogroll.opml". To manually add URLs, open the file with your favorite text editor and add the URLs, one per line:
http://rss.cnn.com/rss/cnn_topstories.rss http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml
If you need to add URLs that have restricted access via username/password, simply provide the username/password in the following way:
In order to protect username and password, make sure that $HOME/.newsbeuter/urls has the appropriate permissions. Newsbeuter also makes sure that usernames and passwords within URLs aren’t displayed in its user interface. In case there is a @ in the username, you need to write it as %40 instead so that it can be distinguished from the @ that separates the username/password part from the hostname part.
You can also configure local files as feeds, by prefixing the local path with "file://" and adding it to the $HOME/.newsbeuter/urls file:
Now you can run newsbeuter again, and it will present you with a controllable list of the URLs that you configured previously. You can now start downloading the feeds, either by pressing "R" to download all feeds, or by pressing "r" to download the currently selected feed. You can then select a feed you want to read, and by pressing "Enter", you can go to the article list for this feed. This works even while the downloading is still in progress. You can now see the list of available articles by their title. A "N" on the left indicates that an article wasn’t read yet. Pressing Enter brings you to the content of the article. You can scroll through this text, and also run a browser (default: lynx) to view the complete article if the content is empty or just an abstract or a short description. Pressing "q" brings you back to the article list, and pressing "q" again brings you back to the feed list. Pressing "q" a third time then closes newsbeuter.
Newsbeuter caches the article that it downloads. This means that when you start newsbeuter again and reload a feed, the old articles can still be read even if they aren’t in the current RSS feeds anymore. Optionally you can configure how many articles shall be preserved by feed so that the article backlog doesn’t grow endlessly (see "max-items" below).
Newsbeuter also uses a number of measures to preserve the users' and feed providers' bandwidth, by trying to avoid unnecessary feed downloads through the use of conditional HTTP downloading. It saves every feed’s "Last-Modified" and "ETag" response header values (if present) and advises the feed’s HTTP server to only send data if the feed has been updated by modification date/time or "ETag" header. This doesn’t only make feed downloads for RSS feeds with no new updates faster, it also reduces the amount of transferred data per request. Conditional HTTP downloading can be optionally disabled per feed by using the "always-download" configuration command.
Several aspects of newsbeuter’s behaviour can be configured via a configuration file, by default $HOME/.newsbeuter/config. This configuration file contains lines in the form "<config-command> <arg1> ...". The configuration file can also contain comments, which start with the # character and go as far as the end of line. If you need to enter a configuration argument that contains spaces, use quotes (") around the whole argument. It’s even possible to integrate the output of external commands into the configuration. The text between two backticks ("`") is evaluated as shell command, and its output is put on its place instead. This works like backtick evaluation in Bourne-compatible shells and allows users to use external information from the system within the configuration.
Searching for articles is possible in newsbeuter, too. Just press the "/" key, enter your search phrase, and the title and content of all articles are searched for it. When you do a search from the list of feeds, all articles of all feeds will be searched. When you do a search from the article list of a feed, only the articles of the currently viewed feed are searched. When opening an article from a search result dialog, the search phrase is highlighted.
The history of all your searches is saved to the filesystem, to \~/.newsbeuter/history.search. By default, the last 100 search phrases are stored, but this limited can be influenced through the "history-limit" configuration variable. To disable search history saving, simply set the history-limit to 0.
CONFIGURATION COMMANDS¶
always-display-description (parameters: [true/false]; default value: false)
always-download (parameters: <rssurl> [<rssurl>]; default value: n/a)
article-sort-order (parameters: <sortfield>[-<direction>]; default value: date)
articlelist-format (parameters: <format>; default value: "%4i %f %D %6L %?T?;%-17T; ?%t")
auto-reload (parameters: [yes/no]; default value: no)
bind-key (parameters: <key> <operation> [<dialog>]; default value: n/a)
bookmark-cmd (parameters: <bookmark-command>; default value: "")
bookmark-interactive (parameters: [yes/no]; default value: no)
bookmark-autopilot (parameters: [yes/no]; default value: no)
browser (parameters: <browser-command>; default value: lynx)
cache-file (parameters: <path>; default value: "~/.newsbeuter/cache.db")
cleanup-on-quit (parameters: [yes/no]; default value: yes)
color (parameters: <element> <fgcolor> <bgcolor> [<attr> ...]; default value: n/a)
confirm-exit (parameters: [yes/no]; default value: no)
cookie-cache (parameters: <file>; default value: "")
datetime-format (parameters: <date/time format>; default value: %b %d)
define-filter (parameters: <name> <filter>; default value: n/a)
delete-read-articles-on-quit (parameters: [yes/no]; default value: "no")
display-article-progress (parameters: [yes/no]; default value: yes)
download-retries (parameters: <number retries>; default value: 1)
download-full-page (parameters: [yes/no]; default value: no)
download-timeout (parameters: <seconds>; default value: 30)
error-log (parameters: <path>; default value: "")
external-url-viewer (parameters: <command>; default value: "")
feed-sort-order (parameters: <sortorder>; default value: none)
feedlist-format (parameters: <format>; default value: "%4i %n %11u %t")
oldreader-flag-share (parameters: <flag>; default value: "")
oldreader-flag-star (parameters: <flag>; default value: "")
oldreader-login (parameters: <login>; default value: "")
oldreader-min-items (parameters: <number>; default value: 20)
oldreader-password (parameters: <password>; default value: "")
oldreader-passwordfile (parameters: <path-to-file; default value: "")
oldreader-show-special-feeds (parameters: [yes/no]; default value: yes)
feedhq-flag-share (parameters: <flag>; default value: "")
feedhq-flag-star (parameters: <flag>; default value: "")
feedhq-login (parameters: <login>; default value: "")
feedhq-min-items (parameters: <number>; default value: 20)
feedhq-password (parameters: <password>; default value: "")
feedhq-passwordfile (parameters: <path-to-file; default value: "")
feedhq-show-special-feeds (parameters: [yes/no]; default value: yes)
goto-first-unread (parameters: [yes/no]; default value: yes)
goto-next-feed (parameters: [yes/no]; default value: yes)
highlight (parameters: <target> <regex> <fgcolor> [<bgcolor> [<attribute> ...]]; default value: n/a)
highlight-article (parameters: <filterexpr> <fgcolor> <bgcolor> [<attribute> ...]; default value: n/a)
history-limit (parameters: <number>; default value: 100)
html-renderer (parameters: <path>; default value: internal)
http-auth-method (parameters: <method>; default value: any)
ignore-article (parameters: <feed> <filterexpr>; default value: n/a)
ignore-mode (parameters: [download/display]; default value: download)
include (parameters: <path>; default value: n/a)
keep-articles-days (parameters: <days>; default value: 0)
macro (parameters: <macro key> <command list>; default value: n/a)
mark-as-read-on-hover (parameters: [yes/no]; default value: no)
max-download-speed (parameters: <number>; default value: 0)
max-items (parameters: <number>; default value: 0)
notify-format (parameters: <string>; default value: "newsbeuter: finished reload, %f unread feeds (%n unread articles total)")
notify-program (parameters: <path>; default value: "")
notify-always (parameters: [yes/no]; default value: no)
notify-screen (parameters: [yes/no]; default value: no)
notify-xterm (parameters: [yes/no]; default value: no)
notify-beep (parameters: [yes/no]; default value: no)
opml-url (parameters: <url> ...; default value: "")
pager (parameters: [<path>/internal]; default value: internal)
podcast-auto-enqueue (parameters: [yes/no]; default value: no)
prepopulate-query-feeds (parameters: [yes/no]; default value: no)
ssl-verify (parameters: [yes/no]; default value: yes)
proxy (parameters: <server:port>; default value: n/a)
proxy-auth (parameters: <auth>; default value: n/a)
proxy-auth-method (parameters: <method>; default value: any)
proxy-type (parameters: <type>; default value: http)
refresh-on-startup (parameters: [yes/no]; default value: no)
reload-only-visible-feeds (parameters: [yes/no]; default value: no)
reload-time (parameters: <number>; default value: 60)
reload-threads (parameters: <number>; default value: 1)
reset-unread-on-update (parameters: <url> ...; default value: n/a)
save-path (parameters: <path>; default value: ~/)
search-highlight-colors (parameters: <fgcolor> <bgcolor> [<attribute> ...]; default value: black yellow bold)
show-keymap-hint (parameters: [yes/no]; default value: yes)
show-read-feeds (parameters: [yes/no]; default value: yes)
show-read-articles (parameters: [yes/no]; default value: yes)
suppress-first-reload (parameters: [yes/no]; default value: no)
swap-title-and-hints (parameters: [yes/no]; default value: no)
text-width (parameters: <number>; default value: 0)
ttrss-flag-publish (parameters: <character>; default value: "")
ttrss-flag-star (parameters: <character>; default value: "")
ttrss-login (parameters: <username>; default value: "")
ttrss-mode (parameters: [multi/single]; default value: multi)
ttrss-password (parameters: <password>; default value: "")
ttrss-passwordfile (parameters: <path-to-file; default value: "")
ttrss-url (parameters: <url>; default value: "")
unbind-key (parameters: <key> [<dialog>]; default value: n/a)
urls-source (parameters: <source>; default value: "local")
use-proxy (parameters: [yes/no]; default value: no)
user-agent (parameters: <user agent string>; default value: "")
AVAILABLE OPERATIONS¶
open (default key: ENTER)
quit (default key: q)
reload (default key: r)
reload-all (default key: R)
mark-feed-read (default key: A)
mark-all-feeds-read (default key: C)
save (default key: s)
next-unread (default key: n)
prev-unread (default key: p)
next (default key: J)
prev (default key: K)
random-unread (default key: ^K)
open-in-browser (default key: o)
open-in-browser-and-mark-read (default key: O)
help (default key: ?)
toggle-source-view (default key: ^U)
toggle-article-read (default key: N)
toggle-show-read-feeds (default key: l)
show-urls (default key: u)
clear-tag (default key: ^T)
set-tag (default key: t)
open-search (default key: /)
goto-url (default key: #)
enqueue (default key: e)
edit-urls (default key: E)
reload-urls (default key: ^R)
redraw (default key: ^L)
cmdline (default key: <colon>)
set-filter (default key: F)
select-filter (default key: f)
clear-filter (default key: ^F)
bookmark (default key: ^B)
edit-flags (default key: ^E)
next-unread-feed (default key: ^N)
prev-unread-feed (default key: ^P)
next-feed (default key: j)
prev-feed (default key: k)
delete-article (default key: D)
purge-deleted (default key: $)
view-dialogs (default key: v)
close-dialog (default key: ^X)
next-dialog (default key: ^V)
prev-dialog (default key: ^G)
pipe-to (default key: |)
sort (default key: g)
revsort (default key: G)
up (default key: UP)
down (default key: DOWN)
pageup (default key: PPAGE)
pagedown (default key: NPAGE)
TAGGING¶
Newsbeuter comes with the possibility to categorize or "tag", as we call it, RSS feeds. Every RSS feed can be assigned 0 or more tags. Within newsbeuter, you can then select to only show RSS feeds that match a certain tag. That makes it easy to categorize your feeds in a flexible and powerful way.
Usually, the ~/.newsbeuter/urls file contains one RSS feed URL per line. To assign a tag to an RSS feed, simply attach it as a single word, separated by blanks such as space or tab. If the tag needs to contain spaces, you must use quotes (") around the tag (see example below). An example \~/.newsbeuter/urls file may look like this:
http://blog.fefe.de/rss.xml?html interesting conspiracy news "cool stuff" http://rss.orf.at/news.xml news orf http://www.heise.de/newsticker/heise.rdf news interesting
When you now start newsbeuter with this configuration, you can press "t" to select a tag. When you select the tag "news", you will see all three RSS feeds. Pressing "t" again and e.g. selecting the "conspiracy" tag, you will only see the http://blog.fefe.de/rss.xml?html RSS feed. Pressing "^T" clears the current tag, and again shows all RSS feeds, regardless of their assigned tags.
A special type of tag are tags that start with the tilde character ("~"). When such a tag is found, the feed title is set to the tag name (excluding the \~ character). With this feature, you can give feeds any title you want in your feed list:
http://rss.orf.at/news.xml "~ORF News"
Another special type of tag are tags that start with the exclamation mark. When such a tag is found, the feed is hidden from the regular list of feeds and its content can only be found through a query feed.
http://rss.orf.at/news.xml "!ORF News (hidden)"
SCRIPTS AND FILTERS¶
From version 0.4 on, newsbeuter contains support for Snownews extensions. The RSS feed readers Snownews and Liferea share a common way of extending the readers with custom scripts. Two mechanisms, namely "execurl" and "filter" type scripts, are available and supported by newsbeuter.
An "execurl" script can be any program that gets executed and whose output is interpreted as RSS feed, while "filter" scripts are fed with the content of a configured URL and whose output is interpreted as RSS feed.
The configuration is simple and straight-forward. Just add to your ~/.newsbeuter/urls file configuration lines like the following ones:
exec:~/bin/execurl-script filter:~/bin/filter-script:http://some.test/url
The first line shows how to add an execurl script to your configuration: start the line with "exec:" and then immediately append the path of the script that shall be executed. If this script requires additional parameters, simply use quotes:
"exec:~/bin/execurl-script param1 param2"
The second line shows how to add a filter script to your configuration: start the line with "filter:", then immediately append the path of the script, then append a colon (":"), and then append the URL of the file that shall be fed to the script. Again, if the script requires any parameters, simply quote:
"filter:~/bin/filter-script param1 param2:http://url/foobar"
In both cases, the tagging feature as described above is still available:
exec:~/bin/execurl-script tag1 tag2 "quoted tag" filter:~/bin/filter-script:http://some.test/url tag3 tag4 tag5
A collection of such extension scripts can be found on this website: http://kiza.kcore.de/software/snownews/snowscripts/extensions
If you want to write your own extensions, refer to this website for further instructions: http://kiza.kcore.de/software/snownews/snowscripts/writing
COMMAND LINE¶
Like other text-oriented software, newsbeuter contains an internal commandline to modify configuration variables ad hoc and to run own commands. It provides a flexible access to the functionality of newsbeuter which is especially useful for advanced users.
To start the commandline, type ":". You will see a ":" prompt at the bottom of the screen, similar to tools like vi(m) or mutt. You can now enter commands. Pressing the return key executes the command (possibly giving feedback to the user) and closes the commandline. You can cancel entering commands by pressing the ESC key. The history of all the commands that you enter will be saved to \~/.newsbeuter/history.cmdline. The backlog is limited to 100 entries by default, but can be influenced by setting the "history-limit" configuration variable. To disable history saving, set the history-limit to 0.
Starting with newsbeuter 2.0, the commandline provides you with some help if you can’t remember the full names of commandline commands. By pressing the TAB key, newsbeuter will try to automatically complete your command. If there is more than one possible completion, you can subsequently press the TAB key to cycle through all results. If no match is found, no suggestion will be inserted into the commandline. For the "set" command, the completion also works for configuration variable names.
In addition, some common key combination such as Ctrl-G (to cancel input), Ctrl-K (to delete text from the cursor position to the end of line), Ctrl-U (to clear the whole line) and Ctrl-W (to delete the word before the current cursor position) were added.
Please be aware that the input history of both the command line and the search functions are saved to the filesystems, to the files ~/.newsbeuter/history.cmdline resp. \~/.newsbeuter/history.search. By default, the last 100 entries are saved, but this can be configured (configuration variable history-limit) and also totally disabled (by setting said variable to 0).
Currently, the following command line commands are available:
quit
save <filename>
set <variable>[=<value>|&|!]
tag <tagname>
goto <case-insensitive substring>
source <filename> [...]
dumpconfig <filename>
<number>
FILES¶
$HOME/.newsbeuter/config
$HOME/.newsbeuter/urls
SEE ALSO¶
podbeuter(1). The documentation that comes with newsbeuter is a good source about the general use and configuration of newsbeuter.
AUTHORS¶
Andreas Krennmair <ak@newsbeuter.org>, for contributors see AUTHORS file.
AUTHOR¶
Andreas Krennmair <ak@newsbeuter.org>
05/07/2018 |