: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 |-e] [-u ] [-c ] [-x ...] [-h] -e, --export-to-opml export OPML feed to stdout -r, --refresh-on-start refresh feeds on start -i, --import-from-opml= import OPML file -u, --url-file= read RSS feed URLs from -c, --cache-file= use as cache file -C, --config-file= read configuration from -X, --vacuum compact the cache -x, --execute=... execute list of commands -q, --quiet quiet startup -v, --version get version information -l, --log-level= write a log with a certain loglevel (valid values: 1 to 6) -d, --log-file= use as output log file -E, --export-to-file= export list of read articles to -I, --import-from-file= import list of read articles from -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 <> 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 <>. **** *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. The maximum number of articles is controlled by <>. **** **** *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 <>. **** *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 <>. ****