jugtail is a tool for getting menu information from various gopher
servers, acting as a search engine in a specified gopher sub-space.

It is a modified version of Jonzy's popular gopher search tool.

The remainder of this document is divided into two parts, the first
part titled "KNOWN PORTS" will list all machines jugtail is known to
have been ported to, and the second part "GETTING STARTED" is a
somewhat detailed set of steps to assist you in getting jugtail up
and running.

----------------------------------------------------------------------
KNOWN PORTS

jugtail has been heavily modified from its previous version, and
this has both a positive and negative impact on portability.

All systems must be tested again, and really old systems will probably
not be able to run jugtail (for example, C89 is now assumed).

Please report your experiences of running jugtail on your system,
so this section can be expanded accordingly.

----------------------------------------------------------------------
GETTING STARTED

jugtail can be downloaded from its web page at
http://www.nongnu.org/jugtail

or from the savannah project page at
http://savannah.nongnu.org/projects/jugtail

Once you have downloaded jugtail the following command will uncompress and
untar the files into a directory that gets created called "jugtail-VERS":
	gunzip jugtail-VERS.tar.gz
	tar -xvf jugtail-VERS.tar

For installation instructions see the generic INSTALL file.
Also, remember to edit the jugtail.conf file in the package data directory
to apply your desired changes to the options.

To view the man page, after installation type:

man jugtail

or, before installation, type:

man ./jugtail.1

Other interesting man pages are jugtail.conf.5 and veronica.ctl.5

It is highly recommended you edit the "jugtail.conf.h" file to ensure
the defines HOSTDOMAIN, JUGTAILHELP, and ERRORHOST reflect the needs
for your site.  These values can be overridden if you edit the "jugtail.conf"
file and ensure "hostname", "jugtailhelp", and "errorhost" reflect your site
as well.

If you have problems compiling look at the Makefile and sprint.h files
created via "configure".  Alternatily you may need to look at the
jugtail.conf.h and Makefile.

The following information describes the purpose of various defines and
variables to assist you should any problems be encountered:

  These values are found in jugtail.conf.h:
  You can use the jugtail.conf file alter these values. 
  HOSTDOMAIN      Any part of your machine name that does not get displayed
		  via a call to `hostname`.  The result of `hostname` and
		  HOSTDOMAIN should yield a fully qualified domain name of the
		  machine running jugtail.
		  Note: The fully qualified domain name can be overridden by
		  entering "hostname" as the name in the jugtail.conf file.
  JUGTAILHELP     The gopher server serving the jugtail help document.
		  This is the gopher selector, host, and port of the document
		  to give the user if an error is encountered.
		  Note: This field can be overridden by entering "jugtailhelp"
		  as the gopher path to the jugtail help document in the
		  jugtail.conf file.
  ERRORHOST       The Path, Host, and Port for an error item.
		  Note: This field can be overridden by entering "errorhost"
		  as the gopher path in the jugtail.conf file.
  PORT2USE        The port to use when jugtail is a search engine.
  MAXPROCS	  The maximum number of forked jugtail processes.
  DELIMITERS	  The delimiters that seperate a word.
  MAXITEMS2RETURN The maximum number of found items to return.
  DEFAULTBOOLOP   The default boolean operator if none is given between words.
  JUGTAILHELPTITL The title to be displayed to the user of the jugtail
                  help document.
  USAGERROR       The string "usage error".
  WILDCARDERR     The invalid wildcard usage error message.
  TOMNYPRCSERR    The too many processes error message.
  NOFORKERR       The jugtail can't fork error message.
  GTSTRERR        The get string timed out error message.
  READERR         The read line error message.
  TMPFILENAME     The location and name of jugtail's temporary file.

  These values are found in jugtail.conf.h are automaticly generated when you
  run "configure".  These too can be altered via the jugtail.conf file.
  CATCOMMAND      The cat system command, the %s is required.
  SORTCOMMAND     The sort system command, the %s is required.
  TOUCHCOMMAND    The touch system command, the %s is required.

  These values are found in Makefile
  THEVERSION      The version of jugtail, only edit this if you make changes.
  MANSUFF         The suffix of the man page and where to install the manpage.
  DESTDIR         The location of the jugtail executable.  You may not want
		  this to be publicly accessible.
  DESTMAN         The location of the jugtail man page.
  PERMISSIONS     The permissions for the jugtail executable.
  LINT            The lint program to use if need me.
  LINTFLAGS       Any lint flags you want to set.
  CC              The C compiler to use.  Note: You can leave this blank
		  if you don't know where your C compiler resides, the
		  configuration step will attempt to locate it for you.
  NOWARNINGS	  Uncommented if you don't want to see any compiler warnings.
  OPTIMIZATION	  Any optimization flags you want to have.
  PROTOTYPES	  Uncommented if you want to use prototypes.

  These values are found in Makefile are automaticly generated when you
  run "configure".  If you know you need these flags simply add them to the
  DFLAGS or LFLAGS line.
  -D_POSIX_SOURCE    Needed when compiling under A/UX.
  -DSOLARIS2 -DSVR4  Needed when compiling on a sun with Solaris.
  -lsocket -lnsl     Needed for linking under Solaris
  DFLAGS	     The definition flags needed for your environment
  CFLAGS	     The compiler flags needed for your environment.
  LFLAGS	     The libraries you need, some libraries may exist
		     here you don't need but this should not cause
		     problems.

You will want to place the "ABOUT" document somewhere on your
gopher server, and then give the proper definition of JUGTAILHELPDOC
in the jugtail.conf.h or "jugtailhelp" in jugtail.conf.  You may want
to copy the file "ABOUT" in the same directory as the jugtail
link, so the users will have knowlege of how to search the tables built
by jugtail, and rename it "About jugtail".

Create a link file somewhere in your gopher data directory.  Mine looks like:
  Name=Search all UofU menus using jugtail
  Numb=4
  Type=7
  Port=3000
  Path=
  Host=gopher.utah.edu

You can assist veronica in harvesting its data by configuring and placing
the veronica.ctl file, included with this distribution, at the appropriate
location in your gopher tree.

IMPORTANT NOTE:  jugtail does NOT use aliased hostnames and requires
Fully Qualified Domain Names.

The steps I did to get jugtail running as a server follow:
 jugtail -tmVb data -X "ftp:*" .utah.edu gopher.utah.edu
 jugtail -tB data
 jugtail -tS -l data.log data

Sample steps to rebuild the jugtail database follow:
 cd directory_other_than_where_the_jugtail_data_resides
 jugtail -b data -l report -X "ftp:*" .utah.edu gopher.utah.edu
 jugtail -B data
 mv data* directory_where_the_jugtail_data_resides/
 kill -HUP `/usr/bin/head -1 /usr/local/var/jugtail.pid`

Edit the jugtail.sample.csh script to meet your particular needs.  This
script is a sample script to be used by cron.

There are more examples of jugtail commands listed in the man page.

NOTE: jugtail is not inetd compatible.  Furthermore, if you note any
problems building the database you should ensure that gopherd is NOT
run via inetd.
