# $Dwarf: README,v 1.4 2002/07/03 19:09:39 ward Exp $
# $Source$

Ripnews is a bulk downloader for usenet. It's quite flexible in terms of
configuration. Some of it's features are:

- basic support for multiple servers per group
- cacheing of article headers to speed up reading of newsgroups
- newsrc file support (one newsrc file per server)
- flexible but simple configuration

Configuration:
==============

I'll just give a commented example config, it should be pretty clear,
after that I'll list the possible options.

<== cut here ==>
# Set the default NNTPSERVER to localhost
NNTPSERVER=localhost

# Set the cachedir, this is where the subject caches are stored
# without this ripnews will be much slower (but should still work)
CACHEDIR=/mnt/newspace/News/.ripnews_caches

# Set the datadir, this where a subdir for each group will be made to
# store the ripped articles
DATADIR=/mnt/newspace/News

# Set the tempdir, used to store the undecoed data. Without this ripnews
# uses a lot more memory
TEMPDIR=/mnt/newspace/News/ripnews_temp

# Set include pattern to a case insensitive "bad religion"
OPT_I=(?i)bad religion

# Set the base newsrc name. The server name will be appended.
NEWSRCNAME=/ward/src/ruby/ripnews/.newsrc

# Set the permission to create subdirs with
PERMISSION=0700

# For alt.binaries.e-book.technical change from defaults...
alt.binaries.e-book.technical {
	# Set another include pattern
	OPT_I=(?i)reilly
}

alt.binaries.e-book.flood {
	# Add to default pattern, this will not be case insensitive
	# anymore, cause that's how ruby patterns work
	OPT_I+=|douglas adams
}

# For both alt.binaries.e-book.technical and alt.binaries.e-book.flood
# change some value
alt.binaries.e-book.technical| \
alt.binaries.e-book.flood {
	# Sets long filenames. If this is set the subject will be used
	# as a filename instead of the name specified in the encoding.
	OPT_L = true
}

# Change default server to news.tilbu1.nb.nl.home.com, since the config
# is parse in order this will be used from her on down
NNTPSERVER=news.tilbu1.nb.nl.home.com

alt.binaries.sounds.mp3.heavy-metal| \
alt.binaries.sounds.mp3.1980s {
	# Add news4.euro.net as a second server for
	# alt.binaries.sounds.mp3.heavy-metal and
	# alt.binaries.sounds.mp3.1980s
	NNTPSERVER+=|news4.euro.net
}

alt.binaries.sounds.mp3.gothic-industrial
alt.binaries.sounds.mp3.heavy-metal| \
alt.binaries.sounds.mp3.1980s {
	OPT_L=true
	OPT_I=(?i)( \
		bauhaus| \
		big black \
	)
}
<== cut here ==>

Supported commandline options:
------------------------------

"-I", "--include"	Set include pattern.
"-c", "--configfile"	Specify a different config file. Default
			.ripnewsrc
"-L", "--longname"	Sets long filenames.
"-C", "--combinedname"	Sets combined filenames.
"-X", "--exclude"	Set exclude pattern.
"-T", "--test"		Set test mode. Newsrc files will not be writen
			to.

Supported config options:
-------------------------

OPT_I=<pattern>			Set include pattern.
OPT_L=<bool>			Set long filenames.
OPT_C=<bool>			Sets combined filenames.
OPT_X=<pattern>			Set include pattern
OPT_T=<bool>			Set test mode. Newsrc files will not be written
				to.
TEMPDIR=<dir>			Set tempdir location.
NNTPSERVER=<server>[|server]	Set NNTPSERVER names
CACHEDIR=<dir>			Set cachedir location.
DATADIR=<dir>			Set output dir location.
NEWSRCNAME=<newsrcbase>		Specify newsrc basename. Server names
				will be appended.
PERMISSION=<perm>		Set permission bits for directory
				creation. Standard unix style, eg. 0755.

Ruby patterns:
--------------

Ruby patterns are a lot like perl patterns, but there are some
differences. (?i) is the modifier to turn on case insensitivity, unlike
perl this modifier only works on the following block. Luckily you can
group multiple blocks into one by enclosing them with ()'s. So while
'OPT_I=(?i)foo|bar' would match 'foo' case insensitve and 'bar' case
sensitive 'OPT_I=(?i)(foo|bar)' will match both 'foo' and 'bar' case
insensitivly.

Where can I find newsservers:
=============================
freenews.maxbaud.net
www.newzbot.com
www.gj.net/~bhkraft

Known bugs:
===========

There are a lot of known bugs at this time. Basically the error handling
is still almost non existant. Well, if it breaks you get to keep
_both_ pieces. That's what you get with pre-alpha software ;)

Credits:
========
- Stijn Hoop for adding yEnc support

Contact info:
=============

New problems can be reported directly to me at <ward@wouts.nl>. Patches
welcome ;)

Ward Wouts
