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 an html file which contains tags that are parsed and replaced when loaded by voracious. The resulting html is what will be displayed in the browser. The following tags are recognized: $ALLNAVLINKS$ This will be replaced with a list of links to all defined paths. Each navlink will belong to the css class "navlink". $CLASS$ This will be replaced with the class name specified in the "[classes]" section of the configuration file for each feed item on the page. It will be ignored if it has not been set for a given feed. This may only appear in the section marked by "$ITEM$". $EDITLINK$ This will be replaced with the link to the configuration file editor. The link will belong to the css class "editlink". $ITEM$ This marks the beginning of a section which will be repeated for each item in a web feed. $/ITEM$ This marks the end of the "$ITEM$" section. $NAVLINKS$ This will be replaced with a list of links to defined paths rel‐ ative to the current path. This includes all immediate children and each parent in the hierarchy. Each navlink will belong to the css class "navlink". $SHUTDOWNFORM$ This will be replaced with a form consisting of a single button to shut down the server. $feed.foo$ This will be replaced with the "foo" attribute from the feed, where "foo" is any attribute recognized by the feedparser mod‐ ule, e.g. "feed.title". See the feedparser documentation for further details: http://www.feedparser.org/docs/ $entry.foo$ This will be replaced with the "foo" attribute from the entry, where "foo" is any attribute recognized by the feedparser mod‐ ule, e.g. "feed.title" or "feed.summary". See the feedparser documentation for further details: http://www.feed‐ parser.org/docs/ The default template file should make this section clearer and give you a good starting point to create your own custom tem‐ plates. Note that the template file will be reloaded while refreshing a page when changes are detected so you can experiment with it live. OPTIONS -h, --help Show the help message and exit --age-limit=AGE_LIMIT Limit the age of items in a feed to this many minutes. This option may be incorporated into the conguration file in the future. -b BIND, --bind=BIND Bind the server to this address. By default the server will only listen to "localhost" -c CONFIG_PATH, --config=CONFIG_PATH Set the configuration file path. This will be relative to the default directory unless it is an absolute path. -d DEFAULT_DIR, --dir=DEFAULT_DIR Set the default directory. -p PORT, --port=PORT Set the server port (default: 8080) --nobozo Ignore feedparser's "bozo" attribute, which flags malformed xml. --noedit Prevent editing and server shutdown from the browser interface. -i REFRESH_INTERVAL, --interval=REFRESH_INTERVAL Set the feed retrieval interval, in minutes (default: 15). Feeds will be updated when this much time has passed and the page is refreshed. --include-dir=INCLUDE_DIR The include directory for local page content, such as css style sheets, javascript and images. This will be relative to the default directory unless it is an absolute path. If not set, all requests for local content will be ignored. --password=PASSWORD Set authentication password. --proxy=PROXY Use an http proxy to retrieve feeds. This should be specified as "http://example.com:8080". -t TEMPLATE_PATH, --template=TEMPLATE_PATH Set the default template file path. This will be relative to the default directory unless it is an absolute path. --tm-fmt=TM_FMT Set the time format (default: "%A %Y-%m-%d %H:%M"). See the documention for Python's time.strftime() function. -u USERNAME, --username=USERNAME Set authentication username. AUTHORS Xyne November 2009 VORACIOUS(1)