VORACIOUS(1) VORACIOUS(1) NAME Voracious - a customizable web feed aggregator for your browser. SYNOPSIS voracious [options] DESCRIPTION Voracious is a web feed aggregator with an http server backend that you can access through your web browser. It is intended to organize multi‐ ple feeds into coherent categories for quicker browsing with a better overview. For example, you could easily create a single webpage with links and summaries to articles on several of your favorite news sites. Voracious is customizable through the use of a template file which allows you to choose which information is displayed and how. See the template file section below for details. Voracious also offers a degree of privacy by retrieving feeds only when requested unlike most browsers which retrieve all of your feeds auto‐ matically. This will prevent servers from being able to log when you are online even when you are not actively browsing their content. Speed is not an issue though as voracious uses multiple threads to retrieve feeds and stores them internally for fast access once they have been downloaded. Feeds will be redownloaded after a timeout interval when they are again requested by the user. USAGE To use voracious, simply run it from a console and then navigate to the server in your browser. The default address will be "http://local‐ host:8080/". You will first need to add some paths and feed urls to the configuration file, which you can do by following the "edit" link. Once you have added a path, you can navigate to it to display the feeds, e.g. "http://localhost:8080/example". The navbar will also contain links to all defined paths. DEFAULT CONFIGURATION DIRECTORY The default configuration directory is '$XDG_CONFIG_HOME/voracious". If "$XDG_CONFIG_HOME" is not set, it will use "~/.config/voracious" instead. CONFIGURATION FILE The configuration file has three sections which are marked with brack‐ ets. The first section, "[paths]", specifies a server path and the feeds which should be aggregated under that path. Each path is placed at the beginning of its own line and feed urls which it should aggre‐ gate are indented on separate lines following it. For example, [options] /example http://example.com/rss/1.xml http://example.com/rss/2.xml http://example.com/rss/3.xml would create a server path under "/example" which would combine all three feeds. You could then view them by navigating to "http://local‐ host:8080/example" in your browser. Note that all paths begin with "/". The second section, "[classes]", will associate css classes with feeds so that you can use the "$CLASS$" tag in the template file to customize the page style. For example, you could use it to associate different colors with differents feeds to make them more distinctive and recog‐ nizable. This section follows the same format as the "[options]" sec‐ tion except that instead of plain urls, regular expressions are used: [classes] example example blue example.*1.xml red example.*[23].xml See the template file section below for more details. The third section, "[templates]", will associate different template files with paths matching the regular expressions: [templates] headlines_template.htm /news.* summaries_template.htm /blogs.* The configuration file will be reloaded if it is changed while the server is running so you can update it without restarting voracious. TEMPLATE FILE The template file is a custom XHTML file that contains special tags and attributes that are parsed and replaced when loaded by voracious. The interpolated XHTML is what will be displayed in the browser. The fol‐ lowing body tags are recognized, all of which begin with "voracious_: element: voracious_navbar This will be replaced with a navigation list for the current path. element: voracious_entry This element will be cloned for each entry in the aggregated feed entries. For each entry, it will interpolate the nested elements using the data from that entry, so that it will expand to a list of elements. element: voracious_text This element will be replaced with the interpolated value of its "value" attribute, as a text node. If the attribute "max_length" is set, it will crop the output if it is too long. all attributes The value of any attribute with the prefix "voracious_" will be interpolated, then the prefix will be removed and the value will be appended to the new name. The best example is the CLASS interpolation: to . This can be used to customize individual feeds using the classes section of the configuration file. It can also be used for "href" attributes via "voracious_href". These explanations may not seem very clear, but a quick look at the default template file and a bit of experiementation should show just how simple it actually is. The template file also supports additional head tags. These will not be interpolated, but they can be used to add Javascript and additional content to the page, such as favicons and external style sheets. INTERPOLATION Value strings passed to the interpolation function are split into lists using ";" as a separator. An attempt is made to interpolate each item in the list. As soon as one succeeds, the new value is returned. This enables the template file to specify "defaults" when a feed lacks cer‐ tain attributes, e.g. "entry.title ; feed.title" would return the entry's title if present, otherwise the feed title, or nothing at all if that too is missing. White-space is ignored in the list. feedparser attributes Most interpolations rely on attributes from the feedparser's feed and entry objects. For example, "feed.title" would be expanded to the feed's title, while "entry.title" would be expanded to the entry's title. The template file and the feed‐ parser documentation should make this clear: http://www.feed‐ parser.org/docs/ CLASS This will be replaced by a class string as determined by the configuration file. ENTRY_ID This will be replaced by "voracious_entry_x" where "x" is the number of the entry on that page. This can be used to create a table of contents or navigate with Javascript. OPTIONS See "voracious --help" for information about the available command-line options. AUTHORS Xyne April 2011 VORACIOUS(1)