PREFACE
=======
Original Author - Tim Smith (tzs@u.washington.edu)
Maintainers - 
March 1995 - Sven Goldt (goldt@math.tu-berlin.de)
July 1995  - Robert A. Yetman (boby@pixi.com)

LOCATION
========
Site1	     = sunsite.unc.edu
Path1        = /pub/Linux/system/Mail/news
File1        = suck-2.4.tar.gz

Site2        = tsx-11.mit.edu
Path2        = /pub/linux/sources/sbin
File2        = suck-2.4.tar.gz

INTRODUCTION
============

READ README.NEWS FIRST!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

This package contains the following software for copying news from an
NNTP server to your local machine, and copying replies back up to
an NNTP server.

suck		Pull a small newsfeed from an NNTP server, avoiding the
			NEWNEWS command.

lpost		Gives one article fetched by suck to the local server.

rpost		Posts article(s) to an NNTP server (like inews).

testhost        Check to see what commands your host recognizes or
		get the active list.

get.news	a script to tie all this together.

put.news	a script called by rpost (see below)


************************************************************************
NOTE:
Suck will not work with obsolete NNTP servers that can't handle
the xhdr command. inn-1.4sec has its own NNTP server that can handle xhdr,
cnews.CR-G has no own NNTP server so it depends on which NNTP server you
connect to cnews.
************************************************************************

************************************************************************
LOOK AT config.h BEFORE COMPILING!  Lots of user-definable stuff in there.
************************************************************************

SUCK
====
Usage:
	Suck [hostname] [-d[tmd] dirname] [-s] [-m] [-b[ir] batchfile]

Suck works in three modes.

1. stdout mode
	%suck
or	%suck myhost.com

	Suck grabs news from an NNTP server and sends the articles to
stdout. Suck accepts as argument the name of an NNTP server or
if you don't give an argument it will take the environment variable
NNTPSERVER. You can redirect the articles to a file or compress them
on the fly like "suck server.domain | gzip -9 > output.gz".
Now it's up to you what you do with the articles.  Maybe
you have the output already on your local machine because you
used a slip line or you still have to transfer the output to your
local machine.

2. Multifile mode
	%suck -m
	%suck myhost.com -m

	Suck grabs news from an NNTP server and stores each article in a
separate file.  They are stored in the directory specified in config.h or
by the -dm command line option.

3. batch mode
	%suck -b[ir] batchfile 
or	%suck myhost.com -b[ir] batchfile 

	Suck will grab news from an NNTP server and store them
into files, one for each article (Multifile mode).  The location of the files
is based on the defines in config.h and the command line -dm.  
Once suck is done downloading the articles, it will build a batch file
which can be processed by either innxmit or rnews.
	-bi - build batch file for innxmit.  The articles are
		left intact, and a batchfile is built with a
		one-up listing of the full path of each article.
		Then innxmit can be called:
	e.g: innxmit localhost batchfile
		
	-br - build batch file for rnews.  The articles are
		concatenated together, with the #!rnews size
		article separator.  This can the be fed to
		rnews:
	e.g: rnews -S localhost batchfile	
	
Options valid in all modes:
-s	
	This forces the status message printed when each message
is downloaded to stderr vice stdout.  Useful if not using batch
or multi-file mode.

-dt dirname
-dm dirname
-dd dirname

	Specify the location of the various files used by suck.
-dt dirname = directory of temp files created by suck (suck.newrc, suck.sort,
		suck.index, suck.restart, suck.killlog).

-dm dirname = directory for storage of Messages created in Multifile mode
		or batch mode

-dd dirname = directory of data files used by suck (sucknewsrc suckkillfile suckothermsgs)


sucknewsrc file ---------------------
	Suck looks for a file sucknewsrc to see what articles you want and
which you already received. The format of sucknewsrc is very simple. It
consists of one line for each newsgroup.  The line contains two fields.
The first field is the name of the group.  The next field is the highest
article number that was in the group when that group was last downloaded.
The fields are separated by a space.

	To add a new newsgroup, just stick it in sucknewsrc, with a
highest article number of 0.  When suck finds a highest article number
of -1, it does not suck any news from that group.  When suck is
finished, it creates the file suck.newrc which contains the new
sucknewsrc with the updated article numbers.

	See the sucknewssrc.sample file for examples.

suckkillfile file --------------------
	To use the killfile routines, uncomment the #define KILLFILE
	line in config.h.  Then, if this file exists,  the headers of 
all messages will be scanned and the message possibly not downloaded, 
based on the parameters in this file.  Currently the only paramter
supported in this file, is the "LINES=" parameter.  Any message longer
than the number of lines specified on this parameter line are not
downloaded.  Any messages not downloaded have the headers logged to
suck.killlog. You can then download these messages by putting their
Messages-ID in the suckothermsgs file.

	See the suckkillfile.sample file for an example.

suckothermsgs file -------------------
	If this file exists, It must contain a one-per-line listing
of Message-ID's, with the <> included.  These messages will then 
be downloaded, in addition to any messages generated by processing
the sucknewsrc file.  This can be used to get messages in other groups,
or to download a message that was killed.

	See the suckothermsgs file for an example.
-----------------------------------------------------------------------
	So now you get the picture. To automatically get a newsfeed even
without support from the news administration you could write a little
shell script for the remote site that pulls any articles since your
last retreival, and uploads any newly posted articles.  For an example
of how this is down, see the get.news script.

	Suck uses a variety of temporary and working files during
operation.  You shouldn't care for them because they will be
recreated every time you run suck.  Suck does not itself clean up any of
these temporary files when it is done.

suck.restart - This file is created to allow a restart in case of
	interruption.  It will restart with the last incomplete
	article downloaded.
suck.newrc   - sucknewsrc with the updated article counts downloaded
suck.index   - list of articles the NNTP server says we haven't received
suck.sorted  - suck.index deduped so we don't download articles twice,
		as if an article is cross-posted to multiple groups.
suck.killlog - This file is NOT recreated every time.  It contains
	     - the header of those messages not downloaded due to
	     - suckkillfile.
		
RPOST
=====
rpost (remote post) will post articles from the local machine to a remote
NNTP server (the opposite of suck)).  It works in two modes

1. stdin mode
	rpost
or	rpost hostname
	
	 rpost reads 1 article from stdin and sends it to your
NNTP server. The article must have a header of at least 2 lines, namely
Newsgroups: and Subject: and a body (the message). Header and body
have to be seperated by a newline.  Rpost does not change the message
in any way.

2. batch mode
	rpost [hostname] -b batchfile [-p prefix] [-f filter $$o=<outfile> filter_arg1 ... ]

	-b batchfile
	
	A listing of the articles to be posted.  One article per 
line, with the line being the path to the file.  On my system, I
just point it to the out.going file produced by inn:

	e.g: -b /usr/spool/news/out.going/pixi

	-p prefix
	If the batchfile for the above article does not contain
	a full path, rather a partial path, this paramater must
	be specified.  This is useful when the out.going file is
	generated by another program.  Inn lists the path in
	the out.going file relative to its base directory
	/usr/spool/news.  In that case I just use -p /usr/spool/news

	-f filter $$o=<outfile> filter_arg1 filter_arg2 ...
	In many cases, each article must be massaged before the 
	remote NNTP will accept it.  This option lets you do that.
	There are two required parameters with this:

	$$o=<outfile>	- <outfile> is the name of the file produced by
		your filter that will get uploaded to the remote NNTP server.
		THIS IS NOT passed to your filter program.

	$$i - When rpost calls your filter, it will replace $$i with the
		file name of the message to be massaged.

	arg1 - The first argument to your filter program/script.  It most
		likely will be $$i 
		
	arg2 ... - any additional args needed can be specified.

	$$o can be specifed anywhere on the command line AFTER the -f
		filter argument.

	This sounds confusing, so let me try to clarify it a bit.  Say
your NNTP server doesn't like messages with NNTP-Posting-Host filled in.
I could write a one line batch file calling sed to delete this from my
messages.

------------myscr
#!/bin/sh
#sample filter script
sed -e "/^NNTP-Posting-Host/d" $1 > $2
------------end myscr script 

Then I call rpost like this

	rpost -b /usr/spool/news/out.going/pixi -f myscr \$\$o=/tmp/FILTERED_MSG \$\$i /tmp/FILTER_MSG

Then, before each message is uploaded, myscr is called with the file
name of the message to be cleaned.  It puts the cleaned-up message in
/tmp/FILTERED_MSG, which is then uploaded to your NNTP server.

NOTE: The $$o and $$i have to be escaped, using either the backslashes
as I have done above, or with single quotes, to prevent the shell from
trying to interpret these as variables.  Failure to escape them will result
in rpost not working!

LPOST
=====
NOTE - use the batch function of suck and avoid rpost, it is
not the most efficient way of doing things.  It is kept here solely
as a link to the past, and some people still use it.

 lpost (local post) reads stdin and pipes the articles to rnews.  You
need rnews which is typically found in /usr/lib/news. If not, you should
create a symbolic link to rnews in that directory (while you are at it,
you could create a symbolic link for inews as well) like ln -s
bin/input/rnews rnews.  A typical way to use lpost is "zcat output.gz |
lpost".  This could take a while, so be patient. If you want to see how
lpost is working invoke it with the option -v.

TESTHOST
========

Usage: testhost [-a] hostname

	This program does two things.  The default, is to query the
hostname and list out what commands it allows.  This can be used to
determine if you need the #define NNRP in config.h.  The second, 
with the -a, will give you a list, to stdout, of the host's active file.

CONCLUSION
==========

 The suck package is useful if you have a dialup connection to a shell
or slip account and want to reduce the expenses for your
phonebill/online time. Rumors say that some dudes use suck for other
reasons like archiving, extra newsfeed or sending articles by mail.
 With all these little tools together you almost have the functionality
of a newsreader, but without the advantage of comfortability and the
disadvantage of online time.
