diff options
Diffstat (limited to 'doc/newsbeuter.1')
| -rw-r--r-- | doc/newsbeuter.1 | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/doc/newsbeuter.1 b/doc/newsbeuter.1 new file mode 100644 index 00000000..50339f56 --- /dev/null +++ b/doc/newsbeuter.1 @@ -0,0 +1,398 @@ +.\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "NEWSBEUTER" 1 "" "" "" +.SH NAME +newsbeuter \- an RSS feed reader for text terminals +.SH "SYNOPSIS" + + +\fInewsbeuter\fR [\-r] [\-e] [\-i opmlfile] [\-u urlfile] [\-c cachefile] [\-C configfile] [\-v] [\-o] [\-h] + +.SH "DESCRIPTION" + + +\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" + +.TP +\-h +Display help + +.TP +\-r +Refresh feeds on start + +.TP +\-e +Export feeds as OPML to stdout + +.TP +\-v +Clean up cache thoroughly (i\&.e\&. reduce it in size if possible) + +.TP +\-V +Get version information about newsbeuter and the libraries it uses + +.TP +\-i opmlfile +Import an OPML file + +.TP +\-u urlfile +Use an alternative URL file + +.TP +\-c cachefile +Use an alternative cache file + +.TP +\-C configfile +Use an alternative configuration file + +.TP +\-o +Active offline reading mode\&. When bloglines synchronization mode is configured, then the list of feeds will not be loaded from bloglines\&.com, but instead from the local cache\&. This makes it possible to read locally cached articles even without internet connection to connect to the bloglines server\&. + +.SH "FIRST STEPS" + + +After you've installed newsbeuter, you can run it for the first time by typing "newsbeuter" on your command prompt\&. This will bring you the following message: + +.nf +Error: no URLs configured\&. Please fill the file /Users/ak/\&.newsbeuter/urls with RSS feed URLs or import an OPML file\&. +.fi + +.nf +newsbeuter 0\&.8 +usage: \&./newsbeuter [\-i <file>|\-e] [\-u <urlfile>] [\-c <cachefile>] [\-h] + \-r refresh feeds on start + \-e export OPML feed to stdout + \-i <file> import OPML file + \-u <urlfile> read RSS feed URLs from <urlfile> + \-c <cachefile> use <cachefile> as cache file + \-C <configfile> read configuration from <configfile> + \-v clean up cache thoroughly + \-h this help +.fi + + +This means that newsbeuter can't 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: + +.nf +http://rss\&.cnn\&.com/rss/cnn_topstories\&.rss +http://newsrss\&.bbc\&.co\&.uk/rss/newsonline_world_edition/front_page/rss\&.xml +.fi + + +If you need to add URLs that have restricted access via username/password, simply provide the username/password in the following way: + +.nf +http://username:password@hostname\&.domain\&.tld/feed\&.rss +.fi + + +In order to protect username and password, make sure that $HOME/\&.newsbeuter/urls has the appropriate permissions\&. + + +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't 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\&. + + +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't in the current RSS feeds anymore\&. Optionally you can configure how many articles shall be preserved by feed so that the article backlog doesn't grow endlessly (see below)\&. + + +Several aspects of newsbeuter's behaviour can be configured via a configuration file, by default $HOME/\&.newsbeuter/config\&. This configuration files contains lines in the form "<config\-command> <arg1> ..."\&. 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\&. + + +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\&. + +.SH "CONFIGURATION COMMANDS" + +.TP +\fIalways\-display\-description\fR (parameters: [true/false]; default value: \fIfalse\fR) +If true, then the description will always displayed even if e\&.g\&. a content:encoded tag has been found\&. (example: always\-display\-description true) + +.TP +\fIarticlelist\-format\fR (parameters: <format>; default value: \fI"%4i %f %D %?T?;%\-17T; ?%t"\fR) +This variable defines the format of entries in the article list\&. See below 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") + +.TP +\fIauto\-reload\fR (parameters: [yes/no]; default value: \fIno\fR) +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) + +.TP +\fIbind\-key\fR (parameters: <key> <operation>; default value: \fIn/a\fR) +Bind key <key> to <operation>\&. This means that whenever <key> is pressed, then <operation> is executed (if applicable in the current context)\&. A list of available operations can be found below\&. (example: bind\-key ^R reload\-all) + +.TP +\fIbookmark\-cmd\fR (parameters: <command>; default value: \fI""\fR) +If set, the configured command will be used as bookmark plugin\&. Please refer to the documentation for further information on bookmark plugins\&. (example: bookmark\-cmd "~/bin/my\-bookmark\-plugin\&.sh") + +.TP +\fIbloglines\-auth\fR (parameters: <login>:<password>; default value: \fI""\fR) +Set the Bloglines username and password\&. This is necessary for the Bloglines synchronization mode\&. (example: bloglines\-auth "username@emailaddress\&.com:mypassword") + +.TP +\fIbloglines\-mark\-read\fR (parameters: [yes/no]; default value: \fIno\fR) +If set to yes, it will mark all articles that are downloaded from Bloglines as read\&. (example: bloglines\-mark\-read yes) + +.TP +\fIbookmark\-cmd\fR (parameters: <bookmark\-command>; default value: \fI""\fR) +If set, then <bookmark\-command> will be used as bookmarking plugin\&. See the documentation on bookmarking for further information\&. (example: bookmark\-cmd "~/bin/delicious\-bookmark\&.sh") + +.TP +\fIbrowser\fR (parameters: <browser\-command>; default value: \fIlynx\fR) +Set the browser command to use when opening an article in the browser\&. (example: browser w3m) + +.TP +\fIcache\-file\fR (parameters: <path>; default value: \fI"~/\&.newsbeuter/cache\&.db"\fR) +This configuration option sets the cache file\&. This is especially useful if the filesystem of your home directory doesn't support proper locking (e\&.g\&. NFS)\&. (example: cache\-file "/tmp/testcache\&.db") + +.TP +\fIcleanup\-on\-quit\fR (parameters: [yes/no]; default value: \fIyes\fR) +If yes, then the cache gets locked and superfluous feeds and items are removed, such as feeds that can't be found in the urls configuration file anymore\&. (example: cleanup\-on\-quit no) + +.TP +\fIcolor\fR (parameters: <element> <fgcolor> <bgcolor> [<attr> ...]; default value: \fIn/a\fR) +Set the foreground color, background color and optional attributes for a certain element (example: color background white black) + +.TP +\fIconfirm\-exit\fR (parameters: [yes/no]; default value: \fIno\fR) +If set to yes, then newsbeuter will ask for confirmation whether the user really wants to quit newsbeuter\&. (example: confirm\-exit yes) + +.TP +\fIdatetime\-format\fR (parameters: <date/time format>; default value: \fI%b %d\fR) +This format specifies the date/time format in the article list\&. For a detailed documentation on the allowed formats, consult the manpage of strftime(3)\&. (example: datetime\-format "%D, %R") + +.TP +\fIdefine\-filter\fR (parameters: <name> <filter>; default value: \fIn/a\fR) +With this command, you can predefine filters, which can you later select from a list, and which are then applied after selection\&. This is especially useful for filters that you need often and you don't want to enter them every time you need them\&. (example: define\-filter "all feeds with \fIfun\fR tag" "tags # \\\\"fun\\\\"") + +.TP +\fIerror\-log\fR (parameters: <path>; default value: \fI""\fR) +If set, then user errors (e\&.g\&. errors regarding defunct RSS feeds) will be logged to this file\&. (example: error\-log "~/\&.newsbeuter/error\&.log") + +.TP +\fIfeedlist\-format\fR (parameters: <format>; default value: \fI"%4i %n %11u %t"\fR) +This variable defines the format of entries in the feed list\&. See below for more information on format strings\&. (example: feedlist\-format " %n %4i \- %11u \-%> %t") + +.TP +\fIhtml\-renderer\fR (parameters: <path>; default value: \fIinternal\fR) +If set to "internal", then the internal HTML renderer will be used\&. Otherwise, the specified command will be executed, the HTML to be rendered will be written to the command's stdin, and the program's output will be displayed\&. This makes it possible to use other, external programs, such as w3m, links or lynx, to render HTML\&. (example: html\-renderer "w3m \-dump \-T text/html") + +.TP +\fIignore\-article\fR (parameters: <feed> <filterexpr>; default value: \fIn/a\fR) +If a downloaded article from <feed> matches <filterexpr>, then it is ignored and not presented to the user\&. This command is further explained in the "kill file" section below\&. (example: ignore\-article "*" "title =~ \\\\"Windows\\\\"") + +.TP +\fIinclude\fR (parameters: <path>; default value: \fIn/a\fR) +With this command, you can include other files to be interpreted as configuration files\&. This is especially useful to separate your configuration into several files, e\&.g\&. key configuration, color configuration, ... (example: include "~/\&.newsbeuter/colors") + +.TP +\fImacro\fR (parameters: <macro key> <command list>; default value: \fIn/a\fR) +With this command, you can define a macro key and specify a list of commands that shall be executed when the macro prefix and the macro key are pressed\&. (example: macro k open ; reload ; quit) + +.TP +\fImax\-items\fR (parameters: <number>; default value: \fI0\fR) +Set the number of articles to maximally keep per feed\&. If the number is set to 0, then all articles are kept\&. (example: max\-items 100) + +.TP +\fInotify\-program\fR (parameters: <path>; default value: \fI""\fR) +If set, then the configured program will be executed if new articles arrived (through a reload)\&. The first parameter of the called program contains the notification message\&. (example: notify\-program "~/bin/my\-notifier") + +.TP +\fInotify\-screen\fR (parameters: [yes/no]; default value: \fIno\fR) +If yes, then a "privacy message" will be sent to the terminal, containing a notification message about new articles\&. This is especially useful if you use terminal emulations such as GNU screen which implement privacy messages\&. (example: notify\-screen yes) + +.TP +\fInotify\-xterm\fR (parameters: [yes/no]; default value: \fIno\fR) +If yes, then the xterm window title will be set to a notification message about new articles\&. (example: notify\-xterm yes) + +.TP +\fIpodcast\-auto\-enqueue\fR (parameters: [yes/no]; default value: \fIno\fR) +If yes, then all podcast URLs that are found in articles are added to the podcast download queue\&. See below for more information on podcast support in newsbeuter\&. (example: podcast\-auto\-enqueue yes) + +.TP +\fIopml\-url\fR (parameters: <url>; default value: \fI""\fR) +If the OPML online subscription mode is enabled, then the list of feeds will be taken from the OPML file found on this location\&. (example: opml\-url "http://host\&.domain\&.tld/blogroll\&.opml") + +.TP +\fIproxy\fR (parameters: <server:port>; default value: \fIn/a\fR) +Set the proxy to use for downloading RSS feeds\&. (example: proxy localhost:3128) + +.TP +\fIproxy\-auth\fR (parameters: <auth>; default value: \fIn/a\fR) +Set the proxy authentication string\&. (example: proxy\-auth user:password) + +.TP +\fIrefresh\-on\-startup\fR (parameters: [yes/no]; default value: \fIno\fR) +If yes, then all feeds will be reloaded when newsbeuter starts up\&. This is equivalent to the \-r commandline option\&. (example: refresh\-on\-startup yes) + +.TP +\fIreload\-time\fR (parameters: <number>; default value: \fI60\fR) +The number of minutes between automatic reloads\&. (example: reload\-time 120) + +.TP +\fIsave\-path\fR (parameters: <path>; default value: \fI~/\fR) +The default path where articles shall be saved to\&. If an invalid path is specified, the current directory is used\&. (example: save\-path "~/Saved Articles") + +.TP +\fIshow\-read\-feeds\fR (parameters: [yes/no]; default value: \fIyes\fR) +If yes, then all feeds, including those without unread articles, are listed\&. If no, then only feeds with one or more unread articles are list\&. (example: show\-read\-feeds no) + +.TP +\fItext\-width\fR (parameters: <number>; default value: \fI0\fR) +If set to a number greater than 0, then all HTML will be rendered to this maximum line length\&. If set to 0, the terminal width will be used\&. (example: text\-width 72) + +.TP +\fIsuppress\-first\-reload\fR (parameters: [yes/no]; default value: \fIno\fR) +If yes, then the first automatic reload will be suppressed if auto\-reload is set to yes\&. (example: suppress\-first\-reload yes) + +.TP +\fIunbind\-key\fR (parameters: <key>; default value: \fIn/a\fR) +Unbind key <key>\&. This means that no operation is called when <key> is pressed\&. (example: unbind\-key R) + +.TP +\fIurls\-source\fR (parameters: <source>; default value: \fI"local"\fR) +This configuration command sets the source where URLs shall be retrieved from\&. By default, this is ~/\&.newsbeuter/urls\&. Alternatively, you can set it to "bloglines", which enables newsbeuter's Bloglines synchronization mode, or to "opml", which enables newsbeuter's OPML online subscription mode\&. (example: urls\-source "bloglines") + +.TP +\fIuse\-proxy\fR (parameters: [yes/no]; default value: \fIno\fR) +If yes, then the configured proxy will be used for downloading the RSS feeds\&. (example: use\-proxy yes) + +.TP +\fIuser\-agent\fR (parameters: <user agent string>; default value: \fI""\fR) +If set to a non\-zero\-length string, this value will be used as HTTP User\-Agent header for all HTTP requests\&. (example: user\-agent "Lynx/2\&.8\&.5rel\&.1 libwww\-FM/2\&.14") + +.SH "TAGGING" + + +Newsbeuter comes with the possibility to categorize or "tag", as well call it, RSS feeds\&. Every RSS feed can be assigned 0 or more tags\&. Within newsbeuter, you can then select to only show RSS feeds that match a certain tag\&. That makes it easy to categorize your feeds in a flexible and powerful way\&. + + +Usually, the /\&.newsbeuter/urls file contains one RSS feed URL per line\&. To assign a tag to an RSS feed, simply attach it as a single word, separated by blanks such as space or tab\&. If the tag needs to contain spaces, you must use quotes (") around the tag (see example below)\&. An example /\&.newsbeuter/urls file may look like this: + +.nf +http://blog\&.fefe\&.de/rss\&.xml?html interesting conspiracy news "cool stuff" +http://rss\&.orf\&.at/news\&.xml news orf +http://www\&.heise\&.de/newsticker/heise\&.rdf news interesting +.fi + + +When you now start newsbeuter with this configuration, you can press "t" to select a tag\&. When you select the tag "news", you will see all three RSS feeds\&. Pressing "t" again and e\&.g\&. selecting the "conspiracy" tag, you will only see the http://blog\&.fefe\&.de/rss\&.xml?html RSS feed\&. Pressing "^T" clears the current tag, and again shows all RSS feeds, regardless of their assigned tags\&. + + +A special type of tag are tags that start with the tilde character ("")\&. When such a tag is found, the feed title is set to the tag name (excluding the character)\&. With this feature, you can give feeds any title you want in your feed list: + +.nf +http://rss\&.orf\&.at/news\&.xml "~ORF News" +.fi + +.SH "SCRIPTS AND FILTERS" + + +From version 0\&.4 on, newsbeuter contains support for Snownews extensions\&. The RSS feed readers Snownews and Liferea share a common way of extending the readers with custom scripts\&. Two mechanisms, namely "execurl" and "filter" type scripts, are available and supported by newsbeuter\&. + + +An "execurl" script can be any program that gets executed and whose output is interpreted as RSS feed, while "filter" scripts are fed with the content of a configured URL and whose output is interpreted as RSS feed\&. + + +The configuration is simple and straight\-forward\&. Just add to your ~/\&.newsbeuter/urls file configuration lines like the following ones: + +.nf +exec:~/bin/execurl\-script +filter:~/bin/filter\-script:http://some\&.test/url +.fi + + +The first line shows how to add an execurl script to your configuration: start the line with "exec:" and then immediately append the path of the script that shall be executed\&. If this script requires additional parameters, simply use quotes: + +.nf +"exec:~/bin/execurl\-script param1 param2" +.fi + + +The second line shows how to add a filter script to your configuration: start the line with "filter:", then immediately append the path of the script, then append a colon (":"), and then append the URL of the file that shall be fed to the script\&. Again, if the script requires any parameters, simply quote: + +.nf +"filter:~/bin/filter\-script param1 param2:http://url/foobar" +.fi + + +In both cases, the tagging feature as described above is still available: + +.nf +exec:~/bin/execurl\-script tag1 tag2 "quoted tag" +filter:~/bin/filter\-script:http://some\&.test/url tag3 tag4 tag5 +.fi + + +A collection of such extension scripts can be found on this website: http://kiza\&.kcore\&.de/software/snownews/snowscripts/extensions + + +If you want to write your own extensions, refer to this website for further instructions: http://kiza\&.kcore\&.de/software/snownews/snowscripts/writing + +.SH "COMMAND LINE" + + +Like other text\-oriented software, newsbeuter contains an internal commandline to modify configuration variables ad hoc and to run own commands\&. It provides a flexible access to the functionality of newsbeuter which is especially useful for advanced users\&. + + +To start the commandline, type ":"\&. You will see a ":" prompt at the bottom of the screen, similar to tools like vi(m) or mutt\&. You can now enter commands\&. Pressing the return key executes the command (possibly giving feedback to the user) and closes the commandline\&. You can cancel entering commands by pressing the ESC key\&. Currently, the following commands are available: + +.TP +\fIquit\fR +Quit newsbeuter + +.TP +\fIsave\fR <filename> +Save current article to <filename> + +.TP +\fIset\fR <variable>[=<value>] +Set (or get) configuration variable value + +.TP +\fItag\fR <tagname> +Select a certain tag + +.TP +\fI<number>\fR +Jump to the <number>th entry in the current dialog + +.SH "FILES" + + +\fI$HOME/\&.newsbeuter/config\fR + + +\fI$HOME/\&.newsbeuter/urls\fR + +.SH "SEE ALSO" + + +podbeuter(1)\&. The documentation that comes with newsbeuter is a good source about the general use and configuration of newsbeuter\&. + +.SH "AUTHORS" + + +Andreas Krennmair <ak@synflood\&.at>, for contributors see AUTHORS file\&. + |