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:
http://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 (http://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):
  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, 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
--help".  If you'd like to import an OPML file (often referred to as a 
"blogroll"), press shift-O and type in the URL or path of the OPML file.
You can also import OPML files from the command-line by using the
following command:

  # import OPML file "my_blogroll.opml" into raggle
  raggle --import-opml my_blogrole.opml

To find a feed, press f, type in a couple of words to search for, and
press Enter.  Raggle will search for matching RSS feeds using Syndic8
(http://syndic8.com/), and open a new window with the results (note:
this can take a minute or two if the phrase returns a lot of results, so
be specific!).  Once the search window opens, press hilight and feed and
press Enter to add it to your feed list.  You can also search for RSS
feeds from the command- line.  For example, if here's how I would find
the RSS feed for my personal page (http://paulduncan.org/) from the
command-line:

  # find RSS feed for paulduncan.org using Raggle:
  raggle --find paulduncan
   1. Paul Duncan - http://paulduncan.org/rss/

And that's it!  Don't worry about remembering the keys for everything
before running Raggle, you can press ? at any time to view a list of the
current key bindings. If you have any questions or comments about
Raggle, feel free to subscribe to the Raggle mailing list, or email
Richard, Ville, Thomas, 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
your Raggle settings, browse through the default configuration
(the file is located in "doc/default_config.rb", but you can also see
Raggle's default settings by typing "raggle --default-config"), then 
create a file called "config.rb" in your raggle configuration directory
("$HOME/.raggle") 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.  This feed doesn't work with Raggle.  What gives?
A.  A lot of feeds either aren't well-formed XML or specify an  invalid 
    character encoding.  REXML, the XML parser used by Raggle, is a
    strict, non-validating XML parser, which means it's picky about
    both.  Raggle will refuse to parse feeds that aren't well-formed
    XML, and it may or may not work correctly on feeds with an incorrect
    character encoding.  If you're on a Unix machine, you can use
    XMLLint (http://xmlsoft.org/xmllint.html) to check both, like so:

      # replace $url with the feed URL
      wget -qO- "$url" | xmllint --output /dev/null -

    Any output from xmllint means the feed isn't valid XML, and may not
    work correctly with Raggle.  It fact, it probably won't work
    correctly in other RSS aggregators either.  Errors like this should
    probably be passed on to the feed author.
    
    If the feed parses correctly in XMLLint, try passing it through Feed
    Validator (http://feedvalidator.org/).  If there are errors here,
    these should be forwarded on to the feed author.

    If the feed passes Feed Validator, then it's probably a bug in
    Raggle.  See the "Reporting Bugs" section below for instructions on
    submitting a bug report.

Q.  Can I update Raggle from the command-line or from a cron job?
A.  Yes, as of version 0.4.4.  See the documentation on the --update
    command-line option.

Q.  Can I use more than one browser with Raggle?
A.  Yes, with a little bit of config file magic.  Out of the box, Raggle
    only supports one browser.  However, the instructions at the 
    following URL will allow you to select a browser when opening a
    URL, or bind an alternate browser to a different URL:

      http://raggle.org/files/alternate_browser/alternate_browser_email.txt


Reporting Bugs
==============
Have a bug to report or a feature you'd like added to Raggle?  Feel free
to email me at the address below.  Alternatively, you can submit your
feature request or bug directly to my bug-tracking web interface at the
following URL:

  http://bugs.pablotron.org/

(note that you'll need to create an account in order to submit a feature
request or a bug report via the web interface).


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://syndic8.com/
  http://newsisfree.com/
  http://blogstreet.com/rssdiscovery.html
  http://feedster.com/

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

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


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

Richard Lowe <richlowe@richlowe.net>
http://richlowe.net/

Ville Aine <vaine@cs.helsinki.fi>

Thomas Kirchner <redshift@halffull.org>
http://halffull.org/  (RSS: http://halffull.org/feed/rss/)

See the file AUTHORS for additional contributions.
