File: README

# README

Path: | README (CVS)
Last Update: | Sat Dec 10 19:48:47 EST 2005

Raggle 0.4.4 README

###### =============

This document was last updated on Sat Dec 10 19:48:26 2005. Please see the file COPYING for licensing and warranty information. The latest version of this software is available at the following URL: www.raggle.org/.

Table of Contents

###### ===========

- Introduction
- System Requirements o Console Interface o Web Interface
- Installation
- Getting Started
- Configuration Files
- Frequently Asked Questions
- Reporting Bugs
- Related Links
- About the Authors

Introduction

###### ======

Raggle is an RSS aggregator, written in Ruby (ruby-lang.org/). Raggle has two interfaces: a console interface and a (beta) web interface. Features include HTTP proxy, authentication, and conditional GET support, OPML import/export, themes, Syndic8 integration, feed categories, and support for various versions of RSS. The console interface also features customizable keybindings, basic HTML rendering, Screen support, and browser auto-detection. Raggle has been tested under Linux, OpenBSD, MacOS X, and Windows. It should work properly under most Unix variants. If this is the first time you’ve used Raggle, please read the "Getting Started" section below for a brief overview of the keyboard controls and command-line options.

System Requirements

###### =============

The libraries required to run Raggle vary depending on the interface you’re using. Here’s a list of requirements that are necessary regardless of interface:

      Name            Min Version URL
      ----            ----------- ---
      Ruby            1.8         http://ruby-lang.org/
      REXML           2.4         http://www.germane-software.com/software/rexml/
      YAML (or Syck)  0.49        http://www.yaml.org/ (or
                                  http://whytheluckystiff.net/syck/)

Both YAML and REXML are included in the Ruby 1.8 standard library, but some platforms (Debian Linux, for example), install them as separate packages. Here’s a list of optional libraries which Raggle will use if it can:

      Name              Used For
      ----              --------
      DRb               DRb interface (alpha status).
      FileUtils         Initial web interface setup.
      GetText-Ruby      Internationalization (i18n) support.
      Iconv             Character encoding conversions (RECOMMENDED).
      Ncurses-Ruby [*]  Required for Console interface.
      OpenSSL-Ruby      https support.
      WEBrick           Required for Web interface.
      xmlrpc4r          Syndic8 integration (Searching for feeds).
      Mysql-Ruby [*]    Saving bookmarks to MySQL table.
      SQLite-Ruby [*]   Saving bookmarks to SQLite database.

- These libraries are not included with the Ruby standard library; you’ll need to download them separately.

Except as marked, all of the libraries above are included with the Ruby standard library. Again, some platforms (eg Debian Linux) may split these libraries into separate packages. Ncurses-Ruby — which you’ll need to run the console interface — is available at the following URL:

      http://ncurses-ruby.berlios.de/

Note that you’ll need either Ncurses-Ruby or WEBrick depending the interface you’re using. Specific requirements for each interface are covered below.

System Requirements (Console Interface)

###### =================================

- NCurses-Ruby, version 0.7.1 (or newer): ncurses-ruby.berlios.de/

Raggle will run properly in an 80x25 terminal, but a slightly larger terminal (say, 80x35 or 80x40) is recommended.

System Requirements (Web Interface)

###### =============================

- WEBrick, version 1.2.3 (or newer) (note: WEBrick is included in the Ruby for Windows installer) www.webrick.org/

The Raggle web interface requires a web browser with support for CSS, frames, and JavaScript.

Installation

###### ======

The easiest way to install Raggle is to use a package for your system. There are Raggle packages available for Debian, Gentoo, FreeBSD, and Windows. If you’re determined to install Raggle from the tarball, read on.

The included Makefile will install the Raggle executable in a system- wide executable directory, install the Raggle documentation in the system-wide documentation directory, and install the Raggle data files in the system-wide data directory. Here’s the command:

      # install raggle, raggle docs, and raggle data
      sudo make install

or (if you don’t use sudo):

      # install raggle (but you don't use sudo; tsk tsk)
      su -c 'make install'

or (if you just want the executable):

      # install raggle (just the apps, ma'am)
      su -c 'cp ./raggle /usr/local/bin/'

or (if you don’t have root access, and only want it for personal use):

      # copy raggle to your personal executable directory
      cp raggle $HOME/bin/

Getting Started

###### =========

The Raggle display is divided into three windows: the Feed window (along the left side of the screen), the Item window (in the top-right corner), and the Description window (in the bottom-right corner). The Feed window contains a list of RSS feeds you’re currently subscribed to. I’ve included a handful of sample feeds to get you started raggling. If you’d like more feeds, you can import my feed list from the file "doc/pauls_feeds.opml.gz" with the following command:

      # try out a big feed list
      gzip -d < doc/pauls_feeds.opml.gz | raggle --import-opml -

Alternatively, there are several RSS feed directory and search engine links in the "Related Links" section below.

Working with Raggle is simple. Use the left and right arrow keys to navigate between windows. Press Enter or Space to select the highlighted item in the active window. To launch a browser and view an item, select the item, navigate to the Description window and press Enter. Several additional keyboard commands are described in the Raggle feed in Raggle, and in the Raggle man page.

To add a new RSS feed, press ‘a’, then type in the URL of the feed. Alternatively, you add a new RSS feed from the command-line:

      # add a new feed to raggle
      raggle --add "url"

Where "url" is the URL of the RSS feed. A complete list of feed editing commands is available in the Raggle man page, or by typing "raggle

[Validate]