'\" t
.\" Title: newsbeuter
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2
.\" Date: 06/23/2011
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
.TH "NEWSBEUTER" "1" "06/23/2011" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
newsbeuter \- an RSS feed reader for text terminals
.SH "SYNOPSIS"
.sp
\fInewsbeuter\fR [\-r] [\-e] [\-i opmlfile] [\-u urlfile] [\-c cachefile] [\-C configfile] [\-X] [\-o] [\-x \&...] [\-h]
.SH "DESCRIPTION"
.sp
\fInewsbeuter\fR is an RSS feed reader for text terminals\&. 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, BSD or Mac OS X\&.
.SH "OPTIONS"
.PP
\-h
.RS 4
Display help
.RE
.PP
\-r
.RS 4
Refresh feeds on start
.RE
.PP
\-e
.RS 4
Export feeds as OPML to stdout
.RE
.PP
\-X
.RS 4
Clean up cache thoroughly (i\&.e\&. reduce it in size if possible)
.RE
.PP
\-v, \-V
.RS 4
Get version information about newsbeuter and the libraries it uses
.RE
.PP
\-i opmlfile
.RS 4
Import an OPML file
.RE
.PP
\-u urlfile
.RS 4
Use an alternative URL file
.RE
.PP
\-c cachefile
.RS 4
Use an alternative cache file
.RE
.PP
\-C configfile
.RS 4
Use an alternative configuration file
.RE
.PP
\-x command \&...
.RS 4
Execute one or more commands to run newsbeuter unattended\&. Currently available commands are "reload" and "print\-unread"\&.
.RE
.PP
\-o
.RS 4
Active offline reading mode\&. When Google Reader synchronization mode is configured, then the list of feeds will not be loaded from Google Reader, but instead from the local cache\&. This makes it possible to read locally cached articles even without internet connection to connect to Google Reader\&.
.RE
.PP
\-l loglevel
.RS 4
Generate a loglevel with a certain loglevel\&. Valid loglevels are 1 to 6\&. An actual logfile will only be written when you provide a logfile name\&.
.RE
.PP
\-d logfile
.RS 4
Use this logfile as output when logging debug messages\&. Please note that this only works when providing a loglevel\&.
.RE
.PP
\-E file
.RS 4
Export a list of read articles (resp\&. their GUIDs)\&. This can be used to transfer information about read articles between different computers\&.
.RE
.PP
\-I file
.RS 4
Import a list of read articles and mark them as read if they are held in the cache\&. This is to be used in conjunction with the \-E commandline parameter\&.
.RE
.SH "FIRST STEPS"
.sp
After you\(cqve installed newsbeuter, you can run it for the first time by typing "newsbeuter" on your command prompt\&. This will bring you the following message:
.sp
.if n \{\
.RS 4
.\}
.nf
Error: no URLs configured\&. Please fill the file /home/ak/\&.newsbeuter/urls with RSS feed URLs or import an OPML file\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
newsbeuter 2\&.4
usage: \&./newsbeuter [\-i |\-e] [\-u ] [\-c ] [\-x \&.\&.\&.] [\-h]
\-e export OPML feed to stdout
\-r refresh feeds on start
\-i import OPML file
\-u read RSS feed URLs from
\-c use as cache file
\-C read configuration from
\-X clean up cache thoroughly
\-x \&.\&.\&. execute list of commands
\-o activate offline mode (only applies to Google Reader synchronization mode)
\-q quiet startup
\-v get version information
\-l write a log with a certain loglevel (valid values: 1 to 6)
\-d use as output log file
\-E export list of read articles to
\-I import list of read articles from
\-h this help
.fi
.if n \{\
.RE
.\}
.sp
This means that newsbeuter can\(cqt 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:
.sp
.if n \{\
.RS 4
.\}
.nf
http://rss\&.cnn\&.com/rss/cnn_topstories\&.rss
http://newsrss\&.bbc\&.co\&.uk/rss/newsonline_world_edition/front_page/rss\&.xml
.fi
.if n \{\
.RE
.\}
.sp
If you need to add URLs that have restricted access via username/password, simply provide the username/password in the following way:
.sp
.if n \{\
.RS 4
.\}
.nf
http://username:password@hostname\&.domain\&.tld/feed\&.rss
.fi
.if n \{\
.RE
.\}
.sp
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\(cqt displayed in its user interface\&. In case there is a \fI@\fR in the username, you need to write it as \fI%40\fR instead so that it can be distinguished from the \fI@\fR that separates the username/password part from the hostname part\&.
.sp
You can also configure local files as feeds, by prefixing the local path with "file://" and adding it to the $HOME/\&.newsbeuter/urls file:
.sp
.if n \{\
.RS 4
.\}
.nf
file:///var/log/rss_eventlog\&.xml
.fi
.if n \{\
.RE
.\}
.sp
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\(cqt 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\&.
.sp
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\(cqt in the current RSS feeds anymore\&. Optionally you can configure how many articles shall be preserved by feed so that the article backlog doesn\(cqt grow endlessly (see "max\-items" below)\&.
.sp
Newsbeuter also uses a number of measures to preserve the users\*(Aq and feed providers\*(Aq bandwidth, by trying to avoid unnecessary feed downloads through the use of conditional HTTP downloading\&. It saves every feed\(cqs "Last\-Modified" and "ETag" response header values (if present) and advises the feed\(cqs HTTP server to only send data if the feed has been updated by modification date/time or "ETag" header\&. This doesn\(cqt 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\&.
.sp
Several aspects of newsbeuter\(cqs behaviour can be configured via a configuration file, by default $HOME/\&.newsbeuter/config\&. This configuration file contains lines in the form " \&..."\&. The configuration file can also contain comments, which start with the \fI#\fR 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\(cqs 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\&.
.sp
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\&.
.sp
The history of all your searches is saved to the filesystem, to \e~/\&.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\&.
.SH "CONFIGURATION COMMANDS"
.PP
\fIalways\-display\-description\fR (parameters: [true/false]; default value: \fIfalse\fR)
.RS 4
If true, then the description will always displayed even if e\&.g\&. a content:encoded tag has been found\&. (example: always\-display\-description true)
.RE
.PP
\fIalways\-download\fR (parameters: []; default value: \fIn/a\fR)
.RS 4
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\&. (example: always\-download "http://www\&.n\-tv\&.de/23\&.rss")
.RE
.PP
\fIarticle\-sort\-order\fR (parameters: [\-]; default value: \fIdate\fR)
.RS 4
The sortfield specifies which article property shall be used for sorting (currently available: date, title, flags, author, link, guid)\&. The optional direction specifies the sort direction ("asc" specifies ascending sorting, "desc" specifies descending sorting\&. for date, "desc" is default, for all others, "asc" is default)\&. (example: article\-sort\-order author\-desc)
.RE
.PP
\fIarticlelist\-format\fR (parameters: ; default value: \fI"%4i %f %D %6L %?T?;%\-17T; ?%t"\fR)
.RS 4
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)\&. (example: articlelist\-format "%4i %f %D %?T?;%\-17T; ?%t")
.RE
.PP
\fIauto\-reload\fR (parameters: [yes/no]; default value: \fIno\fR)
.RS 4
If enabled, all feeds will be automatically reloaded at start up and then continuously after a certain time has passed (see reload\-time)\&. (example: auto\-reload yes)
.RE
.PP
\fIbind\-key\fR (parameters: [