The Newsbeuter RSS Feedreader
=============================
Andreas Krennmair <ak@synflood.at>

Introduction
------------
Newsbeuter is an RSS feedreader. RSS is 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. NetBSD is currently not supported,
due to technical limitations in the iconv() implementation.

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 competiton that was
started when I got aware that the original name would violate French and
European registered trademarks.

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

Downloading Newsbeuter
~~~~~~~~~~~~~~~~~~~~~~
Newsbeuter is available as source package. Simply go to
http://synflood.at/newsbeuter.html[] 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 SVN repository by
running the following command on the commandline:

svn co http://bereshit.synflood.at/svn/noos/trunk

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.

- STFL (version 0.18 or newer): http://www.clifford.at/stfl/[]
- SQLite 3 (version 3.4 or newer): http://www.sqlite.org/[]
- libcurl: http://curlm.haxx.se/download.html[]
- GNU gettext (on systems that don't provide gettext in the libc): ftp://ftp.gnu.org/gnu/gettext/[]
- pkg-config: http://pkg-config.freedesktop.org/wiki/[]

If you intend to modify 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 "coco-cpp" in your PATH. Debian users only need to install
the package "coco-cpp".


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.


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

include::chapter-firststeps.txt[]



.Configuration Commands
[frame="all", grid="all",format="dsv",separator="|"]
`10`15`15`40`20~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration Command|Argument(s)|Default|Description|Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::configcommands.dsv[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.Available Operations
[frame="all", grid="all", format="dsv",separator="|"]
`20`20`60~~~~~~~~~~~~~~~~~~~~~~~~
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.
open-in-browser|o|Opens the URL associated with the current article.
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.
select-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.
enqueue|e|Add the podcast download URL of the current article (if any is found) to the podcast download queue (see below for more information on podcast support).
reload-urls|^R|Reload the URLs configuration file.
redraw|^L|Redraw the screen.
cmdline|:|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.
delete-article|D|Delete the currently selected article.
purge-deleted|$|Purge all article that are marked as deleted from the article list.
up|UP|Goes up one item in the list.
down|DOWN|Goes down one item in the list.
pageup|PPAGE|Goes up one page in the list.
pagedown|NPAGE|Goes down one page in the 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:

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


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

The "default" color means that the terminal's default color will be used.

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
- *info*: the info bars on top and bottom
- *background*: the application background
- *article*: the article text

The default color configuration of newsbeuter looks like this:

	background   white   black
	listnormal   white   black
	listfocus    yellow  blue   bold
	info         yellow  blue   bold
	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 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 itmes 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.

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


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

Tagging
~~~~~~~

include::chapter-tagging.txt[]


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

include::chapter-snownews.txt[]

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.


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

include::chapter-cmdline.txt[]

.Available Commandline Commands
[frame="all", grid="all", format="dsv"]
`20`20`40`20~~~~~~~~~~~~~~~~~~~
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: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
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
~~~~~~~~~~~~~~~

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

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
[frame="all", grid="all", format="dsv"]
`30`70~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
#: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"]
`30`30`40~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

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.


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:

	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.


Bloglines Synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~

http://www.bloglines.com[Bloglines] is a web-based RSS feed reader. Newsbeuter
provides a synchronization feature that makes it possible to download unread
articles from Bloglines (which can then be optionally be marked as read). This
is useful in cases where you want to use the web frontend e.g. at work, and use
newsbeuter e.g. when you're at home. It is also possible to use newsbeuter as
an offline reader for Bloglines.

To enable Bloglines support, you first need to set the following configuration
variable:

	urls-source "bloglines"

By default, this is set to "local", which means that the list of configured
URLs is retrieved from ~/.newsbeuter/urls. By setting it to "bloglines",
newsbeuter will retrieve the list of retrieved URLs directly from Bloglines.
This means that you can only either use the locally configured URLs or the URLs
from Bloglines. Combination of both is not possible.

After setting the URLs source, you also need to set the Bloglines authentication configuration:

	bloglines-auth "username@emailaddress.com:yourpassword"

In the configuration variable "bloglines-auth", you provide your Bloglines
login (i.e. your email address) and your password, separated by a colon (":"). Optionally, you can configure that all messages that are downloaded are marked as read in the Bloglines web frontend:

	bloglines-mark-read "yes"

After you've configured newsbeuter for Bloglines, you can start it up. Newsbeuter
will then download the RSS feed URLs subscribed in Bloglines, which you can then
reload.

In this configuration, you need the possibility to connect to Bloglines. In
case you don't have access to Bloglines (e.g. a temporary network outage, or
you sit in a location without connectivity, e.g. a train), you can start
newsbeuter in offline mode:

	newsbeuter -o

With this commandline switch, you can read the articles that you have already
downloaded without any network connectivity. This functionality makes
newsbeuter a true offline client for Bloglines.

OPML Online Subscription Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The OPML online subscription mode works similar to the Bloglines
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 an OPML that is 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" must be specified as source for the feed URLs, and the URL of the OPML
file needs to be specified, too. As with Bloglines synchronization mode, the offline
mode via "newsbeuter -o" also works with OPML online subscription mode.


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.

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:

	macro k open ; reload ; quit

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.

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 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 evaluted and
inserted, otherwise "[format 2]" will be evaluted 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"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identifier:Meaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d:Feed description
i:Feed index
l:Feed link
L:Feed RSS URL
n:"unread" flag field
t:Feed title
u:"unread/total" field
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.Available Identifiers for articlelist-format
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.Available Identifiers for notify-format
[frame="all", grid="all", format="dsv"]
`30`60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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)

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

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

include::chapter-podcasts.txt[]

.Podbeuter Configuration Commands
[frame="all", grid="all",format="dsv",separator="|"]
`10`15`15`40`20~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration Command|Argument(s)|Default|Description|Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
include::podbeuter-cmds.dsv[]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.Available Operations in Podbeuter
[frame="all", grid="all", format="dsv"]
`20`20`60~~~~~~~~~~~~~~~~~~~~~~~~
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-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.

Using SQLite Triggers with newsbeuter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section was kindly provided by mailto:elrond+newsbeuter(at)samba-tng.org[Elrond].

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.

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 newsbeuter db:

	 Rivendell:~/.newsbeuter% 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. 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.

Feedback
--------

If you want to tell us something related to newsbeuter, don't hesitate to send
an email: ak-newsbeuter@synflood.at

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

If you want to report newsbeuter bugs, please use this issue tracker:
http://code.google.com/p/newsbeuter/issues/list[]

License
-------
MIT/X Consortium License

(C)opyright 2006-2008 Andreas Krennmair <ak@synflood.at>

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.
