1. Introduction

Newsbeuter is an RSS/Atom feedreader. 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, FreeBSD or Mac OS X.

1.1. Platforms

Newsbeuter has been tested on Linux, FreeBSD and Mac OS X, and is available in
the form of pre-built packages for many popular Linux distributions. For a current
list of distributions with newsbeuter packages, consult this list on the newsbeuter website.

OpenBSD is currently unsupported, as it lacks even the most basic support for
internationalization and localization.

NetBSD is currently not supported, due to technical limitations in the iconv()
implementation.

1.2. Why "Newsbeuter"?

"Newsbeuter" is a pun on the German word "Wildbeuter", which means
"hunter-gatherer". During the stone age, people hunted and gathered their food,
and these days, they hunt and gather news and information. Credits for this
idea goes to Clifford Wolf, who submitted it to a little competition that was
started when I got aware that the original name would violate French and
European registered trademarks.

2. Installation

This chapter describes how to compile and install newsbeuter from source.

2.1. Downloading Newsbeuter

Newsbeuter is available as source package. Simply go to
http://www.newsbeuter.org/ and download the latest source package, which is
usually in the .tar.gz file format. Alternatively, you can check out the latest
development source tree from the newsbeuter Git repository (hosted on GitHub)
by running the following command on the commandline:

git clone git://github.com/akrennmair/newsbeuter.git

2.2. Dependencies

Newsbeuter depends on a number of libraries to function correctly. This table
lists these dependencies. Please be aware that the list libraries may
themselves depend on other libraries. These dependencies are not listed here.
Please also be aware that you need a recent C++ compiler. Currently, newsbeuter
has only been tested with GCC.

If you intend to modify and regenerate the filter language parser, you will also
need Coco/R for C++, which you can download from
http://www.ssw.uni-linz.ac.at/coco/. The Coco/R binary must be installed as
"cococpp" in your PATH. Debian users only need to install the package
"coco-cpp". Use the "regenerate-parser" make target to regenerate the necessary
files.

2.3. Compiling and Installing

After you’ve downloaded and installed the dependencies mentioned above, you can
start compiling and installing newsbeuter. To compile newsbeuter, simply run
"make" in the source tree. After a short time, this should complete
successfully, and you can go on with installation by running "make install". By
default, this will install the "newsbeuter" binary to the /usr/local/bin
directory. You can provide an alternative installation path using the prefix
parameter, e.g. running "make install prefix=/opt/newsbeuter" will install the
binary to the directory /opt/newsbeuter/bin.

3. 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:

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:

If you need to add URLs that have restricted access via username/password, simply
provide the username/password in the following way:

http://username:password@hostname.domain.tld/feed.rss

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:

file:///var/log/rss_eventlog.xml

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.

Table 1. Configuration Commands

Configuration Command

Argument(s)

Default

Description

Example

always-display-description

[true/false]

false

If true, then the description will always displayed even if e.g. a content:encoded tag has been found.

always-display-description true

always-download

<rssurl> [<rssurl>]

n/a

The parameters of this configuration command are one or more RSS URLs. These URLs will always get downloaded, regardless of their Last-Modified timestamp and ETag header.

This variable defines the format of entries in the article list. See the respective section in the documentation for more information on format strings (note that the semicolon should actually be a vertical bar; this is a limitation in AsciiDoc).

articlelist-format "%4i %f %D %?T?;%-17T; ?%t"

auto-reload

[yes/no]

no

If enabled, all feeds will be automatically reloaded at start up and then continuously after a certain time has passed (see reload-time).

auto-reload yes

bind-key

<key> <operation> [<dialog>]

n/a

Bind key <key> to <operation>. This means that whenever <key> is pressed, then <operation> is executed (if applicable in the current dialog). A list of available operations can be found below. Optionally, you can specify a dialog. If you specify one, the key binding will only be added to the specified dialog. Available dialogs are "all" (default if none is specified), "feedlist", "filebrowser", "help", "articlelist", "article", "tagselection", "filterselection", "urlview" and "podbeuter".

bind-key ^R reload-all

bookmark-cmd

<bookmark-command>

""

If set, then <bookmark-command> will be used as bookmarking plugin. See the documentation on bookmarking for further information.

bookmark-cmd "~/bin/delicious-bookmark.sh"

bookmark-interactive

[yes/no]

no

If set to yes, then the configured bookmark command is an interactive program.

bookmark-interactive yes

bookmark-autopilot

[yes/no]

no

If set to yes, the configured bookmark command is executed without any further input asked from user, uless the url or the title cannot be found/guessed.

bookmark-autopilot yes

browser

<browser-command>

lynx

Set the browser command to use when opening an article in the browser. If <browser-command> contains %u, it will be used as complete commandline and %u will be replaced with the URL that shall be opened.

browser "w3m %u"

cache-file

<path>

"~/.newsbeuter/cache.db"

This configuration option sets the cache file. This is especially useful if the filesystem of your home directory doesn’t support proper locking (e.g. NFS).

cache-file "/tmp/testcache.db"

cleanup-on-quit

[yes/no]

yes

If yes, then the cache gets locked and superfluous feeds and items are removed, such as feeds that can’t be found in the urls configuration file anymore.

cleanup-on-quit no

color

<element> <fgcolor> <bgcolor> [<attr> …]

n/a

Set the foreground color, background color and optional attributes for a certain element

color background white black

confirm-exit

[yes/no]

no

If set to yes, then newsbeuter will ask for confirmation whether the user really wants to quit newsbeuter.

confirm-exit yes

cookie-cache

<file>

""

Set a cookie cache. If set, then cookies will be cached (i.e. read from and written to) in this file.

cookie-cache "~/.newsbeuter/cookies.txt"

datetime-format

<date/time format>

%b %d

This format specifies the date/time format in the article list. For a detailed documentation on the allowed formats, consult the manpage of strftime(3).

datetime-format "%D, %R"

define-filter

<name> <filter>

n/a

With this command, you can predefine filters, which you can later select from a list, and which are then applied after selection. This is especially useful for filters that you need often and you don’t want to enter them every time you need them.

define-filter "all feeds with fun tag" "tags # \"fun\""

delete-read-articles-on-quit

[yes/no]

"no"

If set to "yes", then all read articles will be deleted when you quit newsbeuter.

delete-read-articles-on-quit yes

display-article-progress

[yes/no]

yes

If set to yes, then a read progress (in percent) is displayed in the article view. Otherwise, no read progress is displayed.

display-article-progress no

download-retries

<number retries>

1

How many times newsbeuter shall try to successfully download a feed before giving up. This is an option to improve the success of downloads on slow and shaky connections such as via a TOR proxy.

download-retries 4

download-full-page

[yes/no]

no

If set to yes, then for all feed items with no content but with a link, the link is downloaded and the result used as content instead. This may significantly increase the download times of "empty" feeds.

download-full-page yes

download-timeout

<seconds>

30

The number of seconds newsbeuter shall wait when downloading a feed before giving up. This is an option to improve the success of downloads on slow and shaky connections such as via a TOR proxy.

download-timeout 60

error-log

<path>

""

If set, then user errors (e.g. errors regarding defunct RSS feeds) will be logged to this file.

error-log "~/.newsbeuter/error.log"

external-url-viewer

<command>

""

If set, then "show-urls" will pipe the current article to a specific external tool instead of using the internal URL viewer. This can be used to integrate tools such as urlview.

external-url-viewer "urlview"

feed-sort-order

<sortorder>

none

If set to "firsttag", the feeds in the feed list will be sorted by their first tag in the urls file.

feed-sort-order firsttag

feedlist-format

<format>

"%4i %n %11u %t"

This variable defines the format of entries in the feed list. See the respective section in the documentation for more information on format strings.

feedlist-format " %n %4i - %11u -%> %t"

oldreader-flag-share

<flag>

""

If this is set and The Old Reader support is used, then all articles that are flagged with the specified flag are being "shared" in The Old Reader so that people that follow you can see it.

oldreader-flag-share "a"

oldreader-flag-star

<flag>

""

If this is set and The Old Reader support is used, then all articles that are flagged with the specified flag are being "starred" in The Old Reader and appear in the list of "Starred items".

oldreader-flag-star "b"

oldreader-login

<login>

""

This variable sets your The Old Reader login for The Older Reader support.

oldreader-login "your-login"

oldreader-min-items

<number>

20

This variable sets the number of articles that are loaded from The Old Reader per feed.

oldreader-min-items 100

oldreader-password

<password>

""

This variable sets your The Old Reader password for The Old Reader support.

oldreader-password "your-password"

oldreader-passwordfile

<path-to-file

""

A more secure alternative to the above, by storing your password elsewhere in your system.

oldreader-passwordfile "path-to-file"

oldreader-show-special-feeds

[yes/no]

yes

If this is set, then "special feeds" like "People you follow" (articles shared by people you follow), "Starred items" (your starred articles) and "Shared items" (your shared articles) appear in your subscription list.

oldreader-show-special-feeds "no"

feedhq-flag-share

<flag>

""

If this is set and FeedHQ support is used, then all articles that are flagged with the specified flag are being "shared" in FeedHQ so that people that follow you can see it.

feedhq-flag-share "a"

feedhq-flag-star

<flag>

""

If this is set and FeedHQ support is used, then all articles that are flagged with the specified flag are being "starred" in FeedHQ and appear in the list of "Starred items".

feedhq-flag-star "b"

feedhq-login

<login>

""

This variable sets your FeedHQ login for FeedHQ support.

feedhq-login "your-login"

feedhq-min-items

<number>

20

This variable sets the number of articles that are loaded from FeedHQ per feed.

feedhq-min-items 100

feedhq-password

<password>

""

This variable sets your FeedHQ password for FeedHQ support.

feedhq-password "your-password"

feedhq-passwordfile

<path-to-file

""

A more secure alternative to the above, by storing your password elsewhere in your system.

feedhq-passwordfile "path-to-file"

feedhq-show-special-feeds

[yes/no]

yes

If this is set, then "special feeds" like "People you follow" (articles shared by people you follow), "Starred items" (your starred articles) and "Shared items" (your shared articles) appear in your subscription list.

feedhq-show-special-feeds "no"

goto-first-unread

[yes/no]

yes

If set to yes (the default), then the first unread article will be selected whenever a feed is entered.

goto-first-unread no

goto-next-feed

[yes/no]

yes

If set to yes, then the next-unread and prev-unread keys will search in other feeds for unread articles if all articles in the current feed are read. If set to no, then the next-unread and prev-unread keys will stop in the current feed.

goto-next-feed no

highlight

<target> <regex> <fgcolor> [<bgcolor> [<attribute> …]]

n/a

With this command, you can highlight text parts in the feed list, the article list and the article view. For a detailed documentation, see the chapter on highlighting.

highlight all "newsbeuter" red

highlight-article

<filterexpr> <fgcolor> <bgcolor> [<attribute> …]

n/a

With this command, you can highlight articles in the article list if they match a filter expression. For a detailed documentation, see the chapter on highlighting.

highlight-article "author =~ \"Andreas Krennmair\"" white red bold

history-limit

<number>

100

Defines the maximum number of entries of commandline resp. search history to be saved. To disable history saving, set history-limit to 0.

history-limit 0

html-renderer

<path>

internal

If set to "internal", then the internal HTML renderer will be used. Otherwise, the specified command will be executed, the HTML to be rendered will be written to the command’s stdin, and the program’s output will be displayed. This makes it possible to use other, external programs, such as w3m, links or lynx, to render HTML.

If a downloaded article from <feed> matches <filterexpr>, then it is ignored and not presented to the user. This command is further explained in the "kill file" section below.

ignore-article "*" "title =~ \"Windows\""

ignore-mode

[download/display]

download

This configuration option defines in what way an article is ignored (see ignore-article). If set to "download", then it is ignored in the download/parsing phase (which is the default) and thus never written to the cache, if it set to "display", it is ignored when displaying articles but is kept in the cache.

ignore-mode "display"

include

<path>

n/a

With this command, you can include other files to be interpreted as configuration files. This is especially useful to separate your configuration into several files, e.g. key configuration, color configuration, …

include "~/.newsbeuter/colors"

keep-articles-days

<days>

0

If set the a number greater than 0, only articles that are were published within the last <n> days are kept, and older articles are deleted. If set to 0 (default value), this option is not active.

keep-articles-days 30

macro

<macro key> <command list>

n/a

With this command, you can define a macro key and specify a list of commands that shall be executed when the macro prefix and the macro key are pressed.

macro k open ; reload ; quit

mark-as-read-on-hover

[yes/no]

no

If set to yes, then all articles that get selected in the article list are marked as read.

mark-as-read-on-hover yes

max-download-speed

<number>

0

If set to a number great than 0, the download speed per download is set to that limit (in kB).

max-download-speed 50

max-items

<number>

0

Set the number of articles to maximally keep per feed. If the number is set to 0, then all articles are kept.

Format string that is used for formatting notifications. See the chapter on format strings for more information.

notify-format "%d new articles (%n unread articles, %f unread feeds)"

notify-program

<path>

""

If set, then the configured program will be executed if new articles arrived (through a reload) or if notify-always is true. The first parameter of the called program contains the notification message.

notify-program "~/bin/my-notifier"

notify-always

[yes/no]

no

If no, notifications will only be made when there are new feeds or articles. If yes, notifications will be made regardless.

notify-always yes

notify-screen

[yes/no]

no

If yes, then a "privacy message" will be sent to the terminal, containing a notification message about new articles. This is especially useful if you use terminal emulations such as GNU screen which implement privacy messages.

notify-screen yes

notify-xterm

[yes/no]

no

If yes, then the xterm window title will be set to a notification message about new articles.

notify-xterm yes

notify-beep

[yes/no]

no

If yes, then the speaker beep on new articles.

notify-beep yes

opml-url

<url> …

""

If the OPML online subscription mode is enabled, then the list of feeds will be taken from the OPML file found on this location. Optionally, you can specify more than one URL. All the listed OPML URLs will then be taken into account when loading the feed list.

If set to "internal", then the internal pager will be used. Otherwise, the article to be displayed will be rendered to be a temporary file and then displayed with the configured pager. If the pager path is set to an empty string, the content of the "PAGER" environment variable will be used. If the pager path contains a placeholder "%f", it will be replaced with the temporary filename.

less %f

podcast-auto-enqueue

[yes/no]

no

If yes, then all podcast URLs that are found in articles are added to the podcast download queue. See the respective section in the documentation for more information on podcast support in newsbeuter.

podcast-auto-enqueue yes

prepopulate-query-feeds

[yes/no]

no

If yes, then all query feeds are prepopulated with articles on startup.

If yes, then all feeds will be reloaded when newsbeuter starts up. This is equivalent to the -r commandline option.

refresh-on-startup yes

reload-only-visible-feeds

[yes/no]

no

If yes, then manually reloading all feeds will only reload the currently visible feeds, e.g. if a filter or a tag is set.

reload-only-visible-feeds yes

reload-time

<number>

60

The number of minutes between automatic reloads.

reload-time 120

reload-threads

<number>

1

The number of parallel reload threads that shall be started when all feeds are reloaded.

reload-threads 3

reset-unread-on-update

<url> …

n/a

With this configuration command, you can provide a list of RSS feed URLs for whose articles the unread flag will be reset if an article has been updated, i.e. its content has been changed. This is especially useful for RSS feeds where single articles are updated after publication, and you want to be notified of the updates.

reset-unread-on-update "http://blog.fefe.de/rss.xml?html"

save-path

<path>

~/

The default path where articles shall be saved to. If an invalid path is specified, the current directory is used.

save-path "~/Saved Articles"

search-highlight-colors

<fgcolor> <bgcolor> [<attribute> …]

black yellow bold

This configuration command specifies the highlighting colors when searching for text from the article view.

search-highlight-colors white black bold

show-keymap-hint

[yes/no]

yes

If no, then the keymap hints on the bottom of screen will not be displayed.

show-keymap-hint no

show-read-feeds

[yes/no]

yes

If yes, then all feeds, including those without unread articles, are listed. If no, then only feeds with one or more unread articles are list.

show-read-feeds no

show-read-articles

[yes/no]

yes

If yes, then all articles of a feed are listed in the article list. If no, then only unread articles are listed.

show-read-articles no

suppress-first-reload

[yes/no]

no

If yes, then the first automatic reload will be suppressed if auto-reload is set to yes.

suppress-first-reload yes

swap-title-and-hints

[yes/no]

no

If yes, then the title at the top of screen and keymap hints at the bottom of screen will be swapped.

swap-title-and-hints yes

text-width

<number>

0

If set to a number greater than 0, then all HTML will be rendered to this maximum line length. If set to 0, the terminal width will be used.

text-width 72

ttrss-flag-publish

<character>

""

If this is set and Tiny Tiny RSS support is used, then all articles that are flagged with the specified flag are being marked as "published" in Tiny Tiny RSS.

ttrss-flag-publish "b"

ttrss-flag-star

<character>

""

If this is set and Tiny Tiny RSS support is used, then all articles that are flagged with the specified flag are being "starred" in Tiny Tiny RSS.

ttrss-flag-star "a"

ttrss-login

<username>

""

Sets the username for use with Tiny Tiny RSS.

ttrss-login "admin"

ttrss-mode

[multi/single]

multi

Configures the mode in which Tiny Tiny RSS is used. In single-user mode, login and password are used for HTTP authentication, while in multi-user mode, they are used for authenticating with Tiny Tiny RSS.

ttrss-mode "single"

ttrss-password

<password>

""

Configures the password for use with Tiny Tiny RSS.

ttrss-password "mypassword"

ttrss-passwordfile

<path-to-file

""

A more secure alternative to the above, by storing your password elsewhere in your system.

ttrss-passwordfile "path-to-file"

ttrss-url

<url>

""

Configures the URL where the Tiny Tiny RSS installation you want to use resides.

ttrss-url "http://example.com/ttrss/"

unbind-key

<key> [<dialog>]

n/a

Unbind key <key>. This means that no operation is called when <key> is pressed. Optionally, you can specify a dialog (for a list of available dialogs, see "bind-key" above). If you specify one, the key binding will only be unbound for the specified dialog.

unbind-key R

urls-source

<source>

"local"

This configuration command sets the source where URLs shall be retrieved from. By default, this is ~/.newsbeuter/urls. Alternatively, you can set it to "opml", which enables newsbeuter’s OPML online subscription mode, to "ttrss" which enables newsbeuter’s Tiny Tiny RSS support, to "oldreader", which enables newsbeuter’s The Old Reader support, to "newsblur", which enables NewsBlur support, or "feedhq" for FeedHQ support.

urls-source "oldreader"

use-proxy

[yes/no]

no

If yes, then the configured proxy will be used for downloading the RSS feeds.

use-proxy yes

user-agent

<user agent string>

""

If set to a non-zero-length string, this value will be used as HTTP User-Agent header for all HTTP requests.

user-agent "Lynx/2.8.5rel.1 libwww-FM/2.14"

Table 2. Available Operations

Operation

Default key

Description

open

ENTER

Open the currently selected feed or article.

quit

q

Quit the program or return to the previous dialog (depending on the context).

reload

r

Reload the currently selected feed.

reload-all

R

Reload all feeds.

mark-feed-read

A

Mark all articles in the currently selected feed read.

mark-all-feeds-read

C

Mark articles in all feeds read.

save

s

Save the currently selected article to a file.

next-unread

n

Jump to the next unread article.

prev-unread

p

Jump to the previous unread article.

next

J

Jump to next article.

prev

K

Jump to previous article.

random-unread

^K

Jump to a random unread article.

open-in-browser

o

Opens the URL associated with the current article.

open-in-browser-and-mark-read

O

Opens the URL associated with the current article and marks the article as read.

help

?

Runs the help screen.

toggle-source-view

^U

Toggles between the HTML view and the source view in the article view.

toggle-article-read

N

Toggle the read flag for the currently selected article.

toggle-show-read-feeds

l

Toggle whether read feeds should be shown in the feed list.

show-urls

u

Show all URLs in the article in a list (similar to urlview).

clear-tag

^T

Clear current tag.

set-tag

t

Select tag.

open-search

/

Opens the search dialog. When a search is done in the article list, then the search operation only applies to the articles of the current feed, otherwise to all articles.

goto-url

#

Open the URL dialog and then opens specified URL.

enqueue

e

Add the podcast download URL of the current article (if any is found) to the podcast download queue (see the respective section in the documentation for more information on podcast support).

edit-urls

E

Edit the list of subscribed URLs. newsbeuter will start the editor configured through the $VISUAL environment variable (if unset, $EDITOR is used; fallback

reload-urls

^R

Reload the URLs configuration file.

redraw

^L

Redraw the screen.

cmdline

<colon>

Open the command line.

set-filter

F

Set a filter.

select-filter

f

Select a predefined filter.

clear-filter

^F

Clear currently set filter.

bookmark

^B

Bookmark currently selected article or URL.

edit-flags

^E

Edit the flags of the currently selected article.

next-unread-feed

^N

Go to the next feed with unread articles. This only works from the article list.

prev-unread-feed

^P

Go to the previous feed with unread articles. This only works from the article list.

Keys, as used in the bind-key configuration command, use a special syntax.
Lowercase keys, uppercase keys and special characters are written literally.
The Enter key is written as "ENTER", while the Esc key is written as "ESC". The
function keys F1 to F12 are written as "F1" to "F12". The Space key is written
as "SPACE". Key combinations with the Ctrl key, such as Ctrl-R, are written as
^R. Please be aware that all Ctrl-related key combinations need to be written
in uppercase. The following identifiers for keys are supported:

3.2. Configuring Colors

This means that if you configure colors for a certain element, you need to provide
a foreground color and a background color as a minimum. The following colors are
supported:

black

red

green

yellow

blue

magenta

cyan

white

default

color<n>, e.g. color123

The "default" color means that the terminal’s default color will be used. The
"color<n>" color name can be used if your terminal support 256 colors (e.g.
gnome-terminal, xterm with $TERM set to xterm-256color). Newsbeuter contains
support for 256 color terminals since version 2.1. For a complete chart of
colors and their corresponding numbers, please see
http://www.calmar.ws/vim/256-xterm-24bit-rgb-color-chart.html.

Optionally, you can also add one or more attributes. The following attributes are
supported:

3.3. Migrating from other RSS Feed Readers

It is very likely that you have used other RSS feed readers before. In this
case, it is practical to migrate the previous configuration to newsbeuter. The
vast amount of RSS feed readers allows the export of subscriptions via OPML
files. OPML is an XML file format that was designed to save outlines, and has
found its primary use in the import and export of feed subscriptions between
different RSS feed readers.

The best thing to start with is to export your subscriptions from the old
reader. Usually, RSS feed readers have appropriate menu items available to do
so.

Snownews provides a script to convert your current subscription file into an
OPML file:

snow2opml > ~/blogroll.opml

This command creates from your Snownews configuration a file blogroll.opml in
your home directory. To export the subscription list from raggle, the
following command is necessary:

raggle --export-opml ~/blogroll.opml

When you have exported the subscriptions from your old RSS feed reader, you can
import them into newsbeuter:

newsbeuter -i ~/blogroll.opml

Don’t worry, newsbeuter won’t destroy your existing configuration, or add
subscriptions more than once: every URL that is added to the subscription list
is checked before whether it is already in the list, and is only added if not.
This makes it possible to merge several OPML files into your subscription list.

If your old RSS feed reader was able to structure your subscriptions in
hierarchies, and reflected this structure in the exported OPML file, newsbeuter
doesn’t throw away this information (although it doesn’t support hierarchies), but
generates tags from it. Tags are newsbeuter’s way of organizing subscriptions
in a non-hierarchical way. More information on the use of tags can be found below.

Subscriptions found in the folder "Private" will be tagged with "Private",
subscriptions in the folder "International" will be tagged with "News" and
"News/International", subscriptions in the folder "Erlang" will be tagged ith
"IT", "IT/Programming" and "IT/Programming/Erlang", and so on. This means that
when you select the tag "Programming" in newsbeuter, you will see all
subscriptions that were in the "Programming" folder or one of its subfolders
before. This means that you will lose virtually nothing of your previously
configured structure.

4. Advanced Features

4.1. 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:

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

4.2. Scripts and Filters (Snownews Extensions)

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:

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:

4.3. Bookmarking

Since version 0.7, newsbeuter contains a plugin-based bookmarking system. When a user bookmarks a link (possible
in the article list, in the article view, and in the URL view), he is asked for the URL to bookmark (already
preset with the URL of the current selection), the bookmark title (in most cases preset with the
title of the current selection) and the bookmark description. After the question for the description, an
external program, configured via the configuration command "bookmark-cmd", is executed with 3 commandline
parameters. The plugin itself implements the actual bookmark saving (e.g. writing the bookmark to an
external file, or storing it to a del.icio.us account). When everything went OK, the plugin simply exits.
In case something goes wrong while saving the bookmark, it writes out an error message as a single line.
This error message is then presented to the user from within newsbeuter.

Newsbeuter comes with an example plugin, which implements a simple tab-separated bookmark file. This
example can be found in the "doc" subdirectory.

4.4. 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:

Table 3. Available Commandline Commands

Command

Syntax

Description

Example

quit

quit

Quit newsbeuter.

quit

save

save <filename>

Save the currently select article to disk. This works in the article list and in the article view.

save ~/important.txt

set

set <variable>[=<value>|&|!]

Set configuration variable <variable> to <value>. If no value is specified, the current value is printed out. Specifying a ! after the name of boolean configuration variables toggles their values, a & directly after the name of a configuration variable of any type resets its value to the documented default value.

set reload-time=15

tag

tag <tagname>

Only display feeds with the tag <tagname>.

tag news

goto

goto <case-insensitive substring>

Go to the next feed whose name contains the case-insensitive substring.

goto foo

source

source <filename> […]

Load the specified configuration files. This allows it to load alternative configuration files or reload already loaded configuration files on-the-fly from the filesystem.

source ~/.newsbeuter/colors

dumpconfig

dumpconfig <filename>

Save current internal state of configuration to file, so that it can be instantly reused as configuration file.

dumpconfig ~/.newsbeuter/config.saved

dumpform

dumpform

Dump current dialog to text file. This is meant for debugging purposes only.

dumpform

n/a

<number>

Jump to the entry with the index <number> (usually seen at the left side of the list). This currently works for the feed list and the article list.

30

4.5. Filter Language

Newsbeuter provides a powerful filter language that enables the user to
filter the content of many dialogs, such as the feed list or the article
list. The basic concept is that every feed and every article has a
number of attributes which can then be compared with user-supplied
values, and these comparisons and be logically AND’ed, OR’ed and
grouped.

Examples for simple filter expressions are:

unread_count > 0
rssurl =~ "^https:"
age between 0:10

Logically connecting and grouping such expressions looks like in the
following examples:

The possibilities for combining such queries is endless, sky (actually:
the available memory) is the limit.

To filter your feeds, press "F" in the feed list, enter your filter expression,
and press enter. To clear the filter, press Ctrl-F. To filter the articles in the article list,
press "F", enter your expression, and press enter. Clearing the filter works the same as before.
Be aware that only certain attributes work in both dialogs. The table below lists all available
attributes and their context, i.e. an attribute that belongs to a feed can only be matched
in the feed list, while an attribute that belongs to an article can only be matched in the
article list.

Table 4. Available Comparison Operators

Operator

Meaning

=

test for equality ("==" works, too)

!=

test for inequality; logical negation of = operator

=~

test whether regular expression matches

!~

logical negation of the =~ operator

<

less than

>

greater than

⇐

less than or equal

>=

greater than or equal

between

within a range of integer values, where the two integer values are separated by a colon (see above for an example)

#

contains; this operator matches if a word is contained in a list of space-separated words (useful for matching tags, see below)

!#

contains not; the negation of the # operator

Table 5. Available Attributes

Attribute

Context

Meaning

title

article

article title

link

article

article link

author

article

article author

content

article

article body

date

article

publication date of the article

guid

article

a unique identifier of the article

unread

article

indicates whether the article has been read

enclosure_url

article

the URL of a possible enclosure (e.g. podcast file)

enclosure_type

article

the MIME type of the enclosure URL

flags

article

The set of flags of the article

age

article

Age of an article (in days)

articleindex

article

Index of an article in an article list

feedtitle

feed, article

title of the feed

description

feed, article

feed description

feedlink

feed, article

link to the feed

feeddate

feed, article

publication date of the feed

rssurl

feed, article

RSS URL of the feed

unread_count

feed, article

number of unread articles in the feed

total_count

feed, article

total number of articles in the feed

tags

feed, article

all tags that are associated with the feed

feedindex

feed, article

Index of a feed in the feed list

Note that it’s also possible to filter for feed attributes when you query for
article attributes. This is because every article is internally linked to the
feed from which it was downloaded.

4.6. Killfiles

Sometimes, a user is confronted with certain content he doesn’t want to read,
e.g. on topics the user is not interested in or articles from certain people he
doesn’t want to read. In Usenet, such functionality within software is
traditionally called a "killfile", i.e. based on the content of this "killfile",
articles that match certain conditions do not get displayed and are not presented
to the user at all.

In newsbeuter, such a "killfile" can be implemented on a per-article basis via
the configuration file. The most important configuration command for this
is "ignore-article":

The basic format is that the user specifies an RSS feed for which the ignore
shall be applied ("*" matches all RSS feeds), and then a filter expression (see
previous section). If newsbeuter hits an article in the specified RSS feed that
matches the specified filter expression, then this article is ignored and never
presented to the user. The configuration itself can contain as many
ignore-article commands as desired.

Since newsbeuter 2.2, you can specify the way an article is ignored. There are
two ways available:

During download: articles are ignored when a feed is downloaded and parsed,
and thus won’t be written to the local cache.

During display: articles are downloaded and written to the local cache, but
are ignored when a feed is displayed.

Both modes have their advantages and disadvantages: while the download ignore
mode saves some storage, you cannot simply "undo" the ignore by removing it
from the configuration file: if an ignored article has already vanished from a
feed, it won’t reappear. On the other hand, the display ignore mode requires
some more space, but has the advantage that an ignore can be "undone" by
removing the ignore-article configuration command from the configuration.

The default ignore mode is "download". You can set the ignore mode in the
configuration file:

ignore-mode "display"

4.7. Query Feeds

Query feeds are a mechanism of newsbeuter to define custom "meta feeds" by using
newsbeuter’s built-in filter language. A query feed is a feed that is aggregated
from all currently downloaded articles of all feeds. To narrow down the set of
articles, the user has to specify a filter. Only articles that match this filter
are added to the query feed. A query feed is updated whenever it is entered in
the feed list. When you change the unread flag of an article, this is reflected
in the feed where the article was originally fetched.

To define a query feed, the user has to add a line to the file
~/.newsbeuter/urls in the following format:

query:<name of feed>:<filter expression> [<tag> ...]

The "query:" in the beginning tells newsbeuter that it’s a query feed, "<name of
feed>" specifies the name under which the query feed shall be displayed in the
feed list, and "<filter expression>" is the filter expression that shall be
used. Like every other feed, a query feed can be tagged to organize it like
a regular feed.

A good example for the user of this feature is a query feed that contains all
unread articles:

"query:Unread Articles:unread = \"yes\""

Note the quotes that are necessary around the complete query "URL" and the
backslashes that are necessary the escape the quotes in the filter expression.

If you want to combine several feeds to one single feed, a good solution is to
tag the feeds that you want to combine with one certain tag, and then create a
query feed that only displays articles from feeds with that certain tag:

Basically, the possibility of what can be realized with query feeds is only
limited by what can be queried from articles and feeds with the filter language
and by your creativity.

4.8. Google Reader Support

Since version 2.2, newsbeuter contained support for Google Reader. After Google
Reader was discontinued by Google, Google Reader support was subsequently
removed from newsbeuter and replaced with support for alternatives such as The
Old Reader, NewsBlur and FeedHQ.

4.9. The Old Reader Support

The Old Reader is a successor to Google Reader.
Newsbeuter provides functionality to use The Old Reader as its
backend: people can use The Old Reader to manage their subscriptions, and in
addition, use newsbeuter to download and read articles. Newsbeuter will keep
the information which articles have already been read synchronized with The Old
Reader, so that users usually won’t see articles more than once. In addition, it
will only ever download unread articles from The Old Reader.

In order to use The Old Reader support, you first need to configure the proper URL source:

urls-source "oldreader"

In addition, newsbeuter needs to know your The Old Reader username and password
so that it can authenticate with The Old Reader:

After setting these configuration values, you can start newsbeuter, it will
authenticate with The Old Reader and download your subscription list. If you use
"folders" in The Old Reader to organize your feeds, newsbeuter will regard them
and make them available via its "tags" capability: each feed is tagged with the
name of the folder in which it resides.

When you mark single items or complete feeds as read, newsbeuter will
synchronize this information directly to The Old Reader. This, of course,
includes opening articles. Toggling read articles back to "unread" is also
communicated to The Old Reader.

In addition, The Old Reader provides the ability to "star" and to "share"
articles. Starred articles are basically bookmarks, while shared articles are
shown to people that follow your The Old Reader account. Newsbeuter allows the
use of this feature by mapping its powerful "flags" to the "star"/"unstar"
resp. "share"/"unshare" operations.

In order to use this mapping, all you need to do is to configure the flags
that shall be used:

oldreader-flag-share "a"
oldreader-flag-star "b"

After that, use these flags when you edit flags for an article, and these
articles will be starred resp. shared.

By default, newsbeuter also shows The Old Reader "special feeds":
- People you follow: articles shared by people that you follow.
- Starred items: articles that you starred.
- Shared items: articles that you shared.

You can disable these feeds by setting the following configuration variable:

oldreader-show-special-feeds no

4.10. NewsBlur Support

Newsbeuter also supports NewsBlur, another alternative to Google Reader.
Configuration basically works the same as with The Old Reader.

When you start newsbeuter, it will download the feeds that you configured
in NewsBlur. Please take a closer look at the configuration commands for what
you can configure in newsbeuter regarding NewsBlur.

4.11. FeedHQ Support

Newsbeuter also supports FeedHQ, another alternative to Google Reader.
Configuration basically works the same as with The Old Reader.

First, set your urls-source:

urls-source "feedhq"

Then, configure your FeedHQ credentials:

feedhq-login "your-feedhq-account"
feedhq-password "your-password"

When you start newsbeuter, it will download the feeds that you configured
in FeedHQ. Please take a closer look at the configuration commands for what
you can configure in newsbeuter regarding FeedHQ.

4.12. Bloglines Synchronization

Up to and including version 2.3, newsbeuter contained support for synchronization
with Bloglines. On October 1, 2010, Bloglines was discontinued, and newsbeuter’s
support for Bloglines was subsequently removed.

4.13. Tiny Tiny RSS Synchronization

Since version 2.5, newsbeuter can be used to synchronize with Tiny Tiny RSS
installations. Tiny Tiny RSS is a web-based and (optionally) multi-user feed
reader. By providing the ability to use Tiny Tiny RSS as its backend, it’s
possible for users to manage their subscriptions centrally within Tiny Tiny RSS
while reading them wherever they are using newsbeuter.

If you want to use Tiny Tiny RSS support, don’t forget to activate the external
API support in your preferences.

To use Tiny Tiny RSS support, you need to configure a few things. First of all,
newsbeuter needs to know that you want to use Tiny Tiny RSS and which
installation exactly:

With these settings, newsbeuter should be able to connect to Tiny Tiny RSS and
download your subscribed feeds. Articles or even complete feeds that you marked
as read are synchronized directly to Tiny Tiny RSS.

Tiny Tiny RSS provides the ability to "star" and to "publish" articles. Starred
articles are basically bookmarks, while published articles can be retrieved via
a pubic RSS feed. Newsbeuter allows the use of these features by mapping its
flags to the "star" and "publish" operations.

In order to use this mapping, you need to configure the flags that shall be used:

ttrss-flag-star "s"
ttrss-flag-publish "p"

After that, use these flags when you edit flags for an article, and these articles
will be starred resp. published.

4.14. OPML Online Subscription Mode

The OPML online subscription mode works similar to the Google Reader
synchronization mode, except that no information about read articles is
synchronized back. When enabled, all feeds that are listed in the feed list
will be taken from one or more OPML files that are downloaded from a freely
configurable URL.

To enable this mode, the following configuration needs to be done:

urls-source "opml"
opml-url "<opml url>" ["<opml url>" ...]

"opml" must be specified as source for the feed URLs, and the URLs of the OPML
file needs to be specified, too. As with Google Reader synchronization mode, the offline
mode via "newsbeuter -o" also works with OPML online subscription mode.

4.15. Flagging Articles

To support custom categorization of articles by the user, it is possible to
flag an article. A valid flag is any character from A to Z and from a to
z. Every article can be flagged with up to 52 different flags, i.e. every
letter from the Roman alphabet in upper and lower case. Flagging is easy: just
select an article in the article list, or enter the article view, and press ^E.
This will start the flag editor. By pressing enter, the new flags are saved.
You can cancel by pressing the ESC key.

The flags of an article can be used in every filter expression. The flags of an
article are always ordered, and when new flags are added, ordering is
immediately restored. This behaviour can also be relied upon when querying
articles via the filter language.

If an article contains one or more flags, it is marked with an "!" in the
article list. In the article view, all flags (if available) are listed.

4.16. Macro Support

In newsbeuter, it’s possible to define macros to execute more than one command
at once. A macro is configured using the "macro" configuration command. The
first parameter to "macro" is the key, all parameters afterwards are operations
(as listed in the "Available Operations" table above), optionally with
parameters on their own, separated by the ";" character. Here’s a simple
example:

When the user presses the macro prefix ("," by default) and then the "k" key,
the three operations "open", "reload" and "quit" will be executed subsequently.

It is also possible to modify configuration variables within macros, which can
e.g. be used to temporarily modify the browser configuration variable to do
something else, such as running an image viewer from the URLs view:

macro i set browser "feh %u"; open ; set browser "elinks %u"

You can even use this feature to enqueue any of the URLs from the URLs view to
podbeuter’s download queue:

4.17. Commandline Commands

Newsbeuter comes with a -x option that indicates that commands added as arguments
to the command line shall be executed. Currently, the following commands are
available:

reload: this option reloads all feeds, and quits newsbeuter without printing any output.
This is useful if a user wants to periodically reload all feeds without always having
a running newsbeuter instance, e.g. from cron.

print-unread: this option prints the number of unread articles and quits newsbeuter.
This is useful for users who want to integrate this number into some kind of monitoring
system.

4.18. Format Strings

Newsbeuter contains a powerful format string system to make it possible for the
user to configure the format of various aspects of the application, such as
the format of entries in the feed list or in the article list.

Format strings are similar to those that are found in the "printf" function in
the C programming language. A format sequence begins with the % character,
followed by optional alignment indication: positive numbers indicate that the
text that is inserted for the sequence shall be padded right to a total width
that is specified by the number, while negative number specify left padding.
Followed by the padding indication comes the actual sequence identifier, which
is usually a single letter.

In addition, newsbeuter provides other, more powerful sequences, such as
"%>[char]", which indicates that the text right to the sequence will be aligned
right on the screen, and characters between the text on the left and the text
on the right will be filled by "[char]". Another powerful format is the
conditional sequence, "%?[char]?[format 1]&[format 2]?": if the text of the
sequence identifier "[char]" is non-empty, then "[format 1]" will be evaluated
and inserted, otherwise "[format 2]" will be evaluated and inserted. The "&" and
"[format 2]" are optional, i.e. if the identifier’s text is empty, then an
empty string will be inserted.

The following tables show what sequence identifiers are available for which
format:

Table 6. Available Identifiers for feedlist-format

Identifier

Meaning

d

Feed description

i

Feed index

l

Feed link

L

Feed RSS URL

n

"unread" flag field

S

download status

t

Feed title

T

First tag of a feed in the URLs file

u

"unread/total" field

U

"unread" field

c

"total" field

While a reload-all operation is running, the download status indicates the
download status of a feed, which can be "to be downloaded" (indicated by "_"),
"currently downloading" (indicated by "."), successfully downloaded (indicated
by " ") and "download error" (indicated by "x").

Table 7. Available Identifiers for articlelist-format

Identifier

Meaning

a

Article author

D

Publication date

f

Article flags

i

Article index

t

Article title

T

If the article list displays articles from different feeds, then this identifier contains the title of the feed to which the article belongs.

L

Article length

Table 8. Available Identifiers for notify-format

Identifier

Meaning

n

Number of unread articles

f

Number of unread feeds

d

Number of new unread articles (i.e. that were added through the last reload)

D

Number of new unread feeds (i.e. that were added through the last reload)

Dialog Titles

Starting with newsbeuter 2.0, it is now officially supported to customize
the title format of all available dialogs. Here is a list of dialogs with their
respective title format configuration variables, and a list of available formats
and their meaning. Please note taht the title formats are localized, so if you
work on a different locale that is supported by newsbeuter, the actually displayed
title text may vary unless you customize it.

Table 9. Dialog Title Formats

Dialog

Configuration Variable

Default Value

Feed List

feedlist-title-format

%N %V - Your feeds (%u unread, %t total)%?T? - tag ‘%T’&?

Article List

articlelist-title-format

%N %V - Articles in feed %T (%u unread, %t total) - %U

Search Result

searchresult-title-format

%N %V - Search result (%u unread, %t total)

File Browser

filebrowser-title-format

%N %V - %?O?Open File&Save File? - %f

Help

help-title-format

%N %V - Help

Select Tag Dialog

selecttag-title-format

%N %V - Select Tag

Select Filter Dialog

selectfilter-title-format

%N %V - Select Filter

Article View

itemview-title-format

%N %V - Article %T (%u unread, %t total)

URL View

urlview-title-format

%N %V - URLs

Dialog List

dialogs-title-format

%N %V - Dialogs

Table 10. Common Title Format Identifiers

Identifier

Meaning

N

Name of the program, i.e. "newsbeuter"

V

Program version

u

Number of unread articles (if applicable)

t

Number of total articles (if applicable)

Table 11. Feed List Title Format Identifiers

Identifier

Meaning

T

Currently selected tag (empty if none selected)

Table 12. Article List Title Format Identifiers

Identifier

Meaning

T

Feed title

U

Feed URL

Table 13. File Browser Title Format Identifiers

Identifier

Meaning

f

Filename

O

Non-empty if file browser is in open mode, empty if in save mode

Table 14. Article View Title Format Identifiers

Identifier

Meaning

T

Article title

4.19. Highlighting Text

Since version 1.0, newsbeuter supports the highlighting of text in the feed
list, the article list and the article view, using regular expressions to
describe patterns to be highlighted. The command syntax goes like this:

highlight <target> <regex> <fgcolor> [<bgcolor> [<attribute> ...]]

Valid values for <target> are "feedlist", "articlelist", "article" and "all".
When specifying "all", the matching will be done in all three views. The
<regex> must be regular expression, which will be matched case-insensitive
against the text. <fgcolor> and <bgcolor> specify the foreground color resp.
the background color of the matches. You can also specify 0 or more attributes.
You can find a list of valid colors and attributes in the "Configuring Colors"
section.

Highlighting Articles in the Article List

In addition to generally highlighting text, there is also a specific way to
highlight articles in the article list based on whether they match a certain
filter expression. This means that you can highlight items in the article list
based on their content. This is done using the "highlight-article" configuration
command.

The syntax is similar to the "highlight" configuration command, with the difference
that there’s no need to specify a target (since it only applies in the article list),
and instead of a regular expression, a filter expression is used. After the filter
expression, the colors and attributes are specified in the same way.

Example:

highlight-article "author =~ \"Andreas Krennmair\"" white red bold

4.20. Advanced Dialog Management

Since version 2.0, newsbeuter supports an advanced concept of dialogs.
Previously, all dialogs (feed list, article list, article view) were internally
laid out as a pure stack. In 2.0, this changed: all dialogs are managed in a
list, and the user can jump to another, previously opened dialog from
everywhere. This allows a user to open more than one article list, more than one
article view, etc., and switch between them without closing them.

The main dialog for this feature can be reached by pressing the "v" key. This
opens the list of open dialogs. From there, the user can switch to another
dialog by selecting the appropriate entry and pressing "ENTER", or can close
open dialogs by selecting them and pressing Ctrl-X.

4.21. XDG Base Directory Support

If these directories exist or the environment variables $XDG_CONFIG_HOME and
$XDG_DATA_HOME are set, newsbeuter will use these directories, otherwise it
will default to ~/.newsbeuter as its configuration directory.

4.22. Podcast Support

A podcast is a media file distributed over the internet using syndication feeds
such as RSS, for later playback on portable players or computers. Newsbeuter
contains support for downloading and saving podcasts. This support differs a bit
from other podcast aggregators or "podcatchers" in how it is done.

Podcast content is transported in RSS feeds via special tags called
"enclosures". Newsbeuter recognizes these enclosures and stores the relevant
information for every podcast item it finds in an RSS feed. Since version 2.0,
it also recognizes and handles the Yahoo Media RSS extensions. What the user
then can do is to add the podcast download URL to a download queue.
Alternatively, newsbeuter can be configured to automatically do that. This
queue is stored in the file $HOME/.newsbeuter/queue.

The user can then use the download manager "podbeuter" to download these files
to a directory on the local filesystem. Podbeuter comes with the newsbeuter
package, and features a look and feel very close to the one of newsbeuter. It
also shares the same configuration file.

Podcasts that have been downloaded but haven’t been played yet remain in the
queue but are marked as downloaded. You can remove them by purging them from
the queue with the P key. After you’ve played a file and close podbeuter, it
will be removed from the queue. The downloaded file remains on the
filesystem.

Table 15. Podbeuter Configuration Commands

Configuration Command

Argument(s)

Default

Description

Example

download-path

<path>

~/

Specifies the directory where podbeuter shall download the files to. Optionally, the placeholders "%n" (for the podcast feed’s name) and "%h" (for the podcast feed’s hostname) can be used to place downloads in a directory structure.

download-path "~/Downloads/%h/%n"

max-downloads

<number>

1

Specifies the maximum number of parallel downloads when automatic download is enabled.

max-downloads 3

player

<player command>

""

Specifies the player that shall be used for playback of downloaded files.

player "mp3blaster"

Table 16. Available Operations in Podbeuter

Operation

Default key

Description

quit

q

Quit the program.

pb-download

d

Download the currently selected URL.

pb-cancel

c

Cancel the currently selected download.

pb-play

p

Start player with currently selected download.

pb-delete

D

Delete the currently selected URL from the queue.

pb-purge

P

Remove all finished and deleted downloads from the queue and load URLs that were newly added to the queue.

pb-toggle-download-all

a

Toggle the "automatic download" feature where all queued URLs are downloaded one after the other. The "max-downloads" configuration option controls how many downloads are done in parallel.

pb-increase-max-dls

+

Increase the "max-downloads" option by 1.

pb-decrease-max-dls

-

Decrease the "max-downloads" option by 1. If the option is already 1, no further decrease is possible.

A usual "use case" is to configure newsbeuter to automatically enqueue newly
found podcast download URLs. Then, the user reloads the podcast RSS feeds in
newsbeuter, and after that, he/she uses podbeuter to view the current queue, and
either selectively download certain files or automatically download them all
together by pressing "a" within podbeuter.

4.23. Using SQLite Triggers with newsbeuter

SQLite, the db used by newsbeuter, supports triggers. These are small
snippets of SQL that get executed inside the database by the database
engine. They’re stored inside the db and the normal user (including
newsbeuter itself) doesn’t see them. Just the db seems to do some magic:
Like changing some values when you change another value.

So what is this good for when looking at newsbeuter? Well first of it’s a
hack. The real answer should be to use application logic (do it inside
newsbeuter, not in the db). So: Don’t use this, unless you know, what you’re
doing, and unless you have some sort of backup.

Example

So after the "don’t use it" you still want to know, what one can do? So here’s an example.

Suppose you have a strange feed where the articles become "new" by just
changing their subject, and nothing else changes. The body is just empty, and
the URL keeps the same. This feed really exists. It’s the "updated software rss
feed" of some major company and the title just contains the name of the driver
and version number. And the URL points to the download page. newsbeuter
considers articles only as new, when they have a new UniqueID (this is good).
So those articles are never marked as new (unread) ever again.

So what can we do? We do some magic: We let the db test if newsbeuter
changes the subject and then let itself mark the article again as unread.

You need the sqlite3 command line tool (available via apt-get install sqlite3 on Debian) or some other tool to do direct sql on the sqlite database.

That’s it. newsbeuter (well, its db) now marks articles as unread when their
title changes. And nicely enough this works all inside newsbeuter, no need to
restart it so that it rereads the cache, that magically modifies itself. It
just works.

5. Feedback

If you want to tell us something related to newsbeuter, don’t hesitate to send
an email: ak@newsbeuter.org

Alternatively, you can reach the newsbeuter developers on IRC: channel
#newsbeuter on irc.freenode.net.

6. License

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.