This file contains instructions for compiling the xgobi
executable.  If you wish to use XGobi in conjunction with S,
you will also want to follow the instructions below for the
installation of the S function.

1) Compile xgobi

a)  Find the X libraries and include files

  First determine where the X libraries and include files live on your
  system.  The top-level X11 directory might be called /usr/X11 or
  /usr/local/X11, with subdirectories include and lib; alternatively, the X
  libraries and include files may be merged with other system files in
  /usr/include and /usr/lib.

b) Edit the Makefile to point to X

  Edit the XGobi Makefile, changing the following two lines to point to the
  X11 include files and libraries on your machines.

  IDIR= -I/usr/local/pkg/X11/include
  LDIR= -L/usr/local/pkg/X11/lib

c) Install the help directory; edit the Makefile again

  In order to use the XGobi help and print facilities, you need to
  choose a parent directory in which the help and ps subdirectories
  can be found and then edit the Makefile so that the variable
  XGOBIDIR points to that directory.

d) Make xgobi

  Just type 'make' and a new version of XGobi will be compiled.

2) Install the S function

a)  Edit the file Sfunction

  The file Sfunction contains the definition of the XGobi S
  function, named xgobi().  Find the line in which the pathname of
  the XGobi executable is specified, and edit it to point to your copy.

b)  Source Sfunction

  Initiate a New S session, and then type source("Sfunction") to
  define the XGobi S function.  (XGobi works with New S, whether
  your version came from AT&T or from StatSci.)

c)  Install the help page

  The file doc/Sfunction.d contains the S help page.  Move it to
  .Data/.Help/xgobi.

NOTES
  
a)  Resources

  !! WARNING !! :

  If you had an older version of XGobi on your system, then you
  should make sure that there is no system XGobi resource file
  -- it's no longer needed, and it will now interfere with the
  layout.  It might be in a system directory named app-defaults
  under X's home directory, in a subdirectory named lib or
  Xlib.  Or it might be that you've put it somewhere else and
  set up shell variables to point to it:  check the values of
  $XFILESEARCHPATH, $XUSERFILESEARCHPATH, and $XAPPLRESDIR.

  We've included a file named XGobi.ex as an example of the
  resources you'd be most likely to want to tailor in your own
  resource file (which you would name XGobi).  You (Here you are a
  user, not a system administrator.) may want to adjust some
  colors, for example, or change the size of the variable labels,
  or use a different font.  If you do, then choose a place to put
  that file -- one custom is to use the directory
  $HOME/app-defaults -- and then define XUSERFILESEARCHPATH to be
  $HOME/app-defaults/%N.

  !! WARNING !! :

  A couple of people have had a strange problem with resources,
  where just by creating a resource file and putting one or two
  lines in it, they've ended up with an XGobi window with its
  resources completely haywire.  The solution seems to be to
  make certain that XFILESEARCHPATH does not include any
  reference the the private resource files.  Only
  XUSERFILESEARCHPATH can be safely used for that purpose.

b)  Interaction with S

  When XGobi is initiated from within S, the S data of interest is
  written out to an ascii file, which XGobi then reads in.  When XGobi
  wants to write out coefficients or brushing ids to S, it directly
  writes .Data/filename in the S data format.  We are exploring a
  connection to S that uses UNIX inter-process communication methods.

c)  Space requirements

  Nearly all arrays in XGobi are dynamically allocated, so the only
  limitations you should encounter will be the result of space
  limitations on your machine.  XGobi processes I have observed are
  between 1Mb and 2Mb in size -- X programs run large.

  There are a few arrays whose length is NCOLS: if you plan to read in
  a matrix with more than 200 columns, change the definition of NCOLS
  in xgobitypes.h and recompile.

d)  Documentation

  The 'doc' directory contains xgobiman2.ps, which is a postscript
  copy of the most recent user's manual.  This is the second version
  of the user's manual, rewritten in late 1991 and released in
  February, 1992.  It is, as usual, behind the code, but it has been
  greatly extended since the first version.

  Other papers are available -- send email for references or
  postscript copies.

  The S function is documented in the file Sfunction.d.

  The file xgobi.1 is a manual page for XGobi.

e)  Open Windows

  XGobi does not run under Release 2 of the Sun open windows server,
  though it seems to run just fine under Release 3.  The symptom is
  that most of the buttons in the main panel do not respond to mouse
  clicks.

f) Sun bug

  Thanks to Brian Fitzgerald for the following comment:

  Due to a bug in Sun's ld and/or libXmu.s[ao].4.0, some people
  get this error message:

  ld: Undefined symbol
     _get_wmShellWidgetClass
     _get_applicationShellWidgetClass
  *** Error code 2

  This is described in comp.windows.x FAQ 94.  Sun patches 100170,
  100512, and 100573 fix these bugs.  

  Linking with ... -Bstatic -lXmu -Bdynamic ... is a known
  workaround.

g) Compiling under Solaris

  If we had a proper Imakefile, this wouldn't be a problem,
  but we don't yet.  So if you want to compile xgobi under
  Solaris, change the LIBS line in the Makefile to

  LIBS= ${LDIR} -lXaw -lXt -lXmu -lXext -lX11 -lsocket -lnsl -lm

h) Optimization

  I've experimented a bit with optimization; it's certainly
  possible to optimize the compilation of XGobi, using
  either cc or gcc, I believe, but I've never seen it make
  a difference in execution speed because usually it's the
  graphics operations that limit XGobi's speed.

i) X Bug

  I just tried to read in a fairly big file (about 50000
  points) and got this error message:

X Error of failed request:  BadLength (poly request too large or internal Xlib length error)
  Major opcode of failed request:  68 (X_PolyArc)
  Serial number of failed request:  777
  Current serial number in output stream:  779

  I edited my resource file to use a point (glyphType 7) instead
  of the default filled circle (glyphType 6) for drawing, and
  it worked just fine.  I conclude that there's a bug in the X
  libraries at my site in the circle drawing routines.

  An easy way to handle this for a big data set is to put the
  single line
    *glyphType: 7
  in a file named fname.resources, where fname or fname.dat
  is the name of the file containing the data.


