The Newsboat RSS Feedreader
===========================

Introduction
------------
Newsboat 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.  Newsboat is designed to be used on text terminals on Unix or 
Unix-like systems such as GNU/Linux, FreeBSD or macOS.

Platforms
~~~~~~~~~

Newsboat has been tested on Linux (with glibc and musl-libc), FreeBSD and macOS.

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

Why "Newsboat"?
~~~~~~~~~~~~~~~
"Newsboat" is a play on the name of its ancestor, "Newsbeuter". They're spelled
quite differently, but sound similar. ("Newsbeuter" is a pun on German word
"wildbeuter"; "newsboat" is an English word.)

Newsboats were the vessels that collected and delivered news shuffling between
boats in the port. Newsboat the program will collect the news for you, just
like its namesakes did back in the day.

Installation
------------
This chapter describes how to compile and install newsboat from source.

Downloading Newsboat
~~~~~~~~~~~~~~~~~~~~~~

Newsboat is available as source package. Simply go to
https://newsboat.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 newsboat Git repository 
by running the following command on the commandline:

	git clone git://github.com/newsboat/newsboat.git

Dependencies
~~~~~~~~~~~~
Newsboat 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.

- GCC 4.9 or newer, or Clang 3.6 or newer
- http://www.clifford.at/stfl/[STFL (version 0.21 or newer)]
- http://www.sqlite.org/download.html[SQLite3 (version 3.5 or newer)]
- http://curl.haxx.se/download.html[libcurl (version 7.18.0 or newer)]
- ftp://ftp.gnu.org/gnu/gettext/[GNU gettext (on systems that don't provide
  gettext in the libc)]
- http://pkg-config.freedesktop.org/wiki/[pkg-config]
- http://xmlsoft.org/downloads.html[libxml2]
- https://github.com/json-c/json-c/wiki[json-c (version 0.11 or newer)]

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.


Compiling and Installing
~~~~~~~~~~~~~~~~~~~~~~~~
After you've downloaded and installed the dependencies mentioned above, you can
start compiling and installing newsboat. To compile newsboat, 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 `newsboat` 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/newsboat` will install the
binary to the directory '/opt/newsboat/bin'.


First Steps
-----------

include::chapter-firststeps.txt[]



.Configuration Commands
[frame="all", grid="all", format="dsv", separator="\|\||\n", options="header", cols="10,15,15l,40,20l"]
|======================================================================================================
Configuration Command||Argument(s)||Default||Description||Example
include::configcommands-linked.dsv[]
|======================================================================================================

.[[available-operations,Available Operations]]<<available-operations>>
[frame="all", grid="all", format="dsv", separator="\|\||\n", options="header", cols="20,20,60"]
|=========================================================================
Operation||Default key||Description
include::keycmds-linked.dsv[]
|=========================================================================

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:

- `ENTER` (Enter key)
- `BACKSPACE` (backspace key)
- `LEFT` (left cursor)
- `RIGHT` (right cursor)
- `UP` (up cursor)
- `PPAGE` (page up cursor)
- `NPAGE` (page down cursor)
- `DOWN` (down cursor)
- `ESC` (Esc key)

The "Tab" key can't be bound due to technical limitations of STFL.

Example Configuration
~~~~~~~~~~~~~~~~~~~~~

	# a comment
	max-items        100 # such comments are possible, too
	browser          links
	show-read-feeds  no

	unbind-key       R
	bind-key         ^R    reload-all

Configuring Colors
~~~~~~~~~~~~~~~~~~

It is possible to configure custom color settings in newsboat. The basic configuration 
syntax is:

	color <element> <foreground color> <background color> [<attribute> ...]

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 (where `<n>` is a decimal number *not* starting with zero)
can be used if your terminal support 256 colors (e.g. `gnome-terminal`, `xterm`
with `$TERM` set to `xterm-256color`). Newsboat 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:

- `standout`
- `underline`
- `reverse`
- `blink`
- `dim`
- `bold`
- `protect`
- `invis`

Currently, the following elements are supported:

- `listnormal`: a normal list item
- `listfocus`: the currently selected list item
- `listnormal_unread`: an unread list item
- `listfocus_unread`: the currently selected and unread list item
- `info`: the info bars on top and bottom
- `background`: the application background
- `article`: the article text

The default color configuration of newsboat looks like this:

	color background          white   black
	color listnormal          white   black
	color listfocus           yellow  blue   bold
	color listnormal_unread   magenta black
	color listfocus_unread    magenta blue   bold
	color info                yellow  blue   bold
	color article             white   black


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

Newsbeuter (automatic migration)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Newsboat is a fork of Newsbeuter, so the migration from the latter is partially
automated. Simple enough configurations will be transferred without any user
intervention, while more complicated ones might require a little tweaking
afterwards.

To prevent data loss, please check the results before deleting your old
configuration. Pay extra attention to files that you <<include,`include`>> in your
configuration--you'd probably want to manually copy them over to Newsboat
directories, and possibly update the include paths.

Migration from Newsbeuter is attempted on startup if the following conditions
are met:

* none of `-u`, `-c`, `-C` options were specified; and

* the urls file doesn't exist (neither '~/.newsboat/urls' nor
  '$XDG_CONFIG_DIR/newsboat/urls').

Newsboat first tries to migrate an XDG configuration, and if that fails, it
tries the dotdir one. If that fails as well, Newsboat proceeds with the startup
as usual.

XDG migration checks that:

* '$XDG_CONFIG_DIR/newsbeuter/' is readable and executable; and

* neither '$XDG_CONFIG_DIR/newsboat/' nor '$XDG_DATA_DIR/newsboat/' exist.

If both conditions are met, Newsboat tries to create its XDG dirs (aborting the
migration if that fails), then copies the following files: 'urls' and 'config' from
config dir; 'cache.db', 'queue', 'history.search', 'history.cmdline' from data dir.

Dotdir migration checks that '\~/.newsbeuter/' is readable and executable, and
'\~/.newsboat/' doesn't exist. If those conditions are met, it tries to create
'~/.newsboat/' (aborting the migration if that fails), then copies the following
files: 'urls', 'cache.db', 'config', 'queue', 'history.search', 'history.cmdline'.

There's one scenario where the process breaks: if you have an XDG configuration
for Newsbeuter, '\~/.newsboat/' exists and '~/.newsboat/urls' doesn't exist, then
Newsboat will migrate XDG files and proceed, ignoring the dotdir. Please don't
confuse the poor program like that!

Other readers (via OPML)
^^^^^^^^^^^^^^^^^^^^^^^^

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 newsboat:

	newsboat -i ~/blogroll.opml

Don't worry, newsboat 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, newsboat
doesn't throw away this information (although it doesn't support hierarchies), but
generates tags from it. Tags are newsboat's way of organizing subscriptions
in a non-hierarchical way. More information on the use of tags can be found below.

Imagine the following folder hierarchy:

	|- News
	| |- Europe
	| `- International
	|- IT
	| |- Linux
	| |- Windows
	| `- Programming
	|   |- C++
	|   |- Ruby
	|   `- Erlang
	`- Private

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 newsboat, 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.


Advanced Features
-----------------

Tagging
~~~~~~~

include::chapter-tagging.txt[]


Scripts and Filters (Snownews Extensions)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

include::chapter-snownews.txt[]

Bookmarking
~~~~~~~~~~~

Newsboat 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), they are 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), the bookmark description and (since 2.10) the
title of the feed the user is currently in. After the question for the description,
an external program, configured via the configuration command <<bookmark-cmd,`bookmark-cmd`>>, is executed with 4 (since 2.10) 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). If 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 newsboat.

Newsboat comes with an example plugin, which implements a simple tab-separated bookmark file. This
example can be found in the 'contrib' subdirectory.


Command Line
~~~~~~~~~~~~

include::chapter-cmdline.txt[]

.Available Commandline Commands
[frame="all", grid="all", format="dsv", options="header", cols="20,20,40,20l"]
|=============================================================================
Command:Syntax:Description:Example
[[cmd-quit]]<<cmd-quit,+quit+>>:quit:Quit newsboat.:quit
[[cmd-save]]<<cmd-save,+save+>>:save <filename>:Save the currently select article to disk. This works in the article list and in the article view.:save ~/important.txt
[[cmd-set]]<<cmd-set,+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
[[cmd-tag]]<<cmd-tag,+tag+>>:tag <tagname>:Only display feeds with the tag <tagname>.:tag news
[[cmd-goto]]<<cmd-goto,+goto+>>:goto <case-insensitive substring>:Go to the next feed whose name contains the case-insensitive substring.:goto foo
[[cmd-source]]<<cmd-source,+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 ~/.newsboat/colors
[[cmd-dumpconfig]]<<cmd-dumpconfig,+dumpconfig+>>:dumpconfig <filename>:Save current internal state of configuration to file, so that it can be instantly reused as configuration file.:dumpconfig ~/.newsboat/config.saved
[[cmd-dumpform]]<<cmd-dumpform,+dumpform+>>:dumpform:Dump current dialog to text file. This is meant for debugging purposes only.:dumpform
[[cmd-number]]<<cmd-number,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
|=============================================================================


Filter Language
~~~~~~~~~~~~~~~

Newsboat 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:

	( unread_count > 0 and unread_count < 10 ) or total_count > 100
	( author =~ "Frank" or author =~ "John" ) and ( title =~ "Linux" or title =~ "FreeBSD" )

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.

.[[available-comparison-operators]]<<available-comparison-operators,Available Comparison Operators>>
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Operator:Meaning
+=+ / +==+:test for equality
+!=+:test for inequality; logical negation of the +=+ 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
|======================================================================

.Available Attributes
[frame="all", grid="all", format="dsv", options="header", cols="30,30,40"]
|=========================================================================
Attribute:Context:Meaning
[[attr-title]]<<attr-title,+title+>>:article:article title
[[attr-link]]<<attr-link,+link+>>:article:article link
[[attr-author]]<<attr-author,+author+>>:article:article author
[[attr-content]]<<attr-content,+content+>>:article:article body
[[attr-date]]<<attr-date,+date+>>:article:publication date of the article
[[attr-guid]]<<attr-guid,+guid+>>:article:a unique identifier of the article
[[attr-unread]]<<attr-unread,+unread+>>:article:indicates whether the article has been read
[[attr-enclosure_url]]<<attr-enclosure_url,+enclosure_url+>>:article:the URL of a possible enclosure (e.g. podcast file)
[[attr-enclosure_type]]<<attr-enclosure_type,+enclosure_type+>>:article:the MIME type of the enclosure URL
[[attr-flags]]<<attr-flags,+flags+>>:article:The set of flags of the article
[[attr-age]]<<attr-age,+age+>>:article:Age of an article (in days)
[[attr-articleindex]]<<attr-articleindex,+articleindex+>>:article:Index of an article in an article list
[[attr-feedtitle]]<<attr-feedtitle,+feedtitle+>>:feed, article:title of the feed
[[attr-description]]<<attr-description,+description+>>:feed, article:feed description
[[attr-feedlink]]<<attr-feedlink,+feedlink+>>:feed, article:link to the feed
[[attr-feeddate]]<<attr-feeddate,+feeddate+>>:feed, article:publication date of the feed
[[attr-rssurl]]<<attr-rssurl,+rssurl+>>:feed, article:RSS URL of the feed
[[attr-unread_count]]<<attr-unread_count,+unread_count+>>:feed, article:number of unread articles in the feed
[[attr-total_count]]<<attr-total_count,+total_count+>>:feed, article:total number of articles in the feed
[[attr-tags]]<<attr-tags,+tags+>>:feed, article:all tags that are associated with the feed
[[attr-feedindex]]<<attr-feedindex,+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.


Killfiles
~~~~~~~~~

Sometimes, a user is confronted with certain content they don't want to read,
e.g. on topics the user is not interested in or articles written by certain people.
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 newsboat, 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,`ignore-article`>>:

	ignore-article "*" "title =~ \"Gentoo\""
	ignore-article "http://synflood.at/blog/index.php?/feeds/index.rss2" "title =~ \"newsboat\""

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 newsboat 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,`ignore-article`>> commands as desired.

You can also 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,`ignore-mode`>> in the
configuration file:

	ignore-mode "display"


Query Feeds
~~~~~~~~~~~

Query feeds are a mechanism of newsboat to define custom "meta feeds" by using 
newsboat'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. If you want query feeds to be updated at
startup, set <<prepopulate-query-feeds,`prepopulate-query-feeds`>> to `yes`.

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

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

The `query:` in the beginning tells newsboat 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.

This feature is often used to create a 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 to 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:

	http://domain1.tld/feed.xml fun news tag1
	http://domain2.tld/?feed.rss private jokes tag1
	http://domain3.tld/feeds.rss news
	"query:tag1 Articles:tags # \"tag1\""

In this example, the feeds http://domain1.tld/feed.xml and
http://domain2.tld/?feed.rss are aggregated into the query feed named "tag1
Articles", but the feed http://domain3.tld/feeds.rss is not.

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.

The Old Reader Support
~~~~~~~~~~~~~~~~~~~~~

http://theoldreader.com/[The Old Reader] is a successor to Google Reader.
Newsboat provides functionality to use The Old Reader as its 
backend: people can use The Old Reader to manage their subscriptions, and in 
addition, use newsboat to download and read articles. Newsboat 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, newsboat needs to know your The Old Reader username and password 
so that it can authenticate with The Old Reader:

	oldreader-login "your-oldreader-account"
	oldreader-password "your-password"

Note that double quotes should be escaped, i.e. you should write `\"`
instead of `"`.

See also <<oldreader-passwordfile,`oldreaader-passwordfile`>>,
<<oldreader-passwordeval,`oldreader-passwordeval`>> and
<<_passwords_for_external_apis>>.

After setting these configuration values, you can start newsboat, it will 
authenticate with The Old Reader and download your subscription list. If you use 
"folders" in The Old Reader to organize your feeds, newsboat 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, newsboat 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. Newsboat 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, newsboat 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

The Old Reader's folders are converted into Newsboat tags. You can select and
filter feeds by tags; see <<_tagging>> and <<_filter_language>> for details.

NewsBlur Support
~~~~~~~~~~~~~~~~

Newsboat also supports NewsBlur, another alternative to Google Reader. 
Configuration basically works the same as with <<_the_old_reader_support,The Old Reader>>.

First, set your <<urls-source,`urls-source`>>:

	urls-source "newsblur"

Then, configure your NewsBlur credentials:

	newsblur-login "your-newsblur-account"
	newsblur-password "your-password"

Note that double quotes should be escaped, i.e. you should write `\"`
instead of `"`.

See also <<newsblur-passwordfile,`newsblur-passwordfile`>>,
<<newsblur-passwordeval,`newsblur-passwordeval`>> and
<<_passwords_for_external_apis>>.

When you start newsboat, it will download the feeds that you configured
in NewsBlur. Please take a closer look at the
<<newsblur-login,configuration commands>> for what
you can configure in newsboat regarding NewsBlur.

NewsBlur's folders are converted into Newsboat tags. You can select and
filter feeds by tags; see <<_tagging>> and <<_filter_language>> for details.

FeedHQ Support
~~~~~~~~~~~~~~

Newsboat also supports FeedHQ, another alternative to Google Reader. 
Configuration basically works the same as with <<_the_old_reader_support,The Old Reader>>.

First, set your <<urls-source,`urls-source`>>:

	urls-source "feedhq"

Then, configure your FeedHQ credentials:

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

Note that double quotes should be escaped, i.e. you should write `\"`
instead of `"`.

See also <<feedhq-passwordfile,`feedhq-passwordfile`>>,
<<feedhq-passwordeval,`feedhq-passwordeval`>> and
<<_passwords_for_external_apis>>.

if you're using a standalone instance, you should add one more setting:

    feedhq-url "https://the.url.of/your/feedhq/instance"

When you start newsboat, it will download the feeds that you configured
in FeedHQ. Please take a closer look at the
<<feedhq-flag-share,configuration commands>> for what
you can configure in newsboat regarding FeedHQ.

FeedHQ's folders are converted into Newsboat tags. You can select and filter
feeds by tags; see <<_tagging>> and <<_filter_language>> for details.

Tiny Tiny RSS Synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Newsboat 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 newsboat.

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, 
newsboat needs to know that you want to use Tiny Tiny RSS and which 
installation exactly:

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

In addition, it requires username and password for authentication:

	ttrss-login "myusername"
	ttrss-password "mypassword"

Note that double quotes should be escaped, i.e. you should write `\"`
instead of `"`.

See also <<ttrss-passwordfile,`ttrss-passwordfile`>>,
<<ttrss-passwordeval,`ttrss-passwordeval`>> and
<<_passwords_for_external_apis>>.

Tiny Tiny RSS provides two modes of usage, single-user mode and multi-user 
mode. newsboat needs to know about this, too: In single-user mode, 
authentication is done via Basic HTTP authentication, while in multi-user mode, 
authentication is done against Tiny Tiny RSS itself.

	ttrss-mode "single"		# "multi" is default

If Tiny Tiny RSS is configured in multi-user mode and still deployed behind 
an additional HTTP-BasicAuth, the required username and password (which may 
deviate from <<ttrss-login,`ttrss-login`>> and <<ttrss-password,`ttrss-password`>>) can be specified in the user-part
of the url like this:

    ttrss-url "http://htuser:htpasswd@example.com/ttrss/"


With these settings, newsboat 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 public RSS feed. Newsboat 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.

TT-RSS folders are converted into Newsboat tags. You can select and filter
feeds by tags; see <<_tagging>> and <<_filter_language>> for details.

ownCloud News Synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To use ownCloud News support you need to configure a few things.

First, set your <<urls-source,`urls-source`>> to `ocnews` and tell Newsboat where to find
your ownCloud instance:

	urls-source "ocnews"
	ocnews-url "https://localhost/owncloud"

Username and password are required:

	ocnews-login "user"
	ocnews-password "password"

See also <<ocnews-passwordfile,`ocnews-passwordfile`>>,
<<ocnews-passwordeval,`ocnews-passwordeval`>> and <<_passwords_for_external_apis>>.

ownCloud News API uses HTTP basic auth, therefore running ownCloud with SSL is highly
recommended.

ownCloud News provides the ability to "star" articles; starred articles are basically
bookmarks. Newsboat allows the use of this feature by mapping user-specified
flag to the "star" operation.

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

	ocnews-flag-star "s"

If for any reason you don't want Newsboat to verify the hostname of your
instance against the hostname specified in the SSL certificate you're using,
just say so:

	ocnews-verifyhost "no"

OwnCloud News' folders are converted into Newsboat tags. You can select and
filter feeds by tags; see <<_tagging>> and <<_filter_language>> for details.

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.

Inoreader Support
~~~~~~~~~~~~~~~~~

http://inoreader.com/[Inoreader] is another successor to Google Reader.
Newsboat provides functionality to use Inoreader as its backend:
people can use Inoreader to manage their subscriptions, and in
addition, use newsboat to download and read articles. Newsboat will keep
the information which articles have already been read synchronized with
Inoreader, so that users usually won't see articles more than once. In addition, it
will only ever download unread articles from Inoreader.

In order to use Inoreader support, you first need to configure the proper URL source:

	urls-source "inoreader"

In addition, newsboat needs to know your Inoreader username and password
so that it can authenticate with Inoreader.
Note that this is NOT your login with your Google or Facebook account. If you
use one of those to login to Inoreader, you have to create a username and
password in Inoreader _Preferences > Profile_

	inoreader-login "your-inoreader-account"
	inoreader-password "your-password"

(Note that double quotes should be escaped, i.e. you should write +{backslash}"+
instead of +"+.)

See also <<_passwords_for_external_apis,inoreader-passwordfile and inoreader-passwordeval>>.

After setting these configuration values, you can start newsboat, it will
authenticate with Inoreader and download your subscription list. If you use
"folders" in Inoreader to organize your feeds, newsboat 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. You can select and filter feeds by tags;
see <<_tagging>> and <<_filter_language>> sections for details.

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

In addition, Inoreader provides the ability to "star" and to "share"
articles. Starred articles are basically bookmarks, while shared articles are
shown to people that follow your Inoreader account. Newsboat 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:

	inoreader-flag-share "a"
	inoreader-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, newsboat also shows Inoreader "special feeds":

 - Starred items
 - Shared items
 - Liked items
 - Saved web pages

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

	inoreader-show-special-feeds no

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 "Ctrl-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.

Macro Support
~~~~~~~~~~~~~

In newsboat, it's possible to define macros to execute more than one command
at once. A macro is configured using the <<macro,`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:

	macro k open ; reload ; quit
	macro o open-in-browser ; toggle-article-read "read"

When the user presses the macro prefix ("," by default) and then the "k" key,
the three operations <<open,`open`>>, <<reload,`reload`>> and <<quit,`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,`browser`>> configuration variable to do
something else, such as running an image viewer from the URLs view:

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

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

	macro E set browser "echo %u >> ~/.newsboat/queue" ; open-in-browser ; set browser "elinks %u"

Commandline Commands
~~~~~~~~~~~~~~~~~~~~

Newsboat 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 newsboat without printing any output.
  This is useful if a user wants to periodically reload all feeds without always having
  a running newsboat instance, e.g. from cron.
- `print-unread`: this option prints the number of unread articles and quits newsboat.
  This is useful for users who want to integrate this number into some kind of monitoring
  system.


Format Strings
~~~~~~~~~~~~~~

Newsboat 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, newsboat 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:

.Available Identifiers for feedlist-format
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[feedlist-format-d]]<<feedlist-format-d,+d+>>:Feed description
[[feedlist-format-i]]<<feedlist-format-i,+i+>>:Feed index
[[feedlist-format-l]]<<feedlist-format-l,+l+>>:Feed link
[[feedlist-format-L]]<<feedlist-format-L,+L+>>:Feed RSS URL
[[feedlist-format-n]]<<feedlist-format-n,+n+>>:"unread" flag field
[[feedlist-format-S]]<<feedlist-format-S,+S+>>:download status
[[feedlist-format-t]]<<feedlist-format-t,+t+>>:Feed title
[[feedlist-format-T]]<<feedlist-format-T,+T+>>:First tag of a feed in the URLs file
[[feedlist-format-u]]<<feedlist-format-u,+u+>>:"unread/total" field
[[feedlist-format-U]]<<feedlist-format-U,+U+>>:"unread" field
[[feedlist-format-c]]<<feedlist-format-c,+c+>>:"total" field
|======================================================================

While a <<reload-all,`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").

.Available Identifiers for articlelist-format
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[articlelist-format-a]]<<articlelist-format-a,+a+>>:Article author
[[articlelist-format-D]]<<articlelist-format-D,+D+>>:Publication date
[[articlelist-format-f]]<<articlelist-format-f,+f+>>:Article flags
[[articlelist-format-i]]<<articlelist-format-i,+i+>>:Article index
[[articlelist-format-t]]<<articlelist-format-t,+t+>>:Article title
[[articlelist-format-T]]<<articlelist-format-T,+T+>>:If the article list displays articles from different feeds, then this identifier contains the title of the feed to which the article belongs.
[[articlelist-format-L]]<<articlelist-format-L,+L+>>:Article length
|======================================================================

.Available Identifiers for notify-format
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[notify-format-n]]<<notify-format-n,+n+>>:Number of unread articles
[[notify-format-f]]<<notify-format-f,+f+>>:Number of unread feeds
[[notify-format-d]]<<notify-format-d,+d+>>:Number of new unread articles (i.e. that were added through the last reload)
[[notify-format-D]]<<notify-format-D,+D+>>:Number of new unread feeds (i.e. that were added through the last reload)
|======================================================================

Examples:

	feedlist-format     "%4i %n %11u %t"
	articlelist-format  "%4i %f %D   %?T?|%-17T|  ?%t"
	notify-format       "%d new articles (%n unread articles, %f unread feeds)"


Dialog Titles
^^^^^^^^^^^^^

You can 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 that the title formats are localized, so if you
work on a different locale that is supported by newsboat, the actually displayed
title text may vary unless you customize it.

.Dialog Title Formats
[frame="all", grid="all", format="dsv", options="header", cols="20,30,50l"]
|==========================================================================
Dialog:Configuration Variable:Default Value
Feed List:<<feedlist-title-format,+feedlist-title-format+>>:%N %V - Your feeds (%u unread, %t total)%?T? - tag `%T'&?
Article List:<<articlelist-title-format,+articlelist-title-format+>>:%N %V - Articles in feed '%T' (%u unread, %t total) - %U
Search Result:<<searchresult-title-format,+searchresult-title-format+>>:%N %V - Search result (%u unread, %t total)
File Browser:<<filebrowser-title-format,+filebrowser-title-format+>>:%N %V - %?O?Open File&Save File? - %f
Help:<<help-title-format,+help-title-format+>>:%N %V - Help
Select Tag Dialog:<<selecttag-title-format,+selecttag-title-format+>>:%N %V - Select Tag
Select Filter Dialog:<<selectfilter-title-format,+selectfilter-title-format+>>:%N %V - Select Filter
Article View:<<itemview-title-format,+itemview-title-format+>>:%N %V - Article '%T' (%u unread, %t total)
URL View:<<urlview-title-format,+urlview-title-format+>>:%N %V - URLs
Dialog List:<<dialogs-title-format,+dialogs-title-format+>>:%N %V - Dialogs
|==========================================================================

.Common Title Format Identifiers
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[common-title-format-N]]<<common-title-format-N,+N+>>:Name of the program, i.e. "newsboat"
[[common-title-format-V]]<<common-title-format-V,+V+>>:Program version
[[common-title-format-u]]<<common-title-format-u,+u+>>:Number of unread articles (if applicable)
[[common-title-format-t]]<<common-title-format-t,+t+>>:Number of total articles (if applicable)
|======================================================================

.Feed List Title Format Identifiers
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[feedlist-title-format-T]]<<feedlist-title-format-T,+T+>>:Currently selected tag (empty if none selected)
|======================================================================

.Article List Title Format Identifiers
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[articlelist-title-format-T]]<<articlelist-title-format-T,+T+>>:Feed title
[[articlelist-title-format-U]]<<articlelist-title-format-U,+U+>>:Feed URL
|======================================================================

.File Browser Title Format Identifiers
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[filebrowser-title-format-f]]<<filebrowser-title-format-f,+f+>>:Filename
[[filebrowser-title-format-O]]<<filebrowser-title-format-O,+O+>>:Non-empty if file browser is in open mode, empty if in save mode
|======================================================================

.Article View Title Format Identifiers
[frame="all", grid="all", format="dsv", options="header", cols="30,70"]
|======================================================================
Identifier:Meaning
[[articleview-title-format-T]]<<articleview-title-format-T,+T+>>:Article title
[[articleview-title-format-F]]<<articleview-title-format-F,+F+>>:Feed title
|======================================================================

Highlighting Text
~~~~~~~~~~~~~~~~~

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

Examples for possible highlighting configurations are:

	highlight all "newsboat" red
	highlight article "^(Feed|Title|Author|Link|Date):" default default underline
	highlight feedlist "https?://[^ ]+" yellow red bold


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,`highlight-article`>> configuration
command.

The syntax is similar to the <<highlight,`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


Advanced Dialog Management
~~~~~~~~~~~~~~~~~~~~~~~~~~

Newsboat 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".


XDG Base Directory Support
~~~~~~~~~~~~~~~~~~~~~~~~~~

Newsboat implements limited support for the
http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html[XDG Base
Directory Specification]. It needs to be set up manually by creating the
following directories:

- '~/.local/share/newsboat/'
- '~/.config/newsboat/'

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

If you're currently using '~/.newsboat/' but wish to migrate to XDG
directories, you should move the files as follows:

'config', 'urls'::
        to '$HOME/.config/newsboat/'

'cache.db', 'history.search', 'history.cmdline', 'queue'::
        to '$HOME/.local/share/newsboat/'


Podcast Support
~~~~~~~~~~~~~~~

include::chapter-podcasts.txt[]

.Podboat Configuration Commands
[frame="all", grid="all", format="dsv", separator="\|\||\n", options="header", cols="10,15,15l,40,20l"]
|======================================================================================================
Configuration Command||Argument(s)||Default||Description||Example
include::podboat-cmds-linked.dsv[]
|======================================================================================================

.Available Operations in Podboat
[frame="all", grid="all", format="dsv", options="header", cols="20,20,60"]
|=========================================================================
Operation:Default key:Description
[[pb-quit]]<<pb-quit,+quit+>>:q:Quit the program.
[[pb-download]]<<pb-download,+pb-download+>>:d:Download the currently selected URL.
[[pb-cancel]]<<pb-cancel,+pb-cancel+>>:c:Cancel the currently selected download.
[[pb-play]]<<pb-play,+pb-play+>>:p:Start player with currently selected download.
[[pb-delete]]<<pb-delete,+pb-delete+>>:D:Delete the currently selected URL from the queue.
[[pb-purge]]<<pb-purge,+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]]<<pb-toggle-download-all,+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]]<<pb-increase-max-dls,+pb-increase-max-dls+>>:+:Increase the "max-downloads" option by 1.
[[pb-decrease-max-dls]]<<pb-decrease-max-dls,+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 newsboat to automatically enqueue newly
found podcast download URLs. Then, the user reloads the podcast RSS feeds in
newsboat, and after that, uses podboat to view the current queue, and
either selectively download certain files or automatically download them all
together by pressing "a" within podboat.

Running multiple copies of Newsboat simultaneously
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

During development and testing, you might want to run a second copy of
Newsboat, operating with different config, URLs list or cache file. This can
be achieved by creative use of XDG environment variables. This approach is not
beautiful, but it works.

First of all, you will need to create a directory to store the data. Let's call
it 'test':

	$ mkdir -p test/newsboat

Note that we also create a subdirectory called 'newsboat'; this is required
to satisfy XDG specification. **ATTENTION**: if this subdirectory is absent,
Newsboat will attempt to run on your live data!

You can now create 'config' and 'urls' files inside 'test/newsboat'; you can
also copy 'cache.db' if you don't want to start with a fresh one.

When the files are ready, you can invoke Newsboat as follows:

	$ XDG_CONFIG_HOME=test XDG_DATA_HOME=test newsboat

(This will look +newsboat+ binary up in your +PATH+; if you've just built
your own, use +./newsboat+ instead, or provide a full path.)

By modifying the environment in which Newsboat runs you also modify
environments of all the programs that Newsboat starts; that includes filters
and external HTML renderers. If they rely on +XDG_*+ variables, they will look
for things in +test+ directory and might fail.

For filters, you should either copy the files they need to 'test', or invoke
them in such a way that they don't look in XDG directories at all.

For renderers, you can work around the issue by undoing the modifications to
environment, e.g.:

	html-renderer "XDG_CONFIG_HOME=$HOME/.config XDG_DATA_HOME=$HOME/.data w3c"

As already said: not beautiful, but gets the job done.

Using SQLite Triggers with newsboat
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section was written by mailto:elrond+newsbeuter(at)samba-tng.org[Elrond],
originally for Newsbeuter.

SQLite, the db used by newsboat, 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
newsboat 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 newsboat? Well, first off, it's a
hack. The real answer should be to use application logic (do it inside
newsboat, 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. newsboat
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 newsboat
changes the subject and then let itself mark the article again as unread.

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

2. Start `sqlite3` with the newsboat db:

	 Rivendell:~/.newsboat% sqlite3 cache.db
	 SQLite version 3.4.2
	 Enter ".help" for instructions
	 sqlite>

3. Create the trigger:

	 sqlite> create trigger update_item_title update of title on rss_item
		   > for each row when old.title != new.title
		   > begin
		   >   update rss_item set unread = 1 where rowid == new.rowid;
		   > end;

4. Leave `sqlite3` with "Ctrl-D" or `.quit`.

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

Passwords for external APIs
~~~~~~~~~~~~~~~~~~~~~~~~~~~

include::chapter-password.txt[]

Feedback
--------

If you want to tell us something related to newsboat, don't hesitate to send
an email to our mailing list: newsboat@googlegroups.com

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

If you want to report newsboat bugs, please use this issue tracker:
https://github.com/newsboat/newsboat/issues/[]

License
-------
MIT License

Copyright 2006-2015 Andreas Krennmair <ak@newsbeuter.org>
Copyright 2015-2017 Alexander Batischev <eual.jp@gmail.com>
Copyright 2006-2017 Newsbeuter contributors
Copyright 2017 Newsboat contributors

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.
