Thank you for acquiring a copy of the XV distribution.  I hope you enjoy it.

If you like the program and decide to use it, *please* send me a short
email message to that effect.  Be sure to mention the full name of your
organization.  When our sponsors ask us 'what have you been doing', it 
always looks good if we can come up with a nice long list of folks who are
using code developed in the GRASP Lab.  Brownie points, y'see.

Also, if you find XV to be nifty, useful, generally 'cool', and of
some value to you, your donation (not tax-deductable) would be greatly
appreciated.  $10 (U.S.) is probably a fine amount to donate.  Folks
who donate $25 and up will receive a Real Nice bound copy of the XV
Manual.  It'll look lovely in your bookcase, on your coffee table, or
mounted over your fireplace.  If you send $25 (or more!), please
explicitly say whether or not you wish me to send you a copy of the
manual.  I say this because some folks have sent $25, and not
particularly wanted a manual.  Since it costs a fair amount of time
and money to produce and mail out manuals, I'd just as soon keep the
money (and time) if you don't really want a manual.

Please send all donations (or other correspondence) to:
	John Bradley
	1053 Floyd Terrace
	Bryn Mawr, PA  19010

U.S. Funds only, please.  Checks should be made payable to 'John Bradley'.


Installation
------------
If you don't plan to use Imake, copy 'Makefile.std' (a regular old-style
minimalist makefile) to 'Makefile'.  (Actually, this has already been done
for you, as I prefer to just use 'make'.  This is mainly to let you know that
if you ever *do* run Imake (and thereby trash the Makefile), there's a backup
of the 'simple' Makefile in 'Makefile.std'.)

If you are building the program on a Sun running SunOS, a DECstation
running Ultrix, you should be able to just type 'make' and have
everything compile cleanly.  (On the DECstation, you'll see some
warnings about some functions being too long to be optimized.  Ignore
such messages.)  

On an IBM RS/6000, you can build cleanly with one minor tweak.  Replace
tiff/Makefile with tiff/Makefile.aix, then type 'make' in the main XV 
directory.

Otherwise, particularly if you're running on a SVR4-based system,
you'll probably have to edit the Makefile.

Check the Makefile for the configuration option(s).  There are unfortunately
quite a few these days, to support a number of different machines.  If
you're on a SVR4-based machine, you'll probably need '-DSVR4' and '-DDIRENT'.
Read the file for more specific info.

Otherwise, check the options in the Imakefile, and generate a Makefile
using 'xmkmf' (or whatever).  Be sure to 'make depend' before building
the program.

GCC USERS: It is important that the XV source and the contents of the JPEG and
TIFF subdirectories all be compiled with the same compiler.  While this should
normally be the case, as the value of the CC variable in the XV makefile is
propigated to the makefiles in the subdirectories, it's something to keep in
mind.  Also, be sure to specify '-traditional' when compiling with gcc, 
otherwise it'll blow up on some code in the TIFF subdirectory.

GCC USERS: If you compile XV with gcc, and find XV crashing in the
function 'vsprintf()', the gcc-specific include files on your system
are barfified.  You should get your sysadmin-type to fix the
gcc-include files (you can test it by compiling 'vargs.c', a simple
varargs-verification program in the unsupt directory), or alternately,
just use 'cc' instead.

HP USERS:  If you are running HP-UX 7.* , you should remove the '-O' compiler
flag from the Makefile.  The optimizer supplied with that version of the OS 
has been known to break code in xvgam.c (and possibly elsewhere, as well).  
You'll know the optimizer has broken the code if pictures come out 'purple'.

DECSTATION USERS:  I've had a report that compiling 'xvevent.c' with the
optimizer turned on (Ultrix 4.1, MIPS C compiler version 2.1) breaks the
routine TrackPicValues().  I haven't been able to verify this behavior, but
if you're building on this sort of system, you may want to turn optimization
off.

IRIS/HP/Other SysV-based machines:  If you find XV 'going out to lunch' when
you click on any of the buttons in the controls window, (or do any of a 
number of other things), it is almost certainly a matter of configuring the 
'Timer()' function (in xvmisc.c) to correctly wait the requested number of
milliseconds.  This is one of those things that doesn't seem to be very
well nailed down in the different variants of Unix.  IF you experience
problems, take a look at that function, and add an '#ifdef' for your machine 
that makes it use the whatever the proper 'sleep for some number of 
milliseconds' call on your machine.  (Could be poll(), usleep(), setitimer(),
or possibly select(), and probably some others.)


Once you've built the program succesfully, copy the programs 'xv' and
'bggen' and 'vdcomp' (if you want PDS/VICAR support) to wherever you
like your binaries to live, and copy the files 'docs/xv.man' and
'docs/bggen.man' to the approprate man-page directory.  Don't forget
to change the suffixes appropriately.  'imake' users can just say
'make install' and 'make install.man', with any luck.

Note: also included in this distribution (in the unsupt directory) is
'getweather', a dopey little shell script that you may want to run in
a crontab entry every hour, on the half-hour or so.  It will
automagically go out and get the current US weather map via anonymous
ftp, and stick it in some standard place (normally /usr/local/lib/weather.gif).

Finally, print out a copy of docs/xvdocs.ps on a PostScript printer.  If you
are unable to do so, and would like a printed copy of the manual, contact
the author for details.  (Or donate $25!)

Note:  If you are using 'transcript 2.1' to drive your PostScript printer,
you may run into a problem where the xvdocs.ps file prints in the wrong font
(courier, or something, instead of helvetica).  This seems to be caused by
'psrv', which tries to reverse the pages of all PostScript files.  It fails
on this PostScript file.  You (or the local system administrator) can 
temporarily fix this by replacing the line:
  'REVERSE = /pkg/lib/ps/psrv'
with
  'REVERSE = /bin/cat'
in the file /pkg/lib/ps/psint.sh.  (Your pathnames may vary.)


Caveats
-------

XV has been developed on a Sun 4/280 running SunOS 4.1, using both the normal
'cc' and gcc-1.37 compilers.  There shouldn't be anything grotesque enough
in the code to break any other compilers.  (Though 'optimizers' from HP are
quite another story...)

The viewing environment has mainly been an IBM RS6000 with an 8-bit
color display.  It has been tested with MWM, TWM, OLWM, TVTWM, and
DXWM, in roughly that order of thoroughness.  (ie, I personally use
MWM, and most of the folks in the GRASP Lab use TWM.)

I have personally compiled and tested it on the following systems: Sun
4 running SunOS 4.1, VAXstation 3500 running Ultrix 3.0, MicroVax II
running Ultrix 2.0, DecStation 3100 running UWS 3.0, IBM RISC
System/6000 running AIX 3.1.

It has displayed on the following systems:  IBM RT (8-bit color), Sun 3 
(1-bit B/W), Sun 3 (8-bit grayscale), Sun 4 (1-bit B/W), MicroVax II (8-bit
color), MicroVax II (4-bit grayscale), a variety of HPs (4-bit color, 6-bit 
color, 8-bit color, and 24-bit color), and Visual, NCD, Tektronix, and
HDS X terminals (1-bit B/W and 8-bit color).

'vsprintf.c' has been included for the benefit of those on machines that
don't have it.  (Basically, machines running 'vanilla' BSD 4.3)


Bizarrities
-----------

There are some known problems with running XV in conjunction with 'dxwm'.
I'm hoping that that is now a defunct window manager, and that everybody who 
was using that will switch to mwm.  Whether this hope is well-founded or not 
is another matter entirely.  See the DXWM option in the Makefile/Imakefile.


Problems with TWM and TVTWM
---------------------------

XV would appear to exercise a pair of bugs in the version of TWM in MIT's
X11R4 Standard Distribution tape.  Perhaps they've been fixed by now.

Colormap Installation: under twm, if you have multiple XVs running,
and each has their own colormap, sometimes the colormap doesn't get
properly installed if you move the mouse directly from one XV to the
other, quickly, so that it doesn't see the mouse go into the root
window, or any other window.  If you move the mouse outside the window
and move it back in, it SHOULD install the colormap correctly.

Colormap Installation: Note, if an alternate colormap is installed, it
will ONLY be installed when the mouse is inside the IMAGE window.  It
will not be installed when the mouse is in any other XV windows
(except, possibly, the color editor window).  This is because I can't
guarantee that the other windows will still have contrasting
foreground/background colors when the alternate colormap is installed.
It is assumed that if you put the mouse in a window, you will want to
use that window, so you'd better be able to READ that window...

There's a bug in my version of TWM that creeps up if you have
titlebars turned off.  Essentially, XV tells the window manager to
make the window a certain size.  TWM (wrongly) adds enough room at the
top to put its title bar there, but doesn't draw it, since titlebars
are turned off.  XV gets back a ConfigureNotify event on the window
with the new size, which is large by 20-odd pixels in height.  

There *used* to be a '-twmkludge' option in the previous version of xv
to 'work around' this problem.  Unfortunately, this workaround introduced
more problems than it solved, and has since been removed.  The current
thinking is:  if you're using TWM, you should probably be using titlebars.
If you insist on not having titlebars, and your TWM doesn't behave properly,
you should fix TWM.  (It's a one-line fix, and I'll gladly send it to anybody
who asks for it.)


Copyright Notice
----------------
Copyright 1989, 1990, 1991, 1992 by John Bradley 
              and the University of Pennsylvania

Permission to use, copy, and distribute for non-commercial purposes,
is hereby granted without fee, providing that the above copyright
notice appear in all copies and that both the copyright notice and this
permission notice appear in supporting documentation. 

The software may be modified for your own purposes, but modified versions
may not be distributed without prior consent of the the author.

This software is provided "as is" without any express or implied warranty.

The author may be contacted via:
    US Mail:   John Bradley
               GRASP Lab, Room 312C
               3401 Walnut St.  
               Philadelphia, PA  19104

    Phone:     (215) 898-8813
    EMail:     bradley@cis.upenn.edu       


If you'd like to do something with XV that the copyright prohibits (such
as include it in a commercial product), please contact the author (preferably
through email).  Arrangements can probably be worked out.

