
The installation of KNews consists of the following steps.

You have already unpacked the .tar.gz file, otherwise you wouldn't
be reading these instructions.

1A)	If you are comfortable running programs "out of the box", simply
	type:

		make install

	and make will copy the relevant executable images into /usr/bin
	for you.  This does:

		cp vfsys/core /usr/bin/VFsys.knews
		cp news/core /usr/bin/knews

1B)	If you wish to re-make the executables, type:

		make ; make install

	which will re-make everything and then install it.

	(Note that the makefile refers to a utility called "bm"; this is
	a utility that I wrote to increment the version number.  I've
	included the source for it in the "utils" directory -- since you
	are recompiling, it is provided in source form only.  You will
	of course need "bm" to make "bm", but for the first iteration,
	just comment out the "bm" line in the "bm" Makefile :-)  Then
	install bm in your /usr/bin so that the rest of the compile
	can get at it.)

	In either case, create a database directory.  This is a directory
	on a device that has the physical capacity for the newsfeed that
	you wish to receive.  My suggestion (and the default in the
	configuration file) is:

		mkdir /usr/spool/knews

2)	Next, copy the samples/database subdirectory into your database
	directory.  If you've used the same names as above:

		cp samples/database/* /usr/spool/knews

	This just copied:

		accept
		groups

3)	Edit these files to see if you are happy with them.  "accept" contains
	a list of newsgroups that the news software is to accept, any newsgroup
	that doesn't match the regular expressions contained therein will get
	thrown out.  "groups" can be constructed from your active file, via
	the VI command:

		:%s/ .*//

	(ie:  trim off everything after the first space, which is the one right
	after the newsgroup name).  This file is used by VFsys.knews when it
	starts up so that it can create all of the directories required by
	your news system [this is because some newsreaders, TIN in particular,
	decided that if the directory for a particular newsgroup doesn't exist,
	then that newsgroup must be bogus!]


4)	Copy the configuration file into /etc (the default, you can override
	this with a command line option):

		cp samples/etc/* /etc

5)	Edit the configuration file to see that everything is correct for
	your system.  Note that you *have* to set up the news server name,
	the one provided will not work!

6)	To run the program, add the following line to your sysinit file:

		VFsys.knews &

	(You can optionally specify debugging, etc.  Type "use VFsys.knews"
	for more information).

7)	On my system, to get news and do expiry, I just have a shell script
	that runs continuously, feel free to copy this:

		#! /bin/sh

		while true
		do
			date >>log
			knews -v >>log
			echo knews done run at `date` >>log
			echo about to do expiry, but dumping database first >>log
			knews -D >>log
			echo doing expiry at `date` >>log
			knews -e >>log
			echo done expiry at `date`, sleeping 5 minutes >>log
			sleep 300
		done

	You may not want all of the debugging information that that particular
	script generates.  A minimul "running system everything works" version
	of the script is:

		#! /bin/sh

		while true
		do
			knews
			knews -e
			sleep 300
		done

	I put in the sleep 300 so that if the feeder site doesn't have any
	new news, it just goes to sleep for 5 minutes so that we aren't
	constantly hassling it.

8)	Fine tuning.  There are a number of options for fine tuning the
	performance of KNews.  If you are typically only receiving a
	very small feed (ie:  not "*"), you may wish to modify the news
	feeder's request that gets sent to the NNTP server.  This is
	done in "news/news.c", on the line that has nntp_NEWNEWS on
	it.  Change the "*" to "gnu*" if you only wanted to receive
	the "gnu" newsgroups.  From the RFC:

		A newsgroup name containing a "*" (an asterisk) may
		be specified to broaden the article search to some
		or all newsgroups.  The asterisk will be extended
		to match any part of a newsgroup name (e.g.,
		net.micro* will match net.micro.wombat,
		net.micro.apple, etc). Thus if only an asterisk is
		given as the newsgroup name, all newsgroups will be
		searched for new news.

		(Please note that the asterisk "*" expansion is a
		general replacement; in particular, the
		specification of e.g., net.*.unix should be
		correctly expanded to embrace names such as
		net.wombat.unix and net.whocares.unix.)

		Conversely, if no asterisk appears in a given
		newsgroup name, only the specified newsgroup will
		be searched for new articles. Newsgroup names must
		be chosen from those returned in the listing of
		available groups.  Multiple newsgroup names
		(including a "*") may be specified in this command,
		separated by a comma.  No comma shall appear after
		the last newsgroup in the list.  [Implementors are
		cautioned to keep the 512 character command length
		limit in mind.]

		The exclamation point ("!") may be used to negate a
		match.  This can be used to selectively omit certain
		newsgroups from an otherwise larger list.  For
		example, a newsgroups specification of
		"net.*,mod.*,!mod.map.*" would specify that all
		net.<anything> and all mod.<anything> EXCEPT
		mod.map.<anything> newsgroup names would be matched.
		If used, the exclamation point must appear as the
		first character of the given newsgroup name or
		pattern.

Enjoy!

Robert Krten -- rk@parse.com

