autotab :  A system for efficiently searching and accessing the 
           mirrors of the guitar archives maintained at nevada.edu.

=====
Copyright (C) 1994 Robert Zawalski (bob)

These programs are free software. With the exception of getit.c and
getit.man you can redistribute them and/or modify them under the terms
of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any
later version.

getit.c and getit.man are from 
Ken Jenks, Space Shuttle Program Office, 
NASA Lyndon B. Johnson Space Center, 
Houston, Texas.

In his AUTHOR file Ken Jenks says:

"You may use this code for anything you want, and give it to anybody."


NO WARRANTY
===========
These programs are distributed in the hope that they will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details. Write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA if
you don't already have a copy.
===========

This software builds a set of lightning-fast, convenient, network friendly
interfaces for getting files from the mirrors of the
nevada.edu:pub/guitar archive.

The Old Way
===========
Even for the experienced user, traditional use of ftp is time
consuming and labor intensive.

Normally a user first searches one way or another to find the desired
file, then gets it.  The preferable way would be to view an INDEX by
hand and then ftp, cd, dir, and get the file.  The awful way would be
to do an ftp login and play the "cd here, there, and everywhere" game
and then get the desired file.  I've watched old unix hands do this as
much as beginners.  You've have LOTS of company.

Doing either of these is a BUNCH of work, and takes a LOT of time. 
It TAKES your time, and TAKES up scarce slots for anonymous ftp.


A New Way
=========
Using the autotab system, a user can get files in record time doing
very little work. Software automates most of the work.  

Under this system, the search for the desired file is automated by the
software and the result of the search is placed immediately into a
command which silently, speedily, automatically gets the file for you
and stores it in an appropriate directory no matter where you were in
your directory tree when you typed the command.  No need to first 'cd'
to some sensible directory before you get files, or to explicitly tell
ftp to change working directories.  

The software gets the files you request in the background, enabling
you to get a file you've just read about in a newsgroup or email WHILE
you continue to read the news/email.  (suspend the news/mail-reader,
type: getsong "filename" [once you know what you're doing], resume
your news/mail-reader).

The details of the installation is presented in the How-To-INSTALL
file. It has been simplified for use by complete novices (hopefully:).

An overview of the system is presented in the USAGE file.  Short,
concise usage information is available in unix manual page format as
well, in case you need a quick reminder. The manual page is named
autotab.1.  A preformatted (ascii text) version named autotab.txt is
also included.

==============

Many thanks to Ken Jenks (kjenks@gothamcity.jsc.nasa.gov) for the getit
utility.  It is the soul of this system.  

getit, (or a program like it) might permit anonymous ftp to survive
the mass migration of new users to the net.

Thanks Ken!

BIG THANKS to Cal Woods and Ryan Harding for lots of
patience, debugging assistance, code, advice and encouragement.
Their input has resulted in a significantly improved package than what
I'd have released otherwise.  

Thank you Ron Young at nevada.edu for sharing some statistics of
usage patterns in the guitar archives.

All users should thank Ian Utting [I.A.Utting@ukc.ac.uk (iau)], and
David Gardner [djg1@ukc.ac.uk] for their _immediate_ help improving
the seeband utility significantly.  Thanks! 

Thanks also to Joseph W. Lazio, Jacob Lerner, Christopher Neufeld,
Patrick Seemann and Pete Stromberg for taking time to email help with
some of the unix utilities. 

Thanks also to those who used the previous versions and reported their 
results. (good and bad :-)

Clint Adams, Eric Adams, Sam Albrecht, Jay Allen, Paul Boyd, Alan
Curry, Abhay Golhar, John Kean, Phil Lord, Mike A McBrien, Christopher
Neufeld, Mark Ontkush, Bjoern Pettersson, Sam L. Smith, Patrick
Seemann, Brett Wilson, Bas de Witte, and someone named Craig   


Please email corrections, suggestions, flames to bobz@crl.com .

Enjoy,
bob zawalski  bobz@crl.com





Instructions for complete novices and system administrators.
-----------------------------------------------------------

DON'T INSTALL By HAND. Use the install script named install.sh

First Things:
============
This system is designed to be installed for single users or for
site-wide use on a system.  

Single users:

Ensure that 'gcc' (or 'cc'),  'ftp', 'hostname', and 'whoami' are
available to you. There are better ways, but you can learn whether
they're available to you by just typing there names.

Contact your system-administrator if you need assistance with this. It
is really quite a simple thing for them to help you with :-) This is
not a time to be shy.

Arrange for the 'ping' utiltiy to be in your PATH.
This is not critical, but without 'ping', your configuration will be
based on a guess rather than a test.

Ensure you are running your login shell (ie the one named in your
password file.) If you login with a different shell than the one you
normally use, exit that other shell by typing 'exit' or D. 
Type: echo $SHELL    to find out if you're not sure.

===

Save the file from netnews, edit it to make sure all the text above
        begin 644 autotab-1.2.tar.Z
has been deleted, save, and then type:
        uudecode filename 
where 'filename' is the name of the file you saved the edited netnews
posting to.

Now type:
zcat autotab-1.2.tar.Z | tar

This extracts a bunch of files into a directory called autotab-1.20/

Change into this directory (type 'cd autotab-1.20') and type
        sh install.sh 

===

This will install/compile all the programs for you, putting
them into your  bin/ directory just off your root (home) directory
(attempt to) get a copy of the FLAT.INDEX from one of the mirror sites
and put it in your lib/ directory (which it will create if necessary).

The installation script asks you to name a directory to which you
would like all of the files that you get from the archive to be placed.
All the files that you get from using the various programs will
be placed in this directory automatically. 

The installation script ask you to choose a 'style' for your tabs
directory.  Choosing the style named "none", each sngle file you get
will be placed on the floor of your tabs/ directory (what-ever you
named it). All seeband or getband transfers will be placed into a
subdirectory named after the artist in your tabs/ directory.

The "short" style causes all file transfers to be placed into
subdirectories named after the artist's name.

The "long" style replicates the organization of the archive. It places
all transfers into subdirectories named after the artist, but
additionally places these artist subdirectories into 'alpha'
subdirectories, just as is done at the archive.


The install script allows you to configure this system to compress
your FLAT.INDEX file using GNU gzip so you can save space. This
requires zgrep, gzcat and gzip to be present and available in your
PATH.  If all of these are not available, then the FLAT.INDEX remains
uncompressed, and the standard UNIX utilites are used.


The system is configurable to always uncompress song files which
sometimes arrive as song.Z files.  This often causes novice unix users
some difficulty.

Read the USAGE file to learn about the convenience that 'getsong' , 
'getband' and all the other programs will provide for you!


=== Reconfiguration ===

The install.sh script has been designed to be re-run to enable you to
change the confiuration of the mirror sites, of GNU's gzip utilities,
and the location and style of the directory into which you keep your
music files.

You might want to do this if you believe that one of the mirror sites
has become faster, or if you've just aquired GNU gzip and want to use
it even though it was not available when you first installed this
software, or if you want to organize your downloaded files a bit
differently. 

==========================================================

System-wide installation:
------------------------

System wide installation allows all users access to the same
machine-searchable index to the collection (FLAT.INDEX), and one copy
of the executables (sh shell scripts). System-wide installation
produces a table of environmental variables accessed by the
executables into a file. All of these files (the index, an up-date
log, and .tabenv-global are expected to reside in /usr/local/lib in a
new directory named autotab which is created during the installation. 



Individual users will then run the installation script to identify the
name, location and style of the directory into which the files they
retrieve will be stored. The option to use GNU gzip and relatives will
NOT be presented to them.

I'm discouraging use of gzip/zgrep/gzcat in system-wide installations
to reduce cpu and i/o load due to frequent uncompression of the INDEX
file. Things definitely run faster when compression is not used, and
the disk usage of the FLAT.INDEX is trivial except for users with
small disk quotas.

System administrators who would like to keep the FLAT.INDEX compressed
and have their users use zgrep each time they searchit  are invited to
email this opinion (or others) to me. Bob Zawalski  bobz@crl.com

If you intend to install for the system you will need to run this
installation as root to have write permission to /usr/local/bin and
/usr/local/lib .


enjoy,
Bob Zawalski