README

   1 This is XLISP-STAT 2.1 Release 3 for generic bsd systems (with simple
   2 tektronix graphics from the gnuplot system), or X11.
   3
   4 XLISP-STAT is a statistical environment based on a dialect of the Lisp
   5 language called XLISP. Originally developed for the Apple Macintosh,
   6 XLISP-STAT is now also available for UNIX workstations using the X11
   7 window system and for Microsoft Windows. To facilitate statistical
   8 computations, standard Lisp functions for addition, logarithms, etc.,
   9 have been modified to operate on lists and arrays of numbers, and a
  10 number of basic statistical functions have been added.  Many of these
  11 functions have been written in Lisp, and additional functions can be
  12 added easily by a user.  Several basic forms of plots, including
  13 histograms, scatterplots, rotatable plots and scatterplot matrices are
  14 provided.  These plots support various forms of interactive
  15 highlighting operations and can be linked so points highlighted in one
  16 plot will be highlighted in all linked plots. Interactions with the
  17 plots are controlled by the mouse, menus and dialog boxes. An
  18 object-oriented programming system is used to allow menus, dialogs,
  19 and the response to mouse actions to be customized.
  20
  21 Updates to this system will be posted periodically in the anonymous
  22 ftp directory of umnstat.stat.umn.edu (128.101.51.1).
  23
  24 A tutorial introduction to the system is available. It is written
  25 primarily for the Macintosh version, but the differences to the UNIX
  26 version are minor; see below. The tutorial is available as a set of
  27 LaTeX files in xlispstat.doc.tar.Z at the ftp address above.
  28
  29 For further information contact
  30
  31                 Luke Tierney
  32                 School of Statistics
  33                 University of Minnesota
  34                 Minneapolis, Mn. 55455
  35
  36                 luke@umnstat.stat.umn.edu
  37
  38
  39                         COPYRIGHT INFORMATION
  40
  41 *******************************************************************************
  42 * XLISP-STAT 2.1 Copyright (c) 1990, by Luke Tierney
  43 * XLISP version 2.1, Copyright (c) 1989, by David Betz.
  44 *
  45 * Permission to use, copy, modify, distribute, and sell this software and its
  46 * documentation for any purpose is hereby granted without fee, provided that
  47 * the above copyright notice appear in all copies and that both that
  48 * copyright notice and this permission notice appear in supporting
  49 * documentation, and that the name of Luke Tierney and David Betz not be
  50 * used in advertising or publicity pertaining to distribution of the software
  51 * without specific, written prior permission.  Luke Tierney and David Betz
  52 * make no representations about the suitability of this software for any
  53 * purpose. It is provided "as is" without express or implied warranty.
  54 *
  55 * LUKE TIERNEY AND DAVID BETZ DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
  56 * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,
  57 * IN NO EVENT SHALL LUKE TIERNEY NOR DAVID BETZ BE LIABLE FOR ANY SPECIAL,
  58 * INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  59 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  60 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  61 * PERFORMANCE OF THIS SOFTWARE.
  62 *
  63 * XLISP-STAT AUTHOR:
  64 *               Luke Tierney
  65 *               School of Statistics
  66 *               University of Minnesota
  67 *               Minneapolis, MN 55455
  68 *               (612) 625-7843
  69 *
  70 *       Email Address:
  71 *               internet: luke@umnstat.stat.umn.edu
  72 *
  73 * XLISP AUTHOR:
  74 *              David Betz
  75 *              P.O. Box 144
  76 *              Peterborough, NH 03458
  77 *              (603) 924-4145
  78 *******************************************************************************
  79
  80 (David Betz has kindly given his permission to remove the restriction
  81 on commercial use from the copyright. The new copyright is adapted
  82 from the copyright in winterp as distributed with X11 R4.)
  83
  84
  85            MAJOR DIFFERENCES BETWEEN UNIX AND MAC VERSIONS
  86
  87 Examples and sample data sets are located in a library directory. To
  88 access them you can use the functions load-data and load-example. For
  89 example, to load the data sets used in the tutorial technical report
  90 type
  91
  92         (load-data "tutorial")
  93
  94 The library directory is given by the variable *default-path*; data
  95 and examples are in the subdirectories Data and Examples.
  96
  97 The UNIX xlispstat versions are designed to run on a standard
  98 terminal.  This means parentheses matching is not available. If you
  99 are a gnu emacs user you can set up gnu emacs to allow it to run
 100 xlispstat for you.  The files my.emacs and xlispstat.el in the emacs
 101 directory are examples of how to do this.
 102
 103 If you are a vi user you may want to use the -l option for editing
 104 Lisp files.
 105
 106 The basic UNIX version includes some Tektronix graphics based on the
 107 gnuplot routines. The functions plot-points and plot-lines should work
 108 but all other high lever graphics functions will signal an error when
 109 used in this system.  Low level graphics methods will probably result
 110 in a crash.
 111
 112 The X11-based system should operate like the standard unix-based
 113 system, with basic tektronix graphics, when not run under the
 114 appropriate window manager (i. e. on a terminal with the DISPLAY
 115 environment variable set).
 116
 117 Under X11 there is a close button and a menu button. For plot
 118 interaction all mouse buttons are identical. To extend a selection
 119 hold down the shift key as you click.
 120
 121 In the X11 version a "Save to File" is available in the plot menus.
 122 This item brings up a dialog asking for a file name; if the ok button
 123 is pressed an image of the plot is saved as a postscript file.  This
 124 takes a while under X11 (20 - 30 seconds on a sun 3/50).
 125
 126 X11 scroll bars on plots (name-lists in particular) work like xterm
 127 scroll bars.
 128
 129 X11 dialog sliders sliders look something like macintosh sliders.
 130 Sliders and scroll bars are the only items that interpret different
 131 mouse buttons differently, and thus the only point at which a
 132 three-button mouse is assumed: In the body of a slider the left button
 133 decreases by a page increment, the right button increases by a page
 134 increment and the middle button drags the thumb around
 135
 136
 137
 138
 139                           X11 FEATURES/BUGS
 140
 141 Under X11 where plots and modeless dialogs show up on your screen, and
 142 how large they end up being, is up to the window manager. Requests you
 143 make may be honored under one manager but not under another.
 144
 145 Several options can be set using the X11 resource management
 146 facilities.  Options controlling appearance are
 147
 148 xlisp*menu*titles:     on for a title on a menu, off otherwise
 149 xlisp*menu*font:
 150 xlisp*dialog*font:
 151 xlisp*graph*font:
 152
 153 There are also a few options controlling performance. These are
 154
 155 xlisp*graph*fastlines:   on to use 0 width lines
 156 xlisp*graph*fastsymbols: on to use DrawPoints instead of bitmaps
 157 xlisp*graph*motionsync:  on to use XSync
 158 xlisp*graph*icccm:       on to use (almost?) ICCCM-compliant dialogs
 159 xlisp*graph*waitformap   on to wait for MapNotify event before drawing
 160
 161 By default all are on. (This default can be changed by editing the
 162 include file StX11options.h.) That seems to give the best performance
 163 on a DECstation 3100. It may not be the best choice on other
 164 workstations.  You can also use the function x11-options to change
 165 these five options within lisp. The fastlines option will not take
 166 effect immediately when changes this way but will affect the next plot
 167 created. The other two options do take effect immediately.
 168
 169 The only way to set the display to be used is to set the DISPLAY
 170 environment variable before starting up xlispstat.
 171
 172 On some color or greyscale X11 implementations you may get X errors
 173 when you exit from xlispstat. I *think* this is due to a bug in the
 174 X11 server. Try defining the variable SERVER_COLOR_FREE_PROBLEM by
 175 uncommenting its define line in StX11options.h.
 176
 177
 178             FOREIGN FUNCTIONS, DYNAMIC AND STATIC LOADING
 179
 180 Foreign function calling is supported on some UNIX systems. The basic
 181 calling conventions are similar to those in New S and are described in
 182 an appendix to the XLISP-STAT tutorial. To enable foreign function
 183 calling define
 184
 185 FOREIGN_FLAG = -DFOREIGNCALL
 186 FOREIGN_FILE = <system>-foreign.h
 187
 188 where <system> is appropriate for your system. On all supported
 189 systems listed in the src/c/machines directory the configure script
 190 should automatically set things up for dynamic loading. If your system
 191 is not supported, you may be able to adapt one of the existing ones.
 192
 193 At present there is no simple support for users to do static loading,
 194 like in New S. Instead, you can use the EXTRAOBJS and EXTRALIBS
 195 variables in the Makefile. If static loading is important, adding the
 196 S-like facility for user loading should be quite easy.
 197
 198 This (and the use of IEEE arithmetic in printing) is the only aspect
 199 of XLISP-STAT on UNIX systems that involves serious machine
 200 dependencies. If you can live without foreign function calling you can
 201 ignore the src/c/machines directory.