:experimental:

After you've installed Newsboat, you can run it for the first time by typing
`newsboat` on your command prompt. This will bring you the following message:

----
Error: no URLs configured. Please fill the file /home/ak/.newsboat/urls with RSS feed URLs or import an OPML file.

Newsboat 2.22
usage: ./newsboat [-i <file>|-e] [-u <urlfile>] [-c <cachefile>] [-x <command> ...] [-h]
    -e, --export-to-opml            export OPML feed to stdout
    -r, --refresh-on-start          refresh feeds on start
    -i, --import-from-opml=<file>   import OPML file
    -u, --url-file=<urlfile>        read RSS feed URLs from <urlfile>
    -c, --cache-file=<cachefile>    use <cachefile> as cache file
    -C, --config-file=<configfile>  read configuration from <configfile>
    -X, --vacuum                    compact the cache
    -x, --execute=<command>...      execute list of commands
    -q, --quiet                     quiet startup
    -v, --version                   get version information
    -l, --log-level=<loglevel>      write a log with a certain loglevel (valid values: 1 to 6)
    -d, --log-file=<logfile>        use <logfile> as output log file
    -E, --export-to-file=<file>     export list of read articles to <file>
    -I, --import-from-file=<file>   import list of read articles from <file>
    -h, --help                      this help
        --cleanup                   remove unreferenced items from cache
----

This means that Newsboat can't start without any configured feeds.

=== Adding Feeds

To add feeds to Newsboat, you can simply add one feed URL per line to the _~/.newsboat/urls_
configuration file:

	http://rss.cnn.com/rss/cnn_topstories.rss
	http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml

You can also import an OPML file by running `newsboat -i blogroll.opml`


****
*Adding comments* Lines that start with `#` can contain anything you want.
Comments are ignored by Newsboat, but can serve as documentation for you.
Please note, that commenting out URLs for debugging
purposes might lead to unexpected data loss, see
<<cleanup-on-quit,`cleanup-on-quit`>> for more details.
****

*Feeds with restricted access*

If you need to add URLs that have restricted access, simply
provide username/password:

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

In case there is a _@_ in the username, you need to write it as _%40_.

In order to protect usernames and passwords, make sure to restrict read access
for _~/.newsboat/urls_ to you and optionally your group:

    $ chmod u=rw,g=r,o= ~/.newsboat/urls

Newsboat makes sure to not display usernames and passwords in its user interface.

*Local files as feeds*

You can also configure local files as feeds, by prefixing the local path with
`file://` and adding it to the _urls_ file:

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

=== First UI Interaction

The main UI of Newsboat consists of three views

_Feed List View -> Article List View -> Article View_

You can drill down those views by pressing kbd:[Enter] and move to the previous one by pressing
kbd:[Q]. Pressing kbd:[Q] on the _Feed List View_ — or pressing kbd:[Shift+Q] from anywhere — closes Newsboat.

You can also search articles' title or content by pressing kbd:[/] on the _Feed List View_ or the _Article List View_.
On the _Feed List View_ all articles of all feeds are taken into account.
On the _Article List View_ the articles of the current feed are taken into account.
When opening an article from a search result dialog, the search phrase is highlighted.

****
*Search history* The history of all your searches is saved to the filesystem, to the
_history.search_ file (stored next to the _cache.db_ file). By default, the
last 100 search phrases are stored.

You can influence how many search phrases are stored by configuring <<history-limit,`history-limit`>>.
****

*Feed List View*

When you start Newsboat, it presents you with a list of feeds that you added previously.

You can now:

* Press kbd:[Shift+R] to download articles for all feeds.
* Press kbd:[R] to download articles for the selected feed.
* Press kbd:[/] to search all articles in all feeds.
* Press kbd:[Enter] to go to the article list of a selected feed.
* Press kbd:[Q] to close Newsboat.

****
*Local articles* Newsboat keeps the articles that it downloads.
When you start Newsboat again and reload a feed, old articles can still be
read even if they aren't in the current RSS feeds anymore.

You can configure how many articles are kept per feed so that the article backlog doesn't
grow endlessly by configuring <<max-items,`max-items`>>.
****

****
*Caching* Newsboat uses a number of measures to preserve the users' and feed
providers' bandwidth through the use of conditional HTTP downloading.
It saves every feed's "Last-Modified" and "ETag" response header values
(if present) and advises the feed's HTTP server to only send data if the feed
has been updated. This doesn't only make feed downloads for RSS feeds with no new
updates faster, it also reduces the amount of transferred data per request.

You can disable conditional HTTP downloading per feed by configuring
<<always-download,`always-download`>>.
****

*Article List View*

After you entered a feed, you can see the list of available articles
by their title.
A `N` on the left indicates that an article wasn't read yet.

You can now:

* Press kbd:[Q] to go back to the _Feed List View_.
* Press kbd:[/] to search all articles of this feed.
* Press kbd:[Enter] to read a selected article.

*Article View*

On an article you can scroll through the text and read it.
Each link in the article has a number next to it.

You can now:

* Press any number to open an article link in the browser.
  For numbers larger than 9 type kbd:[#], then the number and press kbd:[Enter].
* Press kbd:[O] to open the article in the browser.
* Press kbd:[Q] to go back to the _Article List View_.


****
*Browser view* Sometimes the content of an article is empty or just
an abstract or short description.
You can always press kbd:[O] to view the complete article in a browser.
The default browser is _lynx_.

You can use your browser of choice by configuring <<browser,`browser`>>.
****
