voracious

2014-10-12 23:17 UTC
  • Xyne

Metadata

Description:

A customizable web feed aggregator for your browser.

Latest Version:

2012.12.24.1

Architecture:

  • any

Dependencies:

Arch Repositories:

  • [xyne-any]
  • [xyne-i686]
  • [xyne-x86_64]

AUR ID:

32156

Arch Forum ID:

85305

Tags:

About

Voracious is a customizable web feed aggregator for your browser. Please read the man page for more information.

The following references will be useful for customizing the template:

Certificate Generation

See the python2-xynehttpserver page for references and commands to generate certificates for HTTPS connections.

Examples

Here's a simple example that shows how to use the $CLASS$ tag to assign colors to different feeds.

Configuration File

[paths]
/
/example
  http://feeds.arstechnica.com/arstechnica/index
  http://www.archlinux.org/feeds/news/
  http://www.merriam-webster.com/word/index.xml
  http://xkcd.com/rss.xml



[classes]
arch
  archlinux
ars
  arstechnica
slashdot
  slashdot
xkcd
  xkcd

Default Template File

<template>
  <head>
  </head>
  <body>
    <h1>Voracious</h1>
    <voracious_navbar />
    <voracious_entry type="entry" voracious_class="CLASS" voracious_id="ENTRY_ID">
      <div>
        <div class="header">
          <a voracious_href="entry.link">
            <voracious_text value="entry.title" />
          </a>
        </div>
        <div class="meta">
          <a voracious_href="feed.link">
            <voracious_text value="feed.title" />
          </a>
          <voracious_text value="entry.date_parsed" />
        </div>
        <div class="summary">
          <voracious_text value="entry.summary; entry.content" />
        </div>
      </div>
    </voracious_entry>
  </body>
</template>

Template File With Javascript

<template>
  <head>
  </head>
  <body>
    <script type="text/javascript" src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
    <script type="text/javascript"><![CDATA[

      $(document).ready(function(){
      alert("hello");
      });

    ]]></script>
    <h1>Voracious</h1>
    <voracious_navbar />
    <voracious_entry type="entry" voracious_class="CLASS">
      <div>
        <div class="header">
          <a voracious_href="entry.link">
            <voracious_text value="entry.title" />
          </a>
        </div>
        <div class="meta">
          <a voracious_href="feed.link">
            <voracious_text value="feed.title" />
          </a>
          <voracious_text value="entry.date_parsed" />
        </div>
        <div class="summary">
          <voracious_text value="entry.summary; entry.content" />
        </div>
      </div>
    </voracious_entry>
  </body>
</template>

Template File With Embedded Pages

<template>
  <head>
  </head>
  <body>
    <h1>Voracious</h1>
    <voracious_navbar />
    <voracious_entry type="entry" voracious_class="CLASS">
      <div>
        <div class="header">
          <a voracious_href="entry.link">
            <voracious_text value="entry.title" />
          </a>
        </div>
        <div class="meta">
          <a voracious_href="feed.link">
            <voracious_text value="feed.title" />
          </a>
          <voracious_text value="entry.date_parsed" />
        </div>
        <object voracious_data="entry.link" width="100%" height="400">
          <embed voracious_src="entry.link" width="100%" height="400"> </embed>
          Error: Embedded data could not be displayed.
        </object>
      </div>
    </voracious_entry>
  </body>
</template>

Submitted Changes

You can find changes submitted by others that have not yet been incorporated into Voracious here.

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 multiple 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 automatically. 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://localhost: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 brackets. 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 aggregate 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://localhost: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 recognizable. This section follows the same format as the "[options]" section 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 following 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 certain 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 feedparser documentation should make this clear: http://www.feedparser.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.

Screenshots

Here are some screenshots using the default template file. Note that these are just basic examples and that you can fully customize both the display and the content of all feeds.

screenshot screenshot screenshot screenshot 

Help Message

$ voracious --help

Usage: voracious [options]

voracious - an RSS feed aggregator and miniserver. See the man page for
further details.

Options:
  -h, --help            show this help message and exit
  -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.
  --nobozo              Ignore feedparser's "bozo" attribute, which flags
                        malformed xml.
  --noedit              Allow configuration file editing via HTML.
  -i REFRESH_INTERVAL, --interval=REFRESH_INTERVAL
                        Set the feed retrieval interval, in minutes (default:
                        15). Feeds will be updated during the next request
                        after this much time has passed.
  --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, with the exception of the
                        default CSS file.
  --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.
  --threads=THREADS     Set the number of threads to use when retrieving
                        feeds.
  --tm-fmt=TM_FMT       Set the time format (default: "%A %Y-%m-%d %H:%M").
                        See the documention for Python's time.strftime()
                        function.

  Server Address and Port:
    Configure the server's listening address and port.

    -b ADDRESS, --bind=ADDRESS
                        Bind the server to this address. By default the server
                        will listen on all interfaces.
    -p PORT, --port=PORT
                        Set the server port (default: 8080)

  HTTP Authentication:
    HTTP digest authentication via a username and password.

    --username=USERNAME
    --password=PASSWORD
    --authfile=AUTHFILE
                        The path to a file containing a username on the first
                        line and a password on the second line. This can be
                        used if you do not want to type the password on the
                        command line when starting the server, e.g. to prevent
                        it from being displayed with "ps aux".

  SSL (HTTPS):
    Wrap sockets in SSL for encrypted connections. Simply enabling SSL
    does not guarantee a secure connection and it is the user's
    responsibility to check that the implementation is correct and secure
    and that the server is properly configured. You can find information
    about generating self-signed certificates in the OpenSSL FAQ:
    http://www.openssl.org/support/faq.html

    --ssl               Enable SSL (HTTPS).
    --certificate=path  Set the path to the server's certificate.
    --key=path          Set the path to the server's key.
    --req-cert          Require a certificate from the client.
    --ca-certs=path     Set the path to a file containing concatenated CA
                        certificates for verifying the client certificate.
                        This defaults to the server's own certificate.

  Logging:
    Log messages are printed to STDERR by default. You can easily redirect
    these to a file by appending "2>/path/to/file" to the end of the
    command, e.g. "<cmd> 2>/path/to/log".

CHANGELOG

2011.04.05

  • (re-)added support for head tags in the template file
  • added support for Javascript script tags

2011.04.02

  • added etag and last-modified support
  • ended up rewriting most of the code
  • more modular
  • cleaner code (although I'm probably too tired to tell)
  • 34% more Leprechauns
  • completely changed template parsing

2010.10.02

  • added support for requiring client certificates
  • made minor changes to the default template
  • wrapped navlinks in a proper list

2010.09.18

2010-08-17

  • Corrected "bug" in template file: $entries.*$ is now $entry.*$, as originally intended.
  • Included some changes submitted or inspired by Ben Holroyd
    • parameterized feed and entry tags
      • fallback content
      • maximum content length
    • avoid parsing tags inside HTML comments in template file

The parameterized tags use a CSS-like syntax, e.g. $value:entry.summary;max:100$. Check the man page for details.

If you are using the default template file, simply delete it and Voracious will create a new version. The default template file is located at $XDG_CONFIG_HOME/voracious/template.htm, or ~/.config/voracious/template.htm if $XDG_CONFIG_HOME is not set.

Contact
echo xyne.archlinux.ca | sed 's/\./@/'
Feeds
Blog News
Validation
XHTML 1.0 Strict CSS level 3 Atom 1.0