%% /u/sy/beebe/tex/bibsplit/INSTALL, Sat Nov 13 12:16:20 1999
%% Edit by Nelson H. F. Beebe <beebe@math.utah.edu>
%%
%% Copyright (C) 1999 Nelson H. F. Beebe
%% See the file bibsplit.sin for a full copyright notice.
%%

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


====================
INSTALLATION ON UNIX
====================

As with most GNUware, you can build, test, and install this program on
most UNIX systems by these simple steps

	./configure && make all check install

No source code compilations are required, so the installation should
only take a minute or so.

This is what the "configure" output looks like on the author's Sun
Solaris 2.7 system:

creating cache ./config.cache
checking for autoconf... autoconf
checking for mawk... /usr/local/bin/mawk
checking for ksh... /bin/ksh
checking for mkdir.sh... /u/sy/beebe/tex/bibsplit/mkdir.sh
checking for cat... cat
checking for checknr... checknr
checking for checksum... checksum
checking for chmod... chmod
checking for cmp... cmp
checking for scp... scp
checking for deroff... deroff
checking for diff... diff
checking for distill... distill
checking for ditroff... no
checking for groff... groff
checking for dw... dw
checking for grep... grep
checking for gzip... gzip
checking for ispell... ispell
checking for jar... jar
checking for lex... lex
checking for ln... ln
checking for ls... ls
checking for man2html... man2html
checking for mv... mv
checking for nroff... nroff
checking for rm... rm
checking for sed... sed
checking for sort... sort
checking for spell... spell
checking for tar... tar
checking for tgrind... tgrind
checking for unzip... unzip
checking for zip... zip
checking for zoo... zoo
updating cache ./config.cache
creating ./config.status
creating Makefile
creating bibsplit.sh

This is what the "make check" output should look like:

========================================================================
WARNING: You need about 14MB of free disk space in the current directory
to complete the tests!
========================================================================
Test of bibsplit: there should be no output, other than the test and
command names. The tests take about 30 sec on a fast workstation.
============ check001: bibsplit -?
============ check002: bibsplit -author
============ check003: bibsplit -bycentury
============ check004: bibsplit -bydecade
============ check005: bibsplit -byhalfcentury
============ check006: bibsplit -bylabel
============ check007: bibsplit -bynumber 250
============ check008: bibsplit -bypentad
============ check009: bibsplit -byrange a_e,f_j,k_o,p_t,u_z
============ check010: bibsplit -byscore
============ check011: bibsplit -byyear
============ check012: bibsplit -copyright
============ check013: bibsplit -help
============ check014: bibsplit -version
============ check015: bibsplit -filter 'tr A-Z a-z | tr aeiou AEIOU'
========================================================================

If you wish to undo a "make install", just do "make uninstall"; this
will remove any files in system directories put there by "make
install".

The GNU standard installation directories /usr/local/bin for binaries,
/usr/local/share/lib/PROGRAMNAME for shared files, and
/usr/local/man/man1 for manual pages are assumed.

The prefix /usr/local can be overridden by providing an alternate
definition on the command line:

	make prefix=/some/other/path install

After installation, you can do make distclean to restore the
directories to their distribution state.  You should also do this
between builds for different architectures from the same source tree;
neglecting to do to will almost certainly lead to failure, because the
config.cache file created by configure will lead to incorrect settings
of one or more macro assignments in the Makefile.

This program has been installed at the author's site on at least these
systems:

	Apple Macintosh PPC G3	Rhapsody 5.5
	DEC Alpha		OSF/1 4.0F
	HP 9000/735		HP-UX 10.01
	IBM PowerPC		AIX 4.2
	Intel Pentium II MMX	GNU/Linux 2.2.5-22
	NeXT Turbostation	Mach 3.3
	SGI Indigo/2		IRIX 5.3
	SGI Origin 200		IRIX 6.5
	Sun SPARC		GNU/Linux 2.0.35 (Redhat 5.2 and 6.0)
	Sun SPARC		Solaris 2.6
	Sun SPARC		Solaris 2.7

All but one of the installations succeeded with the one-line command
above.  However, on the NeXT, because of a shell bug in the handling
of shell functions, it was necessary to use bash instead of sh in
order to get the tests to succeed:

	make SHELL=/usr/local/bin/bash check install

Even then, there is an apparent bug in the handling of a shell
case statement like this:

	case $opt in
	...
	-[?] | -help | -hel | -he | -h )
	...
	esac

The shell fails to match the correct case with opt set to -\?, -'?',
and '-?', but curiously, succeeds with --\?, --'?', '--?', etc.  The
workaround was to do

	cp test/check013.opt test/check001.opt

thereby replacing -? by -help for the first test (which of course then
fails, but that is expected).


======================
VALIDATION AND TESTING
======================

The torture test suite that is run by "make check" tests all of the
command-line options, and should reveal any installation problems.

The test bibliography is large enough to exhibit all of the features
of citations and cross referencing that bibsplit can handle, yet not
so large that the distribution is excessively large, or that the "make
check" run takes too long.

At the author's site, an additional unreleased torture test suite has
been used, and will continue to be used in any further developments of
bibsplit.  It has a complete bibliography of the journal American
Mathematical Monthly, covering the years 1894--1999.  The November
1999 snapshot of this bibliography that is used for the testing is
18MB in size, with 35,027 unique entries, 13,001 \cite{} instances,
23,009 labels in those \cite{}s, and 12,889 unique labels in those
\cite{}s.  There are, however, no crossref="label" instances in the
bibliographic entries.

The extensive cross-referencing in this bibliography puts extreme
stress on bibsplit's handling of such data, since thousands of
referenced entries have to be recovered from their output files, and
written to other ones, without duplication.  It took longer than
expected to get this complex code right, but successful handling of
this second test suite has given the author considerable confidence in
bibsplit's correctness.


======
CAVEAT
======

This program requires two critical supporting programs: the UNIX
Bourne shell (or compatible), and an awk implementation based on the
`new' awk language described in the 1988 book (see the accompanying
README.AWK file for further details).

Of the several awk implementations, mawk is preferred, because with
it, bibsplit runs about twice as fast as it does with gawk (based on
extensive tests with late 1999 versions of each). The configure script
chooses awk implementations based on their relative speeds for
bibsplit.


=======================================
INSTALLATION ON OTHER OPERATING SYSTEMS
=======================================

bibsplit has not yet been ported by the author to other operating
systems, notably IBM PC DOS, Microsoft Windows (95, 98, NT), Macintosh
MacOS, and Compaq/DEC (Open)VMS.

However, as long as a POSIX-compliant shell implementation can be
found, it should be straightforward to install bibsplit.  awk is part
of the POSIX standard, so it should already be installed.

Most non-UNIX operating systems claim POSIX compliance, although the
POSIX environment may not be installed by default.

In particular, on the popular Microsoft Windows platform, there are
several implementations, some free, and some commercial, of a
UNIX-like environment that will make installation of bibsplit as
simple as it is on UNIX.  For details, see

	http://www.math.utah.edu/~beebe/gnu-on-windows.html

For further information about POSIX, and its availability on other
operating systems, see

@String{pub-BENCUM              = "Benjamin/Cummings Pub. Co."}

@String{pub-BENCUM:adr          = "Redwood City, CA, USA"}

@String{pub-ORA                 = "O'Reilly \& {Associates, Inc.}"}

@String{pub-ORA:adr             = "981 Chestnut Street, Newton, MA 02164, USA"}

@String{pub-WILEY-INTERSCIENCE = "Wiley-In{\-}ter{\-}sci{\-}ence"}

@String{pub-WILEY-INTERSCIENCE:adr = "New York, NY, USA"}

@Book{IEEE:ITU86,
  author =       "IEEE",
  title =        "{IEEE} Trial-Use Standard Portable Operating System
                 for Computer Environments",
  publisher =    pub-WILEY-INTERSCIENCE,
  address =      pub-WILEY-INTERSCIENCE:adr,
  edition =      "{IEEE Std} 1003.1",
  pages =        "207",
  month =        apr,
  year =         "1986",
  ISBN =         "0-471-85027-6",
  LCCN =         "TK 275 I5 Std 1003.1",
  bibdate =      "Wed Dec 15 10:34:55 1993",
}

@Book{Gallmeister:1995:PPR,
  author =       "Bill Gallmeister",
  title =        "{POSIX.4}: Programming for the Real World",
  publisher =    pub-ORA,
  address =      pub-ORA:adr,
  pages =        "xviii + 548",
  month =        jan,
  year =         "1995",
  ISBN =         "1-56592-074-0",
  LCCN =         "QA76.76.O63 G34 1995",
  bibdate =      "Fri May 19 19:20:07 MDT 1995",
  bibsource =    "ftp://ftp.ora.com/pub/book.catalog",
  price =        "US\$29.95",
  acknowledgement = ack-nhfb,
}

@Book{Lewine:1991:PPG,
  author =       "Donald A. Lewine",
  title =        "{POSIX} programmer's guide: writing portable {UNIX}
                 programs with the {POSIX.1} standard",
  publisher =    pub-ORA,
  address =      pub-ORA:adr,
  pages =        "xxvii + 607",
  year =         "1991",
  ISBN =         "0-937175-73-0",
  LCCN =         "QA76.76.O63 L487 1991b",
  bibdate =      "Wed Nov 13 14:58:22 1996",
  bibsource =    "ftp://ftp.ora.com/pub/book.catalog",
  note =         "March 1994 printing with corrections, updates, and
                 December 1991 Appendix G.",
  price =        "US\$34.95",
  acknowledgement = ack-nhfb,
}

@Book{Zlotnick:PSP91,
  author =       "Fred Zlotnick",
  title =        "The {POSIX.1} standard: a programmer's guide",
  publisher =    pub-BENCUM,
  address =      pub-BENCUM:adr,
  pages =        "xi + 379",
  year =         "1991",
  ISBN =         "0-8053-9605-5",
  LCCN =         "QA76.76.063 Z57 1991",
  bibdate =      "Sat Nov 12 21:24:05 1994",
}


=============
BUG REPORTING
=============

Please report bugs, comments, and kudos by e-mail (or postal mail)
directly to the author:

	Nelson H. F. Beebe
	Center for Scientific Computing
	University of Utah
	Department of Mathematics, 322 INSCC
	155 S 1400 E RM 233
	Salt Lake City, UT 84112-0090
	USA
	Email: beebe@math.utah.edu, beebe@acm.org, beebe@ieee.org (Internet)
	WWW URL: http://www.math.utah.edu/~beebe
	Telephone: +1 801 581 5254
	FAX: +1 801 585 1640, +1 801 581 4148

The author's mail volume is far too large, so please do not expect an
immediate response.  However, all reports will be collected and acted
on as soon as time permits.
