README for news2mail 1.1
------------------------

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.

Version 1.1 is an interim release. It fixes some bugs with NNTP
response handling (aborting if an article that was listed in the
NEWNEWS list wasn't actually available), and adds a feature many
people requested - working with a server that has the NEWNEWS command
disabled. It doesn't have other features people asked for, notably
splitting up the digests to smaller chunks if they're too big. I
haven't had much time to work on news2mail until now, but I expect to
have more time soon. I plan a large redesign and rewrite of news2mail
for the next release - it grew bigger than I originally thought it
would so its code needs to be more dynamic. Thus, if you have any
suggestions, now is the time!


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 you're on Solaris, however, you have to
edit the Makefile, comment the LDFLAGS statement and uncomment the
LDFLAGS that is special for Solaris, as stated there.  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; c) edit the
subs.pl and unsubs.pl scripts to load the misc.pl file from the right
place. In essence, that's what the RPM package of this program does.


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

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

Next, you have to select the method you want the program to use for
saving the last article it downloaded on each run. There are two
methods: "newnews" and "artnum". "newnews" is what version 1.0 was
using and it's the default. If you use it, the program saves the date
and time it runs at, and uses it as a bookmark. If you're using
"artnum" it saves the last article number it took from each group.

Use "newnews" if your server supports it (quite a few of them don't),
and if you want to reserve yourself the option to move to another
server without much pain. Use "artnum" if your server doesn't support
"NEWNEWS" or if it does and you don't want to load it too much
("NEWNEWS" creates very high load on the server), and if you don't
plan to move to another server. Otherwise there's not much difference
between them from the user side.

After you decided which one you want to use, edit the misc.pl file in
~/news2mail (if that's where you installed it), and set the method
that you selected. Instructions are all there in the file.

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. ;-)
