=head1 NAME

raggle - Console RSS aggregator.

=head1 SYNOPSIS

B<raggle>
[B<-aAhlvV>] 
[B<--add> [I<url>]] 
[B<--ascii>]
[B<--default-config>]
[B<--diag>]
[B<--force>] 
[B<--help>] 
[B<--list>]
[B<--lock-title>]
[B<--purge>] 
[B<--save-items>]
[B<--server> [I<port>]]
[B<--sort>]
[B<--unlock-title>]
[B<--unsave-items>]
[B<--usage>]
[B<--verbose>]
[B<--version>]
[B<-c> I<file>]
[B<--config> I<file>]
[B<-d> I<feed>]
[B<--delete> I<feed>]
[B<-e> I<feed>]
[B<--edit> I<feed>]
[B<--export-opml> I<file>]
[B<-f> I<string>]
[B<--find-feeds> I<string>]
[B<--import-opml> I<file>/I<uri>]
[B<-i> I<feed>]
[B<--invalidate> I<feed>]
[B<--max> I<num>]
[B<-p> I<priority>]
[B<--priority> I<priority>]
[B<-r> I<refresh_time>]
[B<--refresh> I<refresh_time>]
[B<-t> I<title>]
[B<--title> I<title>]
[B<-u> I<url>]
[B<--url> I<url>]
[B<--U> I<feed>]
[B<--update> I<feed>]

=head1 DESCRIPTION

B<raggle> is a curses-based RSS aggregator.

The following options are available:

=over 5

=item B<-a> [I<url>]  B<--add> [I<url>]

Add a new feed.  You can optionally specify I<url>, otherwise
it requires B<--url>.

=item B<-A>  B<--ascii>

Use ASCII graphics for windows.

=item B<-c> I<file>  B<--config> I<file>

Use I<file> as an alternate configuration file.

=item B<-d> I<feed>  B<--delete> I<feed>

Delete I<feed> from the feed list.

=item B<--default-config>

Print out the default configuration of Raggle in a format suitable for
your config.rb file.

=item B<--diag>

Print out full stack traces, and other diagnostic information
intended for bug hunting.

=item B<-e> I<feed>  B<--edit> I<feed>

Edit I<feed>'s information.

=item B<--export-opml> I<file>

Export all feeds to I<file> in OPML format.

=item B<-f> I<string>  B<--find> I<string>

Find a feed containing I<string> (uses Syndic8).

=item B<--force>

Force an edit/addition to succeed even if it wants to do things
that are generally unwise.

=item B<-h>  B<--help>  B<--usage>

Show usage information.

=item B<--import-opml> I<file>/I<uri>

Import feeds from an OPML format I<file> or I<uri>.

=item B<-i> I<feed>  B<--invalidate> I<feed>

Invalidate I<feed> (force it to be refreshed). If -1 is given as
I<feed> then all feeds are updated.

=item B<-l>  B<--list>

List current feeds.  Use -v or --verbose to display extra info.

=item B<--lock-title>

Lock the title of a feed (blocks updating of a feed's title from
data in the feed itself), used with B<--add> or B<--edit>.

=item B<--max> I<num>

Set the maximum number of items in a feed to I<num>.  Automatically sets
--save-items.

=item B<-p> I<priority>  B<--priority> I<priority>

Set the feed priority to I<priority>.  0 is the default, higher values will
sort a feed closer to the top.

=item B<--purge>

Purge deleted feeds from the feed cache.

=item B<-r> I<refresh_time>  B<--refresh> I<refresh_time>

Set a feed's refresh time to I<refresh_time>; used with B<--add>
or B<--edit>.

=item B<--save-items>

Save all old items from a feed rather than replacing them with newly fetched ones; used with B<--add> or B<--edit>.

=item B<--server> [I<port>]

Run Raggle in HTTP server mode, optionally specifying a I<port>.

=item B<--sort>

Sort feed list by priority then by title, case-insensitive.

=item B<-t> I<title>  B<--title> I<title>

Set a feed's title to I<title>, used with B<--add> or B<--edit>.

=item B<--unlock-title>

Reverse the actions of B<--lock-title>, causing it to be updated
from the title stored in the RSS feed; used with B<--add> or
B<--edit>.

=item B<--unsave-items>

Reverse the actions of B<--save-items>, cause old items to be
removed from the feed cache; used with B<--add> or B<--edit>.

=item B<-U> I<feed>  B<--update> I<feed>

Update the specified feed (or I<all> for all feeds).

=item B<-u> I<url>  B<--url> I<url>

Set the URL from which to retrieve a feed to I<url>, used with
B<--add> or B<--edit>.

=item B<-v>  B<--verbose>

Turns on verbose output, displaying extra info on the command
line.

=item B<-V>  B<--version>

Show B<raggle> version.

=back

=head1 KEYS: MOTION

=over 5

=item I<F12>, I<q>

Quit B<raggle>

=item I<Right Arrow>, I<Tab>, I<l>

Move to the next window.

=item I<Left Arrow>, I<h>

Move to the previous window.

=item I<Up Arrow>, I<k>

Scroll up.

=item I<Down Arrow>, I<j>

Scroll down.

=item I<End>, I<$>, I<G>

Scroll to bottom.

=item I<Home>, I<0>, I<g>

Scroll to top.

=item I<PageUp>

Scroll up one page.

=item I<PageDown>

Scroll down one page.

=head1 KEYS: INTERACTION

=item I<Return>, I<Space>

Select item.

=item I<o>

Open the current feed or item's link in your browser.

=item I<1> through I<9>

Open a link from the current story in your browser.  Link numbers are given
at the bottom of the description window.

=item I<u>

Move item up.

=item I<d>

Move item down.

=item I<a>

Add a feed.  Will add the currently selected feed after a search
via I<f>, otherwise you will be prompted for the address.

=item I<O>

Import or export an OPML copy of your feed list.  If the given name is
an existing file or a URI, it will be imported; otherwise, a new OPML
file will be created with the given name.

=item I<e>

Edit the current feed's options to your liking.

=item I<I>

Invalidate the current feed, causing a refresh.

=item I<Delete>

Delete feed or item.

=item I<y>

Undelete all items in the current feed.

=item I</>

Find an entry.

=item I<f>

Search for a feed via Syndic8.

=item I<p>

Select previous unread item.

=item I<n>

Select next unread item.

=item I<m>

Mark all items as read.

=item I<M>

Mark all items as unread.

=item I<N>

Mark current item as unread.

=item I<s>

Sort list.

=item I<r>

Lower the current feed's sorting priority.

=item I<R>

Raise the current feed's sorting priority.

=item I<c>

Select a feed category to view.

=item I<C>

Close the current window.

=head1 KEYS: SYSTEM

=item I<!>

Run a shell in the foreground (exit from it to get back to B<raggle>)

=item I<?>

Show current key bindings.

=item I<\>

View item source.

=item I<U>

Start a manual update of feeds.

=item I<S>

Start a manual save of feeds and configuration.

=item I<C-l>

Redraw the screen.

=head1 EXAMPLES

Add a feed called "Bar" updating every 2 hours.
    $ raggle --add -t Bar --url http://foo.com/bar.rss --refresh 120

Add a feed called "Baz" that will sort to the top.
    $ raggle -a -t "Baz" -u http://foo.com/baz.rss --priority 10

Change the refresh time of the "Bar" feed to update every hour.
    $ raggle --edit 1 --refresh 60

Don't update feed #1's title from the RSS.
    $ raggle -e 1 --lock-title

Keep old items associated with feed #16.
    $ raggle -e 16 --save-items

Update feed #1's title from the RSS info.
    $ raggle -e 1 --unlock-title

Change the URL of feed #3.
    $ raggle -e 3 -u http://www.slashdot.org/slashdot.rss

Export all feeds to foo.opml
    $ raggle --export-opml foo.opml

Import all feeds from foo.opml, and set their refresh time to
90 minutes.
    $ raggle --import-opml foo.opml -r 90

Import all feeds from foo.opml, and set their refresh time to
90 minutes.
    $ raggle --import-opml foo.opml -r 90

Find feed matching the string "halffull"
    $ raggle --find halffull

=head1 ENVIRONMENT

=item B<BROWSER>

Used to find a suitable web browser (see B<RAGGLE_BROWSER>).

=item B<HOME>

Used to find the Raggle configuration directory.

=item B<http_proxy>

HTTP Proxy server, in the format "http://I<host>:I<port>/".

=item B<no_proxy>

Comma-delimited list of hosts and domains to connect directly to
(only applicable if you're using an HTTP proxy).

=item B<PATH>

Used to find a suitable web browser (see B<RAGGLE_BROWSER>).

=item B<RAGGLE_BROWSER>

Path to the web browser Raggle should use when a feed item is 
opened.  If B<RAGGLE_BROWSER> isn't set, Raggle checks 
B<BROWSER>, then looks for common command-line browsers in B<PATH>.
Note: this behavior can be overridden by setting the 'browser' 
config directive in your Raggle configuration file.

=item B<RAGGLE_WEB_DATA>

Used to find the web interface data files.  If it's not set, 
Raggle looks for a directory called "web_ui" in the configuration 
directory. 

=item B<SHELL>

Shell to launch when invoking a sub-shell.

=item B<WINDOW>

Used to determine if Raggle is running in screen.

=head1 BUGS

=item B<*>

Pressing Ctrl-C while adding a feed will cause Raggle to exit 
unexpectedly, not cancel.

=item B<*>

It's possible that feeds.yaml will be mistakenly written as an
Array rather than a FeedList for no apparent reason.

=item B<*>

Possibly more!  Please report any you find to <I<raggle-dev@raggle.org>>

=head1 HISTORY

=item
B<raggle> 0.1 was released on 23 Jun, 2003

=item
B<raggle> 0.2 was released on 17 Aug, 2003 

=item
B<raggle> 0.3 was released on 20 Feb, 2004

=item
B<raggle> 0.4 was released on 15 Mar, 2005

=head1 AUTHORS

=item
Paul Duncan <I<pabs@pablotron.org>>,

=item
Richard Lowe <I<richlowe@richlowe.net>>,

=item
Ville Aine <I<vaine@cs.helsinki.fi>>,

=item
Thomas Kirchner <I<redshift@halffull.org>>