Move remote APIs descriptions into separate chapter

1 files changed, 273 insertions, 263 deletions

diff --git a/doc/newsboat.txt b/doc/newsboat.txt
index d0fb1e3b..59a0e046 100644
--- a/doc/newsboat.txt
+++ b/doc/newsboat.txt
@@ -307,236 +307,18 @@ 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:
+Newsboat as a Client for Newsreading Services
+---------------------------------------------
 
-	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
-|=========================================================================
+Newsboat is a perfectly capable feedreader in its own right, but it can’t cover
+_all_ the use-cases. For example, you might want to synchronize your news
+between devices, or you don’t have a computer that’s running 24/7 to fetch your
+feeds. In such cases, you might register with some online feedreader, and use
+Newsboat as a client. The next few sections provide configuration instructions
+for each supported service.
 
-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
-~~~~~~~~~~~~~~~~~~~~~
+The Old Reader
+~~~~~~~~~~~~~~
 
 http://theoldreader.com/[The Old Reader] is a successor to Google Reader.
 Newsboat provides functionality to use The Old Reader as its 
@@ -602,11 +384,11 @@ You can disable these feeds by setting the following configuration variable:
 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
-~~~~~~~~~~~~~~~~
+NewsBlur
+~~~~~~~~
 
 Newsboat also supports NewsBlur, another alternative to Google Reader. 
-Configuration basically works the same as with <<_the_old_reader_support,The Old Reader>>.
+Configuration basically works the same as with <<_the_old_reader,The Old Reader>>.
 
 First, set your <<urls-source,`urls-source`>>:
 
@@ -632,11 +414,11 @@ 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
-~~~~~~~~~~~~~~
+FeedHQ
+~~~~~~
 
 Newsboat also supports FeedHQ, another alternative to Google Reader. 
-Configuration basically works the same as with <<_the_old_reader_support,The Old Reader>>.
+Configuration basically works the same as with <<_the_old_reader,The Old Reader>>.
 
 First, set your <<urls-source,`urls-source`>>:
 
@@ -666,8 +448,8 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tiny Tiny RSS
+~~~~~~~~~~~~~
 
 Newsboat can be used to synchronize with Tiny Tiny RSS 
 installations. Tiny Tiny RSS is a web-based and (optionally) multi-user feed 
@@ -711,7 +493,6 @@ 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.
@@ -732,8 +513,8 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ownCloud News
+~~~~~~~~~~~~~
 
 To use ownCloud News support you need to configure a few things.
 
@@ -771,25 +552,8 @@ just say so:
 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
-~~~~~~~~~~~~~~~~~
+Inoreader
+~~~~~~~~~
 
 http://inoreader.com/[Inoreader] is another successor to Google Reader.
 Newsboat provides functionality to use Inoreader as its backend:
@@ -855,6 +619,257 @@ You can disable these feeds by setting the following configuration variable:
 
 	inoreader-show-special-feeds no
 
+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.
+
+Passwords for external APIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+include::chapter-password.txt[]
+
+
+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.
+
 Flagging Articles
 ~~~~~~~~~~~~~~~~~
 
@@ -1278,11 +1293,6 @@ 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[]
-
 Environment variables
 ~~~~~~~~~~~~~~~~~~~~~