		 Installation Instructions for NEWSCAN
		    A Network News Article Scanner
		      by John F. McGowan, Ph.D.

----------------------------------------------------------------------------

Install Topics

1.  Make sure you have Perl / Correct version of Perl.
1.1 How to get Perl 4.036
2.  Finding the Perl interpreter on your system.
3.  Installing newscan manpage (on-line help)
3.1 Installing newscan manpage on Linux.
4.  Unix OS flavor dependency problems (SOCKET.PH).
5.  Determining the NNTP server for your system.
6.  Intalling and using xnewscan
7.  Where to get Tcl/Tk


1.  You will need Larry Wall's Perl on your system.  newscan works with
    Perl 4.036.  newscan is known to fail with Perl 4.019.  Perl 4.019
    will report a syntax error in the newscan perl script.  This appears
    to be a bug in the perl 4.019 interpreter.  perl 4.036 has no problem
    parsing the newscan perl script.  You can
    find out your version of Perl by typing 

	% perl -v
	
	The 36 is 4.036 is the Patch level returned by perl -v


    NOTE on Perl 5.0
    -------------------
    Perl 5.0 represents the recent major release of Perl after 4.036.
    Perl 5.0 is a major rewrite of the Perl code.  newscan has not been
    tested with Perl 5.0.


1.1 How to get Perl 4.036

	Perl is available by anonymous ftp from jpl-devvax.jpl.nasa.gov.
It is in directory pub/perl.4.0  pub/perl.4.0/kits@36 contains the entire
source distribution for Perl in files perl.kitnn.Z where nn = 1..44  Patches
for upgrading your version of perl can be found in pub/perl.4.0/patches
subdirectory.  Perl 5.000 is also available at this site.

	Perl is available at many other sites as well.

2.  By default, the first line of the newscan script:

	#!/usr/bin/perl

	assumes perl is located in /usr/bin directory.

	This is true on the author's system, but may not be true on your
system.  You may need to edit the path to perl.  For example,

	#!/usr/local/bin/perl

	is a common path for perl.

	To find perl on your system, use the Unix which command:

	% which perl
	/usr/local/bin/perl

	which will return path to perl.


3.	Man Page  (Unix On Line Help)

	The newscan Perl script doubles as a manpage.  The script is
	written in such a way that the Perl source acts as an nroff
	comment.  Likewise, perl ignores the nroff manpage embedded in
	the script.  To install the manpage: 

	% cp newscan newscan.1
	% mv newscan.1 /usr/man/man1	# for example

	This procedure works with the nroff supplied on AIX and Sun
	systems to my certain knowledge.  It does not work with the
	groff emulation of nroff on Linux.  Please see next section if
	you are using on Linux.

3.1     Installing Man Page on Linux (Unix On Line Help)

	The embedded manpage described in section 3. above DOES NOT WORK
        on LINUX systems.  For some reason the groff emulation of nroff
        provided with most Linux systems cannot handle the nroff directives
        embedded in newscan.

	For this reason, the newscan distribution now includes a 
	file newscan.man which contains the nroff source for the 
        newscan manpage.

	% cp newscan.man newscan.1
	% mv newscan.1 /usr/man/man1  # for example

	The distribution also includes newscan.man.ascii which is the
	straight ASCII output of running groff emulating nroff on
	newscan.man. 

4.	Machine or Unix Flavor Dependencies  (SOCKET.PH)

	newscan needs sys/socket.ph Perl header file in sys subdirectory of
	Perl library directory to layer out differences in socket calls
	between the BSD (Berkeley) and SVR4 (System V, Release 4) flavors 
        of Unix.  If Perl is installed correctly at
	your site, this is not a problem.  newscan will complain if it
	cannot find sys/socket.ph!  Then complain to your Perl caretaker.

	socket.ph can be created from the socket.h C header file using 
        the h2ph utility which comes with perl.

	Quick Fix (if socket.ph file is missing)

		Comment out line

			require "sys/socket.ph";

		and change lines

		$AF_INET = &AF_INET;
		$SOCK_STREAM = &SOCK_STREAM;

		to

		$AF_INET = 2;

		and

		for BSD Systems (SunOS, SGI Irix 4, also AIX)

		$SOCK_STREAM = 1;

		for Unix SVR4 Systems (Solaris, SGI Irix 5, Unixware,...)

		$SOCK_STREAM = 2;


5. Determining your NNTP (News) Server

	(a) cat /usr/local/lib/rn/server
            This file contains NNTP server address for rn and 
	    trn news readers.

	(b) Some systems define environment variable NNTPSERVER to contain
            the nntp server address.  newscan will check this variable
            and use it *IF* the NNTP line is omitted from 
            the newscan configuration
            file.  The NNTP line explicity tells newscan which NNTP (News)
            Server to attach to.

	(c) Ask someone.


6. Installing and using xnewscan

	xnewscan is a Tcl/Tk script that provides a graphical user interface
for newscan.  Tcl (pronounced "tickle") is a scripting language developed by
Dr. John Ousterhout and his students at Berkeley.  Tk is an extension to
Tcl.  Tk is a toolkit for the X Window System.  Tk adds commands to Tcl
to build Motif-like user interfaces.

	xnewscan requires the wish windowing shell for running Tcl/Tk.
By default, the first line of xnewscan is

	#!/usr/bin/wish -f

	If wish is located somewhere other than /usr/bin, you will need
to edit this line.  For example,

	#!/usr/local/bin/wish -f

	Once xnewscan is installed, simply type

	% xnewscan

	This will pop up the graphical interface.  xnewscan expects
the newscan script (using the name newscan) to be installed somewhere in
your PATH.  xnewscan uses the term QUERY for newscan configuration files.

	Use xnewscan to select queries (configuration files), run the
searches, view results (the articles found by search), and view statistics
on the search.


7. Where to get Tcl/Tk

	The home ftp site for the Tcl source code is

		ftp.cs.berkeley.edu

	The home ftp site for the Tk source code is

		ftp.cs.berkeley.edu


	For Linux users, Tcl/Tk and wish are frequently bundled with Linux
	distributions.

	There is also a comp.lang.tcl USENET newsgroup and a Tcl Frequently
Asked Questions (FAQ).

---------------------END OF FILE------------------------------------------
