Raggle 0.3.2 README
===================

This document was last updated on Sat Apr 17 11:44:05 2004.
Please see the file COPYING for licensing and warranty information.  The
latest version of this software is available at the following URL:
http://www.raggle.org/.

Table of Contents
=================
* Introduction
* System Requirements
  o Console Interface
  o Web Interface
* Installation
* Getting Started
* Configuration Files
* Frequently Asked Questions
* Related Links
* About the Authors


Introduction
============
Raggle is a RSS (RDF Site Summary) aggregator, written in Ruby
(http://www.ruby-lang.org/).  Raggle has two interfaces: a console
interface and an alpha web interface.  Features include HTTP proxy
support, OPML import/export, themes, 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
===================
* Ruby, version 1.6.8 (or newer), or 1.8.0 (or newer):
  http://www.ruby-lang.org/
* REXML, version 2.4.0 (or newer) (included in Ruby 1.8.x):
  http://www.germane-software.com/software/rexml/
* YAML support
  Either:
    o YAML-Ruby, version 0.49.1 (or newer):
      http://www.yaml.org/ 
    o Syck, version 0.35 (included in Ruby 1.8.x)
      http://whytheluckystiff.net/syck/ 

You'll also need either Ncurses-Ruby or WEBrick depending the Raggle
interface you're using.  Requirements for each interface are covered
below.


System Requirements (Console Interface)
=======================================
* NCurses-Ruby, version 0.7.1 (or newer):
  http://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)
  http://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, and FreeBSD.  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, and install
the Raggle themes.  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 "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
--help".

And that's it!  If you have any questions or comments about Raggle, feel
free to subscribe to the Raggle mailing list, or email Richard, Ville,
or myself; our email addresses are available in the "About the Authors"
section below.


Configuration Files
===================
  $HOME/.raggle/config.rb          - main configuration file
  $HOME/.raggle/feeds.yaml         - feed list
  $HOME/.raggle/feed_cache.store   - cached feed items
  $HOME/.raggle/theme.yaml         - colors, window layout
  $HOME/.raggle/web_ui/            - web interface

Raggle will fall back to internal defaults if any of these files are
deleted, or if they don't exist.  The feed list, feed cache, and theme
files are automatically regenerated by Raggle; the main configuration
file is not (although it is not required).  If you'd like to change
Raggle defaults, browse through the default configuration file 
("doc/default_config.rb"), then create a file called "config.rb" in
your raggle configuration directory containing the settings you'd like
to override.  For example, here's how you'd change the default focus
mode:

  # change focus mode from 'auto' to 'select'
  # (warning: this command over-writes your existing config file!)
  echo "\$config = { 'focus' = 'select' }" > $HOME/.raggle/config.rb

Unlike previous versions of Raggle, you don't need to copy the entire
config in order to make changes.  The config file only needs to contain
sections you're overriding from the defaults.  Here's what my config
file looks like:

  ########################
  # Paul's Raggle config #
  ########################
  $config = {
    # force focus mode to auto 
    'focus'       => 'auto',
    
    # enable proxy (also configurable via ENV['http_proxy'])
    'proxy'       => {
      'host'      => 'proxy',
      'port'      => 3128,
      'no_proxy'  => nil,
    },
    
    # my funky browser config
    'browser_cmd' => [ '/home/pabs/bin/umbilic.rb', 'open_uri', '%s'],
    
    # enable parallel feed grabbing
    'grab_in_parallel'  => true,
    'max_threads'       => 5,
  }


Note: In Windows, these files are all stored in %USERPROFILE%\.raggle\,
except for web_ui, which is located in "C:\Program Files\Raggle\web_ui\".


Frequently Asked Questions
==========================
Q.  Raggle shows up in black and white?  Where's the color?
A.  You're probably running Raggle in a vt100 terminal.  Try setting the
    terminal to 'xterm'.  In Bourne-derived shells (sh, bash, zsh, etc),
    do this:

      # set the terminal type to xterm
      TERM='xterm'
      export TERM
      raggle

    and in csh-derived shells, do the following:

      setenv TERM 'xterm'
      raggle

    Note for OSX users: The latest versions of OSX use bash as the
    console, _not_ tcsh.

Q.  I get funny characters instead of lines for my window borders.  How
    do I fix this?
A.  Your terminal font doesn't contain the ANSI characters Ncurses uses to 
    draw lines.  Either switch fonts or run Raggle with the --ascii (-A)
    command-line flag.

Q.  When I resize the terminal window, Raggle doesn't change size
    immediately.  How do I fix this?
A.  You can't, at least not at the moment.  We know about this problem,
    but we can't fix it until we have a proper way to handle Ncurses
    events without blocking the entire application (and stopping the
    feed grabbing threads).


Related Links
=============
* RSS Information:
  http://www.xml.com/pub/a/2002/12/18/dive-into-xml.html
  http://backend.userland.com/rss

* RSS Feed Directories / Search Engines:
  http://www.syndic8.com/
  http://www.newsisfree.com/
  http://www.blogstreet.com/rssdiscovery.html
  http://www.feedster.com/

* RSS Aggregators (all of which pale in comparison to Raggle :-D):
  http://blogspace.com/rss/readers
  http://www.bloglines.com/
  http://www.newsgator.org/

* Ruby Links:
  http://www.ruby-lang.org/
  http://raa.ruby-lang.org/
  http://www.rubygarden.org/
  http://www.rubycentral.com/


About the Authors
=================
Paul Duncan <pabs@pablotron.org>
http://www.pablotron.org/  (RSS: http://www.pablotron.org/rss/)
http://www.paulduncan.org/ (RSS: http://www.paulduncan.org/rss/)

Richard Lowe <richlowe@richlowe.net>
http://www.richlowe.net/ (RSS: http://www.richlowe.net/index.cgi/index.rss)

Ville Aine <vaine@cs.helsinki.fi>

See the file AUTHORS for additional contributions.
