README for news2mail 1.0
------------------------

This program is intended for people who don't normally have access to a
Usenet server but have an account on some machine that does, and would
like to periodically receive digested Usenet groups in their mailbox. I
find this a very convenient way to read Usenet offline. This solution is
best for various announce groups, since threading and the ability to
follow-up are not very important in them, but the fact that the news are
delivered to you automatically on a daily (or any other) basis without any
effort from your side, is.

As previously mentioned, you should have an account on a machine with
Usenet access in order to use this program. You should also have
permissions to use cron(8) on it. In case you don't, check whether you have
permissions to use at(1). If you do, you can use my script that emulates
daily cron by using at. You can find it in the misc/ subdirectory.


Compiling
---------

In order to compile the program, type
	make
The code is pretty standard and shouldn't make problems compiling on any
decent Unix platform. If the compiler complains that it doesn't recognize
the "vsnprintf" function, or something of that sort, edit defines.h and
comment out the "USE_VSNPRINTF" define.  If the compiler gives you other
errors, please mail them to me, along with information about the machine
and the OS you were trying to compile it on, as well as the version of GCC
installed (check that out by typing 'gcc --version'), and we'll see what
we can do.


Installing
----------

In order to install it, type
	make install
It will create a directory named "news2mail" in your home directory (if
you prefer another name you can change it in the Makefile), move the
compiled binary there, and also put there the config.txt sample
configuration file, this README file, and the Perl scripts (which will be
described later). The usual method of installing a program on Unix is
tossing its files around the system - e.g., moving the binary to
/usr/local/bin, the configuration to /etc, and so on. The Makefile doesn't
do it because I want to stress that administrator rights are not needed
in order to install and use this program. If you insist on installing it
the Right Way, you'll need to a) edit the defines.h file and modify the
CONFIG_FILE and the GROUPS_FILE definitions before compiling; b) make it
put the log file in the right place (probably /var/log) by editing its path
in the configuration file.


Configuring
-----------

Edit the configuration file (config.txt) to suit your needs. Comments
begin with a # sign and extend to the next end-of-line.

Then use the subs.pl and unsubs.pl scripts to subscribe to and unsubscribe
from newsgroups. Running them is simple:
	subs.pl groupfile newsgroup email
where "groupfile" is the name of the groups file (i.e. "groups.txt" unless
you changed it in defines.h), newsgroup is the name of the newsgroup to
subscribe to, and email is the e-mail address to subscribe to that group.
The same syntax is used for unsubs.pl.


Running
-------

You can run news2mail by hand, though that would be pretty unuseful for
anything other than testing. Type
	news2mail -h
to list the command-line parameters you can use. Note that the -q and
the -Q switches are particularily useful for use in cron scripts.

Normally you would ask cron to run news2mail daily (or at any other time
interval you may choose). Check the crontab(5) man page for instructions,
or the README file for my ecron script if you're going to use it. Please
note that you need to run news2mail from its directory, so the command
should look something like this:
	cd $HOME/news2mail ; ./news2mail -q


Creating a mail-based subscribing service
-----------------------------------------

Included with the package are three perl scripts that can be used to
subscribe to and unsubscribe from newsgroups via e-mail. subs.pl and
unsubs.pl are the two scripts that handle subscription and unsubscription,
and getmail.pl is the script that calls them while interpreting the mail
message that was piped to it.

The installation can be done in many ways. If you can create accounts on
the machine, you can create a special account for news2mail, and all the
mail for that account should be piped to the getmail.pl script via the
.forward (or the .qmail if you're using this wonderful mailer) file. If
you cannot create accounts, you can decide that messages with a certain
token in their Subject: line (e.g., "[n2m]") will be piped to getmail.pl,
and implement that through a simple procmail recipe. If the machine is
running qmail, you can create a special .qmail-n2m file in your home
directory, which will pipe the messages to getmail.pl, and then all the
messages for it should be sent to username-n2m where "username" is of
course your username.

The subject of the message is ignored by the getmail.pl script. Only the
body lines are examined. Each line contains one command. The commands
currently implemented are:

	subscribe newsgroup
	unsubscribe newsgroup
	getlist

The "subscribe" and "unsubscribe" commands (that can be abbreviated as
"subs" and "unsubs") do just what their names indicate. The "getlist"
command attaches the compressed list of all currently available newsgroups
to the poster.  For it to work you need the "mpack" program to be on the
path. You can get mpack at ftp://ftp.andrew.cmu.edu/pub/mpack . You also
need to generate the list once before it can be attached. In order to do
it, enter your news2mail directory (e.g. ~/news2mail) and type:
	./news2mail -l
	zip groups.zip groups.lst
	rm groups.lst
You'll need to re-do this once in a while in order for the list to stay
updated. If you wish you can schedule it to execute automatically every
some time (using cron).


Miscellaneous
-------------

The news2mail program is distributed freely under the terms of the GNU
General Public License. Visit http://www.gnu.org in order to obtain it.

The author is Alex Shnitman <alexsh@linux.org.il>. The home page of the
program is http://alexsh.home.ml.org/news2mail.html . Check it out from
time to time to see if a new release is out. Please don't hesitate to
write me about any problem or to suggest any feature. I'd especially
like to hear if you create a public service using it, because I'd rather
use it instead of my current shaky university account. ;-)
