updated version, but need to update installation scripts

[cls.git] / doc / changes.tex

\documentclass{article}
\usepackage{fullpage}
\usepackage{html}

\title{XLISP-STAT 2.1 Release 3\\Beta Release Notes}
\author{Luke Tierney\\School of Statistics\\University of Minnesota}

%%**** fix this!!
\newcommand{\mytilde}{\~{ }}

\newcommand{\param}[1]{{\em $<$#1$>$}}

\newcommand{\funindex}[1]{\index{#1 function@{\tt #1} function}}
\newcommand{\specindex}[1]{\index{#1 special form@{\tt #1} special form}}
\newcommand{\macindex}[1]{\index{#1 macro@{\tt #1} macro}}
\newcommand{\varindex}[1]{\index{#1 variable@{\tt #1} variable}}
\newcommand{\varstarindex}[1]{\index{#1 variable@{\tt *#1*} variable}}
\newcommand{\constindex}[1]{\index{#1 constant@{\tt #1} constant}}
\newcommand{\lkeyindex}[1]{\index{#1 lambda keyword@{\tt \&#1} lambda keyword}}
\newcommand{\setfindex}[1]{\index{#1 setf form@{\tt #1} setf form}}
\newcommand{\keywordindex}[1]{\index{#1 keyword@{\tt :#1} keyword}}
\newcommand{\typeindex}[1]{\index{#1 type@{\tt #1} type}}
\newcommand{\typelistindex}[1]{\index{#1 type@{\tt (#1)} type}}
\newcommand{\lfmtdirindex}[1]{\index{#1 format directive@{\tt \mytilde#1} format directive}}
\newcommand{\lerrtypeindex}[1]{\index{#1 error type@{\tt #1} error type}}
\newcommand{\lfeatureindex}[1]{\index{#1 feature@{\tt #1} feature}}

\newcommand{\lfun}[1]{{\tt #1}\funindex{#1}}
\newcommand{\lspec}[1]{{\tt #1}\specindex{#1}}
\newcommand{\lmac}[1]{{\tt #1}\macindex{#1}}
\newcommand{\lvar}[1]{{\tt #1}\varindex{#1}}
\newcommand{\lvarstar}[1]{{\tt *#1*}\varstarindex{#1}}
\newcommand{\lconst}[1]{{\tt #1}\constindex{#1}}
\newcommand{\llkey}[1]{{\tt \&#1}\lkeyindex{#1}}
\newcommand{\lsetf}[1]{{\tt (setf #1)}\setfindex{#1}}
\newcommand{\lkeyword}[1]{{\tt :#1}\keywordindex{#1}}
\newcommand{\ltype}[1]{{\tt #1}\typeindex{#1}}
\newcommand{\ltypelist}[1]{{\tt (#1)}\typelistindex{#1}}
\newcommand{\lfmtdir}[1]{{\tt \mytilde#1}\lfmtdirindex{#1}}
\newcommand{\lerrtype}[1]{{\tt #1}\lerrtypeindex{#1}}
\newcommand{\lfeature}[1]{{\tt #1}\lerrtypeindex{#1}}

\newcommand{\CL}{Common Lisp}
\newcommand{\XWIN}{{\em X11}}
\newcommand{\XL}{XLISP}
\newcommand{\TAXL}{XLISP-PLUS 2.1g}
\newcommand{\XLS}{XLISP-STAT}
\newcommand{\NIL}{{\tt nil}}
\newcommand{\TRUE}{{\tt t}}

\newenvironment{note}{\begin{quotation}\noindent\em{}}{\end{quotation}}
\newenvironment{warning}{\begin{quotation}\noindent\em{}}{\end{quotation}}
\begin{htmlonly}
\newenvironment{note}{\begin{quotation}}{\end{quotation}}
\newenvironment{warning}{\begin{quotation}}{\end{quotation}}
\end{htmlonly}

\newenvironment{CLSpec}[2]{%
  \begin{trivlist}%
  \item[]%
    {#1} \hfill [{\em {#2}}]\\ \begin{latexonly}\em{}}%
  {\end{trivlist}}

\makeindex
\begin{document}
\maketitle

\tableofcontents

\section{Introduction}
This note outlines some of the changes in the new \XLS\ release from
Release 2. There are a large number of minor changes, mostly in the
basic \XL\ system. These changes move the basic \XL\ closer to \CL, and
include the addition of packages, multiple values, other improvements
from \TAXL, and a byte code compiler. Wherever possible, changes have
been made in such a way as to maintain backward compatibility. In a
few, hopefully minor, cases this was not possible; these cases should
be noted below.

\begin{note}
If you notice anything that has changed and is not mentioned here,
please let me know. If any change causes exceptional grief, please let
me know as well.
\end{note}


\section{Changes to System Features}
\subsection{Debugging and Evaluation}
\label{Subsection:Debugging}
The error handling in \XLS\ is now based on the \CL\ condition system.
When debugging is turned on, an error enters a break loop. The break
loop presents a list of the available restarts, and the function
\lfun{continue} can be used to select a restart:
\begin{verbatim}
Error: illegal zero argument
Break level 2.
To continue, type (continue n), where n is an option number:
 0: Return to break level 1.
 1: Return to Lisp Toplevel.
2>
\end{verbatim}
When debugging is not turned on, an indication of the function in
which the error occurred is printed before the system returns to the
top level:
\begin{verbatim}
Error: illegal zero argument
Happened in: #<Subr-/: #c49e20>
>
\end{verbatim}

The \lfun{baktrace} function now accepts a second optional argument
that determines whether it prints function arguments or not. Supplying
\NIL\ as this argument suppresses argument printing. The default value
for this argument is the value of the special variable
\lvarstar{baktrace-print-arguments}.

The back trace does not show entries for byte compiled functions or
internal functions called from byte compiled code.

The old \lfun{step} function has been replaced by a new one from the
the stepper file included in \TAXL.  Detailed documentation for this
new \lfun{step} is given in Appendix \ref{Appendix:Stepper}. The
Macintosh version of \lfun{step} no longer has a dialog interface.

The action taken in response to a user interrupt is now customizable.
If the value of the special variable \lvarstar{interrupt-action} is
\NIL, interrupts are ignored. Otherwise, the value should be a
function of no arguments that is called in response to an interrupt.
The default value is the \lfun{top-level} function that returns to the
top level.

Debugging may be affected by the handling of macros. If the special
variable \lvarstar{displace-macros} is non-\NIL, then macros are spliced
into the code after they are expanded. This means macros are only
expanded once and can significantly improve speed of interpreted code.
But it may make code used in stepping less readable, so it may be
useful to set this variable to \NIL\ during debugging.

\XL\ can now be more strict in checking for keywords. If
\lvarstar{strict-keywords} is non-\NIL, then specifying keyword
arguments not defined for a function signals an error unless the
function is defined using \llkey{allow-other-keys} or the keyword
arguments include \lkeyword{allow-other-keys} with a non-\NIL\ value.
If the value of \lvarstar{strict-keywords} is \NIL, then unmatched
keywords are always ignored. For now, this is the default setting.

\begin{note}
  Some graphical control over the system option variables, choosing
  restarts, etc. is clearly needed.
\end{note}

\subsection{Top Level and Saved Workspaces}
It is now possible to save workspaces and customize the initialization
and top level functions. The function \lfun{save-workspace} takes a
single argument, the name of the saved workspace file. It closes all
windows and menus, creates the saved workspace, and exits from the
system. The workspace file is created with a {\tt .wks} extension.

On UNIX, and eventually MS Windows, a saved workspace can be loaded by
specifying {\tt -w}{\it file.wks} (with no spaces) as a command line
argument.  On a Macintosh, you can double click a workspace. If no
workspace argument is given, the workspace named {\tt xlisp.wks} in the
startup directory is used if one is available. Otherwise, a file {\tt
  init.lsp} is loaded. (So {\tt init.lsp} is not loaded if a workspace
is found). It is currently not possible to load a new workspace once
the system has started up.

After loading a workspace or the {\tt init.lsp} file, files on the
command line (or files that where double clicked on the Macintosh) are
loaded. The command line used to start up \XLS\ is also made available
as a list of strings in the variable \lvarstar{command-line}. (On the
Macintosh this variable currently does not contain anything useful.)
Next, the functions of no arguments in the list that is the value of
\lvarstar{startup-functions} is called. One of the functions in the
default value of this variable is responsible for loading the {\tt
  statinit.lsp} file. Finally, the function \lvarstar{top-level-loop} is
called. This function is called again each time the system is reset to
the top level.

The installed versions of xlispstat are now set up to start from a
default {\tt xlisp.wks} saved workspace rather than by loading a set
of {\tt .lsp} files. Compiled versions of files needed less frequently
and help information are still kept in a library and loaded on demand.

\begin{warning}
  The basic objective here is to make startup and the top level
  customizable. The details are likely to change somewhat as I get
  things straightened out on the Mac and Windows versions.
\end{warning}
\begin{warning}
  The ability to save workspaces (and to byte compile files) creates a
  problem for using \verb|#+| and \verb|#-| to test for runtime
  properties. These tests occur when a file is read. But a file can be
  read on a computer with a color display and the definitions can then
  be used from a saved workspace on a monochrome display, for example.
  As a result, \verb|#+| and \verb|#-| should only be used for
  properties, such as the operating system type, that will not change
  from one invocation to another. Runtime tests, such as the function
  \lfun{screen-has-color} should be used instead. All system files
  should have been rewritten with this in mind.
\end{warning}

\subsection{IEEE NaN's and infinites}
Three constants are defined to support IEEE NaN's and infinities:
\begin{center}
  \begin{tabular}{ccc}
    \lconst{positive-infinity} & \lconst{negative-infinity} &
    \lconst{not-a-number}
  \end{tabular}
\end{center}
When printing an infinity or a NaN when \lvarstar{print-escape} is
\NIL, the appropriate symbol is printed using the {\tt \#.} read
macro. For example,
\begin{verbatim}
> positive-infinity
#.POSITIVE-INFINITY
\end{verbatim}
This insures that all numbers are printed in a readable form, even
infinities.  All NaN's are printed identically, there is no provision
for preserving variations among NaN's.
\begin{note}
  There is currently no provision for checking for a NaN or infinity.
  There probably ought to be lisp equivalents of the IEEE-recommended
  functions {\tt isnan} and {\tt finite}.

  At present the symbols used here are external in the XLISP
  package.As they are nonstandard, they should probably be internal in
  a system package.
\end{note}

\subsection{New Garbage Collector and Memory Requirements}
The original mark-and-sweep collector of \XL\ has been replaced by an
in-place two-generation generational collector. This means that there
are now two types of garbage collections, minor and major ones.  Minor
collections occur relatively frequently but are very fast.  Major ones
occur rather rarely in typical usage, and are only marginally slower
than mark-and-sweep collections. The net effect should be to reduce
garbage collection pauses significantly.

In addition, the system is more aggressive about allocating more space
when a substantial fraction of the allocated space is in use. This
should also reduce the number of collections, but may lead to greater
process memory growth. The impact on limited memory systems such as a
Macintosh with a small partition is not clear at this point.

The new garbage collector requires more storage space per Lisp node.
The overall requirements are increased by around 30\%-50\%. The default
partition on the Macintosh will therefore be increased to 3M.

\subsection{Missing and Non-Numerical Data in Graphs}
It is now possible to give plotting functions data sequences that
contain non-numerical values, such as missing value codes.  Points
with one or more non-numerical coordinates are marked internally as
masked. This means they are not drawn and are not considered for the
calculation of scaling information.

Any non-numerical lisp item can be used as a missing data code, but
\NIL\ should be avoided since it also represents the empty list and
can cause confusion in vectorized operations.

\subsection{Working Directories and Directory Function}
The function \lfun{get-working-directory} returns a string naming the
current working directory. The function \lfun{set-working-directory}
sets the working directory to the directory specified by its string
argument.  If the change of directory succeeds, \TRUE\ is returned.
Otherwise, \NIL\ is returned.

On the Macintosh these functions will fail if the length of the
directory name is greater than 255.

A minimal version of the \lfun{directory} function is now available.
The wildcard character for all versions is {\tt *} -- even for the
macintosh. By default, \lfun{directory} only lists regular files. If a
non-\NIL\ value is given for the \lkeyword{all} keyword argument, then
all files and directories are included. Thus
\begin{verbatim}
(directory "*")
(directory "*" :all t)
\end{verbatim}
should list all regular files and all files, respectively, in the
current working directory.

\subsection{Version Information}
In addition to the feature \lfeature{xlisp}, starting with release 3.39
the new version also defines \lfeature{xlisp-plus}. The constants
\lconst{xls-major-release} and \lconst{xls-minor-release} contain
the major and minor release numbers of the executable. For release
3.39, for example, these are 3 and 39, respectively.

\subsection{Content Backgrounds}
The protocol used by the standard \lkeyword{redraw-content} methods
has been augmented to support maintaining a background for plot
contents. Instead of erasing the content area before drawing the
content, these methods now send the \lkeyword{clear-content} message.
The default method for this method clears the content area. By
overriding this method, you can draw any background you want to
maintain.

Unless you want to handle clearing the background yourself, you should
begin your method with a call to \lfun{call-next-method}

A simple example: The code
\begin{verbatim}
(setf p (plot-points (normal-rand '(10 10))))

(defmeth p :clear-content ()
  (call-next-method)
  (send self :frame-rect 50 50 100 100))
\end{verbatim}
sets up a plot that contains a rectangle in its background.

This new protocol is still experimental and may change if a better
design is found.

\section{Changes in Specific Implementations}

\subsection{Changes in the UNIX/X11 Version}
The initial workspace and the default directory can be specified on
the commandline as {\tt -w}{\em file.wks} and {\tt -d}{\em dir},
respectively.

Upon startup of the \XWIN\/ version of \XLS\ the system merges
resources found in file
\begin{center}
  \tt
  /usr/lib/X11/app-defaults/Xlisp
\end{center}
then ones found in the file {\tt Xlisp} in the directory named by the
environment variable {\tt XAPPLRESDIR}, and finally the resources of
the display. Resources can thus be specified in all three places, with
the display's resources having highest precedence.

The functions \lfun{popen} and \lfun{pclose} from {\tt winterp} have
been added to the UNIX version to allow streams connected to processes
to be created.
\begin{note}
  The interface to these functions may change.
\end{note}

\subsection{Macintosh Changes and System 7 Support}
Several options can now be set in a preferences file. This file is a
text file, is must be called {\bf XLS Preferences}, and it must be
located in the same folder as the application.  Each line in the file
represents an option specification. The first word identifies the
option, the remaining words make up the option data. The option names
currently supported are
\begin{center}
\begin{tabular}{lll}
{\bf EditFontName} & {\bf EditFontSize} & {\bf EditFontStyle}\\
{\bf ListenerFontName} & {\bf ListenerFontSize} & {\bf ListenerFontStyle}\\
{\bf GraphFontName} & {\bf GraphFontSize} & {\bf GraphFontStyle}\\
{\bf Workspace} & {\bf Color}
\end{tabular}
\end{center}
the {\bf Workspace} entry specifies a default workspace to use. Unless
specified separately, listener font properties are identical to editor
font ones. As an example, a preferences file containing the entries
\begin{verbatim}
EditFontName Courier
EditFontSize 12
Workspace Alliance Drive:MPW:Programs:New XLS:xlisp.wks
Color off
\end{verbatim}
specifies a 12-point bold italic Courier font for editor windows, an
alternative workspace, and turns color off. Turning color off may be
useful if the screen size and number of colors used would require too
much memory for the background buffer.

The dashed line separating system apple menu items from application
items is now supplied internally -- a dash item is now no longer
necessary. This should result in a single dash under both System 6 and
System 7.

Under Macintosh System 7 \XLS\ now continues to operate while in
background. If the variable \lvarstar{use-notifier} is not \NIL, then
notification occurs when a modal dialog is to be opened or when the
system tries to read from the listener. The notification consists of a
beep, a flashing icon on the system menu, and a diamond marking the
application name in the system menu.

Minimal support for examining processes on the current computer and
for sending local or remote apple events is now available. The
function \lfun{launch-application} takes either a file name string
argument or an application signature argument and launches the
corresponding application. By default the application is launched in
foreground; specifying an optional argument as non-\NIL\ causes the
application to be launched in background. The value returned is a
process information record if the launch succeeds, or \NIL\ if the
launch fails. Process information is currently encoded as a list of
the process name, process signature, process serial number, time of
process start and run time of the process. This representation may
change.
\begin{note}
  Currently applications can only be found by signature if they are
  located on the boot volume.
\end{note}
Application signatures used by \lfun{launch-application} are integers
representing four-character character constants. The function
\lfun{encode-signature} converts strings with the corresponding string
of characters to the signature code. For example,
\begin{verbatim}
> (encode-signature "X1St")
1479627636
\end{verbatim}
computes the signature code for {\tt X1St}, the signature for \XLS.

A list of process information records for all running processes is
returned by \lfun{get-process-list}, and \lfun{get-front-process}
returns the process information for the current front process. The
\lfun{set-front-process} function takes a process name string,
signature code, or process information record and makes the
corresponding process the front process. If the argument is a string
or integer, then the first process, if any, with the corresponding
name or signature is used.

\XLS\ now responds to the four required Apple events (Open
Application, Open Documents, Print Documents, and Quit Application).
The Print event is ignored. Currently new workspaces can only be
opened at startup (i.~e. as part of the initial high level event), but
text files can be opened by double clicking them or dragging them onto
the \XLS\ icon at any time. In addition, the Do Script event is
supported (class {\tt 'misc'}, event {\tt 'dosc'}). This event takes a
direct parameter that is a string and interprets it as a lisp
expression. The expression is evaluated, the result is printed to a
string, and the string is returned as the direct parameter of the
result. For example, if you have the {\tt Alpha} shareware editor,
then from a Tcl shell window you can send an apple event to a running
\XLS\ process asking \XLS\ to make a system beep sound:
\begin{verbatim}
Alpha.5.55> dosc -c 'X1St' -s "(sysbeep)"
NIL
\end{verbatim}

You can also send Apple events to processes on the same or on remote
computers using the function \lfun{send-apple-event}. At the moment
this function allows you to send events that contain parameters that
are strings, integers, or floating point numbers. If a result is
expected it should contain no required parameters or a required direct
parameter that can be coerced to a string. In particular, this allows
Do Script events to be sent to other \XLS\ processes. The
\lfun{send-apple-event} function has three required parameters, two
four-character strings specifying the event class and type, and an
address specifier for the event's receiver. The address can be
\begin{itemize}
\item The symbol \TRUE, which means the current application is the
  target, a self send.
\item A string representing a process name on the local computer.
\item An integer representing the signature code of a process on the
  current computer.
\item A process information record as returned by
  \lfun{launch-application} or by \lfun{get-process-list}.
\item A target specifier as returned by
  \lfun{browse-apple-event-targets} or by
  \lfun{get-apple-event-target}.
\end{itemize}
Several keyword arguments are also accepted:
\begin{description}
\item \lkeyword{data}: Either \NIL, the default, or a string to be
  used as the direct parameter of the event, or a list of lists.  If a
  list of lists is used, then the sublists must contain two items, a key
  string identifying the parameter (such as {\tt "----"} for a direct
  parameter) and the data item. Data items can be integers, floating
  point numbers or strings.
\item \lkeyword{wait-reply}: Wait for a reply if non-\NIL, the default.
\item \lkeyword{timeout}: The symbol \TRUE\ for the default timeout
  (about a minute), an integer for a specific value, or \NIL\ for no timeout.
  If not supplied, the default timeout is used.
\item \lkeyword{can-switch-layer}: Whether or not the receiver should
  be allowed to come to the front if it requires interaction.
\end{description}
As an example,
\begin{verbatim}
(send-apple-event "aevt" "abou" "Finder")
\end{verbatim}
sends the Finder an apple event asking it to present its {\bf About
  This Macintosh} dialog box.

To locate a target on the local machine or a machine on the network
you can use the interactive \lfun{browse-apple-event-targets}
function. This function presents a dialog box that lists available
processes for all Macintoshes on a local network; if the local network
is connected to an internet the dialog also presents a list of
AppleTalk zones to choose from. Several keyword arguments are
available for controlling the appearance of the dialog:
\begin{description}
\item \lkeyword{prompt}: A prompt string to show at the top of the dialog.
\item \lkeyword{application-list-label}: A string to show over the
  program list item.
\item \lkeyword{type}: The connection type, which defaults to {\tt
    "PPCToolBox"}.
\end{description}
By default, all targets with suitable permissions are shown. The set
of targets can also be restricted with two additional keyword
arguments:
\begin{description}
\item \lkeyword{name}: A string specifying the name of the application
  to link to. Only applications with this name are shown.
\item \lkeyword{signature}: An integer signature code. Only
  applications with this signature are shown.
\end{description}
You can also locate applications to link to without using a dialog
box.  The \lfun{get-apple-event-target-list} function returns a list
of all targets available on a particular machine. By default the local
machine is examined. Alternatives can be specified by keyword
arguments:
\begin{description}
\item \lkeyword{object}: The name of a macintosh.
\item \lkeyword{type}: The connection type, which defaults to {\tt
    "PPCToolBox"}.
\item \lkeyword{zone}: An AppleTalk zone name. 
\end{description}
The function \lfun{get-apple-event-target} returns a single target, or
\NIL\ if none is found. It requires one argument, an application name
string or signature code, and also accepts the same keyword arguments
as \lfun{get-apple-event-target-list}. If there are several possible
matches for the name or signature given, an arbitrary choice is
returned.

As an example, suppose an \XLS\ process is running on another
Macintosh named {\tt "Fred's Macintosh"} and that all permissions are
suitably set. We can send a {\tt sysbeep} command to this Macintosh
using the expression
\begin{verbatim}
(let* ((sig (encode-signature "X1St"))
       (target (get-apple-event-target :object "Fred's Macintosh")))
  (when target
        (send-apple-event "misc" "dosc" target :data "(sysbeep)")))
\end{verbatim}
If successful, the expression returns the string {\tt "NIL"}.

\begin{note}
  The support included for Apple events is rather minimal. The main
  reason I have not yet made it more extensive is that I don't know
  what kinds of events will be most useful for communicating with
  other applications. If anyone has any ideas or would like to help
  extending this, please let me know.
\end{note}

One problem that comes up on the Macintosh is the need to account for
the screen size. Currently a background bitmap the size and depth of
the primary screen is allocated within the partition. The size of this
bitmap is
\begin{displaymath}
  \frac{\mbox{width}\times\mbox{height}\times\mbox{depth}}{8}.
\end{displaymath}
For a $512\times320$ monochrome display this is fairly trivial, and a
3M partition should be adequate for most purposes (though this of
course depends on what is loaded). But for a $1024\times1024$ display
using 32-bit color, this is 4M. At the moment, this calculation needs
to be done manually and you need to make adjustments to your partition
accordingly. I will try to come up with a better solution in the
future.

The \lfun{open-file-dialog} function now accepts a third optional
parameter for specifying the file types to show. If this parameter is
\NIL, all files are shown. If it is a string or a list of strings,
only files of the corresponding types are shown.The sefault is {\tt
  "TEXT"}. At present,at most four types can be given; this limitation
will be removed in the future.

\subsection{Changes in the Microsoft Windows Version}
The new standard version for Microsoft Windows now requires at least a
386 processor and Windows version 3.1. This version is still based on
16 bit windows and hence still has the same limitations on vector
sizes as previous versions. In addition, a Win32 version is now
available that removes some of these limitation.

In line with the use on Windows 3.1 as the base, accelerators for the
edit menu items in WXLS and in LSPEDIT have changed to the ones used
in the 3.1 accessories Write and Notepad: {\em Ctrl-X} for Cut, {\em
  Ctrl-C} for Copy, etc.. The interrupt key combination is now {\em
  Ctrl-Break}. The functions \lfun{open-file-dialog} and
\lfun{set-file-dialog} now use the new standard Windows open and save
dialogs and also optionally set the working directory to the directory
containing the selected file.

The listener has been modified so that is can now hold a more
reasonable amount of text and should no longer run out of memory.

Modeless dialogs, such as slider dialogs, are now MDI clients rather
that popup windows.

The need to set environment variables has been eliminated. Instead,
information about the location of startup files can now be placed in a
private initialization file, {\tt wxls.ini} for the 16-bit version and
{\tt wxls32.ini} for the 32-bit version, in the Windows system
directory. This file can contain several variables in sections {\tt
[Xlisp]}, {\tt [Listener]}, and {\tt [Graphics]}:
\begin{center}
  \begin{tabular}{ll}
    Section & Variables\\
    \hline
    {\tt [Xlisp]} & {\tt Libdir}, {\tt Workspace}\\
    {\tt [Listener]} & {\tt Font}, {\tt FontSize}\\
    {\tt [Graphics]} & {\tt Font}, {\tt FontSize}, {\tt Color}\\
    \hline
  \end{tabular}
\end{center}
The {\tt Libdir} variable should be set to the directory containing
the executable and runtime files; this should be done at installation
time by loading {\tt config.lsp}. The {\tt Workspace} variable allows
an alternate initial workspace to be specified. Both can be overridden
on the command line by specifying {\tt -d} or {\tt -w} options,
respectively. The {\tt Color} variable can be used to turn color use
off if allocating a color background buffer would require too much
memory. As an example, a {\tt wxls.ini} file containing
\begin{verbatim}
[Xlisp]
Libdir=C:\WXLS
[Listener]
Font="Courier New Bold"
FontSize=13
[Graphics]
Color=off
\end{verbatim}
specifies a library directory, a listener font, and turns color off.

The initial workspace and the default directory can also be specified
on the commandline as {\tt -w}{\em file.wks} and {\tt -d}{\em dir},
respectively.

A very minimal DDE interface is provided. The interface is very simple
and based on DDEML. As a server, WXLS allows to connections to the
topic {\tt XLISP-STAT} under the service name {\tt XLISP-STAT}. It
accepts two kinds of transactions:
\begin{itemize}
\item Execute transactions in which the command is a sequence of lisp
  expressions. The LSPEDIT application sends the current selection as
  an execute transaction when the {\bf Eval Selection} menu item is
  chosen.
\item Request transactions or the item {\tt VALUE}. This returns a
  string with a printed representation of the value returned by the
  last expression in the most recent execute transaction of the
  conversation.
\end{itemize}
As a client, there are three functions you can use that correspond
fairly closely to their DDEML equivalents: \lfun{dde-connect},
\lfun{dde-disconnect}, and \lfun{dde-client-transaction}.

\lfun{dde-connect} takes two arguments, strings naming a service and
a topic.  The topic string is optional; it defaults to the service
string. The return value is a descriptor of the conversation if the
connection is established, otherwise it is \NIL. At the moment
conversation descriptors are integer indices into a table, and the
number of concurrent conversation is limited to 30. This may change.

\lfun{dde-disconnect} takes a conversation descriptor and attempts to
close the conversation. If successful it returns \TRUE, otherwise \NIL.
If dde-disconnect is called with no arguments then all currently
active conversations are terminated. In this case the return value is
\TRUE\ if any are terminated, \NIL\ if not.

\lfun{dde-client-transaction} requires a conversation descriptor as
its first argument. The remaining arguments are keyword arguments:
\begin{description}
\item \lkeyword{type}: should be \lkeyword{request} or
  \lkeyword{execute}; default is \lkeyword{execute}.
\item \lkeyword{data}: a string, currently only used by execute
  transactions.
\item \lkeyword{item}: an item name string, currently only used by
  request transactions.
\item \lkeyword{timeout}: a positive integer specifying the timeout in
  milliseconds. The default is 60000.
\end{description}
The return value is \TRUE\ if the transaction is successful, \NIL\ if
not.

As an example, you could have WXLS communicate with WXLS by DDE (why
you would want to I do not know, but it works):
\begin{verbatim}
> (dde-connect "xlisp-stat")
0
> (dde-client-transaction 0 :data "(+ 1 2)")
T
> (dde-client-transaction 0 :type :request :item "value")
"3"
> (dde-disconnect 0)
T
\end{verbatim}
You can also communicate with the program manager:
\begin{verbatim}
> (dde-connect "progman")
0
> (dde-client-transaction 0 :data "[ShowGroup(Main,1)]")
T
> (dde-client-transaction 0 :type :request :item "Groups")
"Main\r
Accessories\r
Applications\r
Microsoft C/C++ 7.0\r
Software Development Kit 3.1\r
Win32 Applications\r
Adobe\r
Borland C++ 4.0 Online Books\r
Borland C++ 4.0\r
StartUp\r
Games\r
Borland C++ 3.1\r
Pocket Tools\r
XLISP-STAT Programs\r
"
> (dde-disconnect 0)
T
\end{verbatim}
The first transaction is an execute transaction that opens the Main
group's window. The second is a request that obtains a list of the
current groups.
\begin{warning}
  This DDE interface is experimental and may change. For the moment it
  seems adequate for providing configuring the integration of WXLS
  into Windows during setup.
\end{warning}

The functions \lfun{msw-get-profile-string} and
\lfun{msw-write-profile-string} can be used to access and modify user
preference information.  They require three and four arguments,
respectively. The first and second arguments specify the section and
item names as strings, and the last argument specifies the preference
file name. A preference file name of \NIL\ refers to the system
preference file. For \lfun{msw-write-profile-string} the third
argument is a new value. This can be a string or \NIL; if it is \NIL,
the entry is deleted. This function deletes a section if the item
argument is \NIL.

The function \lfun{msw-win-exec} is a synonym for the \lfun{system}
function.  On failure it now returns two values: \NIL\ and a numerical
error code. The \lfun{msw-win-help} function has been modified to use
keyword symbols to identify help request types.

Both 16-bit and 32-bit versions can use DLL's, but only 16-bit and
32-bit DLL's, respectively.

\section{Improvements in Common Lisp Support}
This section outlines changes in \CL\ compatibility. The subsections
are numbered according to the chapters of Steele \cite{CLtL2}.
Detailed descriptions of standard functions and macros are given in
Steele \cite{CLtL2}.

\subsection{Introduction}
No changes.

\subsection{Data Types}
Vectors and arrays containing typed elements, such as fixnums or
floats, are now partially supported. This support will be completed in
a future release.

Other new data types are hash tables and packages.

\subsection{Scope and Extent}
\label{Subsection:Scope}
The handling of \lspec{block}/\lspec{return-from} and
\lspec{tagbody}/\lspec{go} has been fixed to give the block names and
go tags lexical scope, in compliance with the \CL\ specification. In
the previous implementation they had dynamic scope.

\subsection{Type Specifiers}
The \lfun{typep} function accepts specialized type specifications,
such as {\tt (member 1 2 3)} or {\tt (vector t *)}. New type names can
be defined using the \lmac{deftype} macro.

The function \lfun{coerce} has been modified to be more \CL\
compliant. In particular, it is no longer possible to use it to coerce
an array to a list. The effect of the old coercion can be achieved
with the new \lfun{array-to-nested-list} function.

\subsection{Program Structure}
Special variables are now available. Variables that have been
proclaimed special using the \lfun{proclaim} function or that were
defined using \lmac{defvar}, \lmac{defparameter}, or
\lmac{defconstant} are dynamically scoped in all uses.  It is not
possible to declare variables special locally, but \lmac{progv} can be
used for making variables locally special.

The macro \lmac{defvar} now leaves unbound variable unbound if it is
not given a value argument.

Proper keyword argument handling is now possible; see Section
\ref{Subsection:Debugging} for more details.

The special form \lspec{eval-when} for controlling time of evaluation
is now defined. It is defined in accordance with the revised
definition of Steele \cite{CLtL2}.

\subsection{Predicates}
The \lfun{functionp} now follows the new specification in Steele
\cite{CLtL2}.  Only internal functions ({\tt SUBR}'s), byte compiled
functions, and function closures result in a non-\NIL\ value. In
particular, \NIL\ is returned for symbols and lambda expressions.

The function \lfun{bit-vector-p} has been added for compatibility with
some software; it always returns \NIL.

The macros \lmac{and} and \lmac{or} now return multiple values if the
final expression does.

\subsection{Control Structure}
As mentioned in Section \ref{Subsection:Scope}, block names and go
targets are now properly lexically scoped.

A number of functions, macros and special forms have been modified to
return multiple values when appropriate. These are
\begin{center}
\begin{tabular}{llllllll}
  \lfun{apply} &
  \lspec{block} &
  \lmac{case} &
  \lspec{catch} &
  \lmac{cond} &
  \lmac{do} &
  \lmac{do*} &
  \lmac{dolist} \\
  \lmac{dotimes} &
  \lspec{flet} & 
  \lfun{funcall} &
  \lspec{if} &
  \lspec{labels} &
  \lspec{let} &
  \lspec{let*} &
  \lmac{loop} \\
  \lspec{macrolet} &
  \lmac{prog} &
  \lmac{prog*} &
  \lspec{progn} &
  \lspec{progv} &
  \lmac{unless} & 
  \lspec{unwind-protect} &
  \lmac{when}
\end{tabular}
\end{center}

Functions can now be defined to return multiple values using the
\lfun{values} function. If a function is defined as
\begin{verbatim}
(defun f (x y) (values x y))
\end{verbatim}
then it returns two values:
\begin{verbatim}
> (f 1 2)
1
2
\end{verbatim}
Values beyond the first are ignored when the value of a function is
passed as an argument:
\begin{verbatim}
> (list (f 1 2))
(1)
\end{verbatim}
It is also possible to return no values; the implicit first value when
used as a function argument is \NIL:
\begin{verbatim}
> (values)
> (list (values))
(NIL)
\end{verbatim}
Returning no values is one way to suppress printing if no meaningful
value is returned; for example, the \lfun{pprint} function returns no
values.

Several macros and special forms are available for capturing multiple
values.  You can collect them in a list with
\lmac{multiple-value-list},
\begin{verbatim}
> (multiple-value-list (f 1 2))
(1 2)
\end{verbatim}
access one specific value by position with \lmac{nth-value},
\begin{verbatim}
> (nth-value 0 (f 1 2))
1
> (nth-value 1 (f 1 2))
2
> (nth-value 2 (f 1 2))
NIL
\end{verbatim}
bind them to variables with \lmac{multiple-value-bind},
\begin{verbatim}
> (multiple-value-bind (a b) (f 1 2) (list b a))
(2 1)
\end{verbatim}
or pass them as arguments to a function with \lspec{multiple-value-call},
\begin{verbatim}
> (multiple-value-call #'+ (f 1 2))
3
\end{verbatim}
Multiple values can also be produced with \lfun{values-list} and
captured with \lspec{multiple-value-prog1} and
\lmac{multiple-value-setq}.

The assignment macros \lmac{psetf} and \lmac{rotatef} and the macro
\lfun{typecase} are now available.

The assignment macro \lmac{setf} has been re-implemented as a macro,
both in the interpreter and a compiler. The function
\lfun{get-setf-method} has been added and is used both by \lmac{setf}
and by new versions of macros like \lmac{push} and \lmac{incf}. The
lmac{setf} macro should now work with place forms that use
\lfun{apply}.

The standard macro version of \lmac{setf} introduces a number of
temporary variables to avoid multiple evaluation of forms in a setf
expression. This can slow down interpreted code (it does not affect
compiled code since unnecessary bindings are optimized out).  To
reduce the impact of this, the special variable
\lvarstar{simplify-setf} can be set to a non\NIL\ value. When this
variable is not \NIL, \lmac{setf} substitutes the value expressions
for these variables. In principle this can cause multiple evaluation
of some subform, but it will not for any of the standard setf methods.
This behavior is equivalent to the behavior of the previous internal
version of \lmac{setf}. The setault value of \lvarstar{simplify-setf}
in the interpreter it \TRUE. The compiler should set it to \NIL, but
does not do so yet.

The function \lfun{special-form-p} has been added. It returns \TRUE\ 
if its symbol argument has a global function binding that is of type
{\tt FSUBR}; otherwise it returns \NIL.

\subsection{Macros}
Macros can now be defined to use the \llkey{environment},
\llkey{whole} and \llkey{body} lambda list keywords. The functions
\lfun{macroexpand} and \lfun{macroexpand-1} accept an optional
environment argument, which should only be an environment captured
with an \llkey{environment} argument to a macro or an environment
passed to an evalhook function. Expansion is done using this
environment if supplied; otherwise, the null environment is used.

Macros allow destructuring in their required arguments, not in any
other arguments. The macro \lmac{destructuring-bind} is also
available. The \llkey{whole} lambda keyword may not be used in this
macro.  Steele \cite{CLtL2} says it may, but I think this is an error.

The \lmac{define-compiler-macro} macro is available for defining
macros to be expanded only at compile time.

The function \lfun{macro-function} is available. Macros have been
modified to use a macro function of two arguments, the form to be
expanded and the environment. \lfun{macro-function} returns this
function when its symbol argument names a macro.

The functions \lfun{variable-information} and
\lfun{function-information} for accessing environment information and
\lfun{augment-environment} for changing environment information have
been added. The functions \lfun{parse-macro} and \lfun{enclose} are
also available.

A simple implementation of \lspec{symbol-macrolet} has been added.  It
has not been extensively tested. It is currently not part of the
standard initial workspace but set up to be autoloaded when called.
Code using \lspec{symbol-macrolet} will be completely macro expanded,
which means some standard macros implemented as special forms in the
interpreter will be replaced by macros and expanded. The code may
therefore be a bit slow when interpreted, but speed of compiled code
will not suffer.

\subsection{Declarations}
The special form \lspec{declare} is available, but all declarations
are currently ignored by the interpreter and the compiler, including
special declarations.
\begin{note}
  It may be fairly easy to add proper handling of special declarations
  to the byte code compiler, but adding it to the interpreter will cut
  speed unless the code is rewritten in the spirit of macro
  displacement.
\end{note}

The function \lfun{proclaim} is available. Currently only special
proclamations have an effect. There is no portable way to take back a
special proclamation.

Macros for the special forms \lspec{locally} and \lmac{the} are
available.  They currently ignore declaration and type information.

\subsection{Symbols}
The functions \lfun{keywordp}, \lfun{gentemp}, and
\lfun{get-properties} have been added. The \lfun{getf} function has
been fixed to search for property identifiers only in even positions
in a property list, and the \lsetf{getf} form has been added. The
macro \lmac{remf} has also been added.

The function \lfun{gensym} has not yet been changed to follow the new
specification, but probably will be.

\subsection{Packages}
\XL\ now uses the \CL\ package system for name space management. The
functions \lfun{apropos}, \lfun{apropos-list}, \lfun{intern}, and
\lfun{unintern} have been modified accordingly.

A package is a collection of symbols, with some symbols considered
internal and others external, or exported. The system is always ``in''
some package, the current package, which is the value of the variable
\lvarstar{package}.  Packages can ``use'' other packages.  When in a
package, all symbols of that package, internal or external, and all
external symbols of other packages used by that package are considered
accessible. Accessible symbols can be referenced by their name and are
printed using only their name. Inaccessible symbols can still be
referenced and printed using a package name qualifier and a colon,
{\tt :}, or double colon, {\tt ::} separator. An external symbol in a
package is referenced or printed as
\begin{center}\tt
\param{package}:\param{name}
\end{center}
and an internal symbol as
\begin{center}\tt
\param{package}::\param{name}
\end{center}
Thus {\tt foo:bar} is the external symbol with name {\tt "BAR"} in the
package named {\tt "FOO"}, and {\tt foo::baz} is the internal symbol
with name {\tt "BAZ"} in the {\tt "FOO"} package.

The default package is the package named {\tt "USER"}. This package
has several nicknames that can be used to refer to it:
\begin{verbatim}
> (package-nicknames "USER")
("CL-USER" "COMMON-LISP-USER")
\end{verbatim}
It uses the {\tt "XLISP"} package,
\begin{verbatim}
(package-use-list "USER")
(#<Package XLISP>)
> (package-nicknames "XLISP")
("CL" "COMMON-LISP" "LISP")
\end{verbatim}
Another standard package is the {\tt "KEYWORD"} package. Keywords are
placed in this package as internal symbols and are made constants with
values equal to themselves. Symbols in this package are always
referenced and printed as a colon followed by the symbol name. So {\tt
  :test} is the symbol with name {\tt "TEST"} in the keyword package.

Packages are usually constructed using the \lmac{defpackage} macro.
The current package is usually set with the \lmac{in-package} macro.
Both typically appear in a file, followed by some export commands. For
example, a file containing the lines
\begin{verbatim}
(defpackage "MYPACK" (:use "XLISP"))

(in-package "MYPACK")

(export '(a b))

(defun a () ...)
(defun b () ...)
(defun c () ...)
(defun d () ...)
\end{verbatim}
constructs a new package {\tt "MYPACK"} with external symbols {\tt a}
and {\tt b} and internal symbols {\tt c} and {\tt d}. It is not
necessary to save and restore the old package since the \lfun{load}
function restores the current package to the value it had before the
load.

When a package other than the {\tt "USER"} package is the current
package, the standard listener top level loop adds the package name to
the prompt:
\begin{verbatim}
> (in-package "XLISP"")
#<Package XLISP>
XLISP> (in-package "USER")
#<Package USER>
>
\end{verbatim}

Other functions and macros to support the use of packages are
\begin{center}
  \begin{tabular}{llll}
    \lfun{delete-package} &
    \lfun{do-all-symbols} &
    \lmac{do-external-symbols} &
    \lmac{do-symbols} \\
    \lfun{find-all-symbols} &
    \lfun{find-package} &
    \lfun{find-symbol} &
    \lfun{import} \\
    \lfun{list-all-packages} &
    \lfun{make-package} &
    \lfun{package-name} &
    \lfun{package-shadowing-symbols} \\
    \lfun{package-used-by-list} &
    \lfun{package-valid-p} &
    \lfun{packagep} &
    \lfun{rename-package} \\
    \lfun{shadow} &
    \lfun{shadowing-import} &
    \lfun{symbol-package} &
    \lfun{unexport} \\
    \lfun{unuse-package} &
    \lfun{use-package}
  \end{tabular}
\end{center}

\begin{warning}
  Details of the assignment of system and statistical symbols to
  packages and of package naming are likely to change in the near
  future and should not be relied upon.
\end{warning}

\subsection{Numbers}
The functions \lfun{ceiling}, \lfun{floor}, \lfun{round}, and
\lfun{truncate} now return two values in accordance with the \CL\ 
specification. The second value is the remainder of the operation.
\begin{note}
  The vectorized version only returns one value for a compound
  argument.  This is consistent with the idea that the vectorization
  can be defined with a mapping function. It is not clear whether this
  is the right decision, and it may change.
\end{note}

The functions \lfun{make-random-state} and \lfun{random-state-p} have
been changed to use new random number generators; see Section
\ref{Subsection:Random}

The following vectorized arithmetic functions have been added:
\begin{center}
  \begin{tabular}{llllllllll}
    \lfun{ash} &
    \lfun{asinh} &
    \lfun{atanh} &
    \lfun{cosh} &
    \lfun{cis} &
    \lfun{lcm} &
    \lfun{logtest} &
    \lfun{signum} &
    \lfun{sinh} &
    \lfun{tanh}
  \end{tabular}
\end{center}
The macros \lmac{decf} and \lmac{incf} have also been added.

\subsection{Characters}
The function \lfun{alpha-char-p} has been added.

\subsection{Sequences}
Sequence functions have been improved and expanded. The following
functions have been modified to operate on lists and all vector types,
including strings:
\begin{center}
  \begin{tabular}{llllllll}
    \lfun{concatenate} &
    \lfun{copy-seq} &
    \lfun{count} &
    \lfun{elt} &
    \lfun{find} &
    \lfun{every} &
    \lfun{map} &
    \lfun{notany} \\
    \lfun{notevery} &
    \lfun{some} &
    \lfun{position} &
    \lfun{reduce} &
    \lfun{remove-duplicates} &
    \lfun{subseq}
  \end{tabular}
\end{center}
The following functions have been added:
\begin{center}
  \begin{tabular}{llllll}
    \lfun{count-if} &
    \lfun{count-if-not} &
    \lfun{delete-duplicates} &
    \lfun{fill} &
    \lfun{find-if} &
    \lfun{find-if-not} \\
    \lfun{map-into} &
    \lfun{nreverse} &
    \lfun{position-if} &
    \lfun{position-if-not} &
    \lfun{replace} &
    \lfun{search}
  \end{tabular}
\end{center}
Most keyword arguments specified in Steele \cite{CLtL2} are supported,
except that not all functions that should support the
\lkeyword{from-end} keyword yet.

The \lfun{complement} function for negating a predicate has been added.

\subsection{Lists}
The functions \lfun{mapcan} and \lfun{mapcon} are now functions
instead of macros.

The following list functions have been added:
\begin{center}
  \begin{tabular}{lllll}
    \lfun{copy-alist} &
    \lfun{copy-tree} &
    \lfun{list-length} &
    \lfun{list*} &
    \lfun{nintersection} \\
    \lfun{nreconc} &
    \lfun{nset-difference} &
    \lfun{nset-exclusive-or} &
    \lfun{nsublis} &
    \lfun{nsubst} \\
    \lfun{nsubst-if} &
    \lfun{nsubst-if-not} &
    \lfun{nunion} &
    \lfun{pairlis} &
    \lfun{set-exclusive-or} \\
    \lfun{eighth} &
    \lfun{fifth} &
    \lfun{ninth} &
    \lfun{seventh} &
    \lfun{sixth} \\
    \lfun{tenth} &
  \end{tabular}
\end{center}
Setf forms for the positional accessors \lfun{fifth}, \ldots,
\lfun{tenth} have also been added.

The macro \lmac{pop} is now available.

\subsection{Hash Tables}
Hash tables are now provided, with the interface functions
\begin{center}
  \begin{tabular}{llll}
    \lfun{clrhash} &
    \lfun{gethash} &
    \lfun{hash-table-count} &
    \lfun{hash-table-p} \\
    \lfun{hash-table-rehash-size} &
    \lfun{hash-table-rehash-threshold} &
    \lfun{hash-table-size} &
    \lfun{hash-table-test} \\
    \lfun{make-hash-table} &
    \lfun{maphash} &
    \lfun{remhash} &
  \end{tabular}
\end{center}
Any test predicate is allowed, but the standard ones, \lfun{eq},
\lfun{eql}, and \lfun{equal} have internal implementations that should
make them reasonably fast.

\subsection{Arrays}
Arrays can now be restricted to certain element types. This allows for
more compact storage of arrays of specialized types. The standard
element types supported are
\begin{center}
  \begin{tabular}{llllll}
    \ltype{character} &
    \ltype{fixnum} &
    \ltype{float} &
    \ltypelist{complex fixnum} &
    \ltypelist{complex float}
  \end{tabular}
\end{center}
In addition, the following nonstandard types are supported for
communicating with C programs:
\begin{center}
  \begin{tabular}{llllll}
    \ltype{c-char} &
    \ltype{c-short} &
    \ltype{c-int} &
    \ltype{c-long} &
    \ltype{c-float} &
    \ltype{c-double} \\
    \ltype{c-complex} &
    \ltype{c-dcomplex} &
  \end{tabular}
\end{center}
Other types are considered equivalent to {\tt t}.

The \lfun{array-element-type} function returns the element type of an
array, The \lkeyword{element-type} keyword can be used with
\lfun{make-array} to construct an array of the specified type.

\begin{note}
  The support for typed vectors is not yet complete. It is more or
  less complete for the basic \XL\ system, but has not yet been
  completely integrated in the statistical code. Eventually the linear
  algebra routines and the foreign function interface will be changed
  to rely on these routines in order to minimize conversion to and
  from C data. The details of the supported types may need to be
  changed as this evolves.
\end{note}

The functions \lfun{row-major-aref} and \lfun{svref} have been added.

\begin{note}
  At present, vectors with fill pointers and adjustable arrays are not
  supported. One or both may be added.
\end{note}

\subsection{Strings}
The functions \lfun{nstring-capitalize}, \lfun{schar},
\lfun{string-capitalize}, and \lfun{string-search} have been added.

\subsection{Structures}
The \lmac{defstruct} macro allows constructor, predicate and print
functions to be specified. Inheritance of other structures through the
\lfun{include} keyword is supported, and produces proper subtype
relationships. BOA constructors are not supported.

\subsection{The Evaluator}
The \lfun{applyhook} function and the \lvarstar{applyhook} variable
are now available. Both \lfun{eval} and \lfun{evalhook} now use the
null lexical environment for evaluation.

\subsection{Streams}
The \lfun{force-output} function now allows arbitrary stream
arguments.  Simple versions of \lfun{clear-output} and
\lfun{finish-output} are now available.  The functions
\lfun{fresh-line} and the corresponding format directive are now
available.  The functions \lfun{input-stream-p}, \lfun{open-stream-p},
\lfun{output-stream-p}, and the macro \lmac{with-open-stream} have
been added.

\subsection{Input/Output}
Printing of floating point numbers by the \lfun{print} function now
follows the \CL\ standard. This means floating point numbers always
contain a decimal point and are generally printed with around 18
digits on a system with 64-bit double precision floating point
numbers. This insures that printed numbers can be read back in to
produce essentially identical values (slightly more digits would be
needed to insure absolute equality).
\begin{note}
  This change may produce output that some find to unreadable. It
  would be good to be able to control the number of digits used for
  floating point printing. At present there is a back door mechanism:
  the variable \lvarstar{float-format} can be set to a C format
  string, which will then be used. The old printing approach is
  equivalent to setting this variable to {\tt "\%g"}. I do not know
  how to implement such an option portably in \CL\ and I am not sure
  how important it is, since all model summaries and things like
  \lfun{print-matrix} use \lfun{format}. If this turns out to be
  useful and important, I will change the mechanism to use a \CL\ 
  format string instead of a C one.
\end{note}

Several new print and read control variables are now used. These are
\begin{center}
  \begin{tabular}{lll}
    \lvarstar{print-array} & 
    \lvarstar{print-case} &
    \lvarstar{print-circle} \\
    \lvarstar{print-escape} &
    \lvarstar{print-gensym} &
    \lvarstar{print-length} \\
    \lvarstar{print-level} &
    \lvarstar{print-readably} &
    \lvarstar{read-suppress}
  \end{tabular}
\end{center}
Two nonstandard variables are also used. If
\lvarstar{print-symbol-package} is non-\NIL, all symbols are printed
with package qualifiers. The variable \lvarstar{readtable-case} can be
used to set the case of the readtable.
\begin{note}
  The readtable case should be part of the readtable; this will
  probably be changed to comply with \CL.
\end{note}

The functions \lfun{read}, \lfun{read-char}, \lfun{read-byte}, and
\lfun{read-line} now support {\tt eof-error-p} arguments.

The reader now uses the keyword package as the default package while
processing a features expression specified with the {\tt \#+} or {\tt
  \#-} read macros.  This means that {\tt \#+fred} and {\tt \#+:fred}
are equivalent. The standard symbols in the \lvarstar{features} list
have been changed to keyword symbols.

The \lfun{format} function has been changed to handle the \lfmtdir{E},
\lfmtdir{F}, and \lfmtdir{G} directives in accordance with the \CL\
specification. A number of format directives have been added.  The new
format directives are
\begin{center}
  \begin{tabular}{ll}
    \lfmtdir{O}, \lfmtdir{X} & octal and hexadecimal output\\
    \lfmtdir{\&} & fresh line\\
    \lfmtdir{T} & tabulate\\
    \lfmtdir{(}, \lfmtdir{)} & case conversion\\
    \lfmtdir{*} & argument skipping\\
    \lfmtdir{?} & indirection\\
    \lfmtdir{[}, \lfmtdir{;}, \lfmtdir{]} & conditional expression\\
    \lfmtdir{\{}, \lfmtdir{\}} & iteration\\
    \lfmtdir{|} & page separator
  \end{tabular}
\end{center}

Very minimal implementations of the following functions have been added:
\begin{center}
  \begin{tabular}{llll}
    \lfun{write} &
    \lfun{write-line} &
    \lfun{write-string} &
    \lfun{write-to-string} \\
    \lfun{parse-integer} &
    \lfun{prin1-to-string} &
    \lfun{princ-to-string} &
    \lfun{pprint} \\
    \lfun{read-from-string} &
  \end{tabular}
\end{center}

\subsection{File System interface}
The functions \lfun{delete-file}, \lfun{file-length},
\lfun{probe-file}, \lfun{truename}, \lfun{rename-file}, and \lfun{file-write-date} have been added.

There is no separate pathname type; pathnames are currently just
strings.  Minimal versions of the following pathname functions have
been added:
\begin{center}
\begin{tabular}{llll}
\lfun{make-pathname} &
\lfun{merge-pathnames} &
\lfun{namestring} &
\lfun{parse-namestring} \\
\lfun{pathname} &
\lfun{pathname-device} &
\lfun{pathname-directory} &
\lfun{pathname-host} \\
\lfun{pathname-name} &
\lfun{pathname-type} &
\lfun{pathname-version}
\end{tabular}
\end{center}
The variable \lvarstar{default-pathname-defaults} is used for default
values.

\subsection{Errors}
Error handling now uses the condition system; see Section
\ref{Subsection:Conditions} for details.

\subsection{Miscellaneous Features}
The \lfun{step} function has been replaced by a new implementation.
Details are given in  Appendix \ref{Appendix:Stepper}.

The standard function \lfun{function-lambda-expression} replaces
\lfun{get-lambda-expression}.

A very rudimentary \lfun{describe} functions is available; it will be
improved in the future.

A byte code compiler for \XL\ is included in Release 3. For code that
spend much time in tight loops, the compiler can lead to significant
speed improvements.

The interface to the compiler is through two functions, \lfun{compile}
and \lfun{compile-file}. Suppose {\tt f} is defined as
\begin{verbatim}
(defun f (x) (+ x 1))
\end{verbatim}
Then
\begin{verbatim}
> #'f
#<Closure-F: #c6741c>
> (compile 'f)
F
> #'f
#<Byte-Code-Closure: #c73644>
\end{verbatim}

\lfun{compile} can also be used to compile a lambda expression:
\begin{verbatim}
> (compile nil '(lambda (x) (+ x 1)))
#<Byte-Code-Closure: #d77350>
\end{verbatim}

The function \lfun{compile-file} takes a file name string as its
required argument.  If the file has no extension, a {\tt .lsp}
extension is added. It compiles the file into a file with a {\tt .fsl}
extension.  When \lfun{load} is given a string {\tt "fred"} as its
argument, it first looks for {\tt "fred.fsl"} and then for {\tt
"fred.lsp"}. If both are present, the {\tt .fsl} files is used if it
is newer than the {\tt .lsp} file; otherwise the {\tt .lsp} file is
used.

\begin{note}
  Currently the compiler ignores all declarations, including special
  declarations, and all proclamations other than special ones. Future
  versions will use inline and optimize declarations to choose among
  code generation strategies.
\end{note}

The {\tt .fsl} files produced by the compiler contain ordinary lisp
expressions that are read in by the reader. Constants are printed out
with \lvarstar{print-circle} and \lvarstar{print-readably} turned on.
This should be sufficient, but if things get confused by a lot of
messing with packages, it may help to also turn on
\lvarstar{print-symbol-package}. This can be done by supplying the
\lkeyword{print-symbol-package} keyword argument to
\lfun{compile-file} with a non-\NIL\ value.

The function \lfun{compiled-function-p} returns true for internal
compiled functions ({\tt SUBR}'s) or byte compiled functions.

The compiler is based on CPS conversion (see, for example, Friedman,
Wand and Haynes \cite{FriedmanWandHaynes92}). The design is based on
the {\em ORBIT}\/ compiler as described in Krantz et
al.~\cite{KrantzEtAl86} and on Brooks, Gabriel and Steele
\cite{BrooksGabrielSteele82}.
\begin{note}
  At this point the compiler does not do anything special for
  vectorized arithmetic or anything else statistical. In the future I
  will explore adding optimizations designed to deal with problems
  specific to statistical usage. The basic design should make this
  reasonably easy.
\end{note}

\subsection{Loop}
No changes -- not implemented. The subset of loop from Peter Norvig's
\cite{Norvig92} book should work with at most minor modifications.

\subsection{Pretty Print}
No changes -- not implemented. The XP pretty pringing package from the
CMU lisp archives can be made to work with minor modifications.

\subsection{CLOS}
No changes -- not implemented. The closette subset of CLOS from the
AMOP book can be made to work with minor modifications.

\subsection{Conditions}
\label{Subsection:Conditions}
\XLS\ now uses an implementation of the \CL\ condition system for
error handling. The functions \lfun{error}, \lfun{cerror},
\lfun{warn}, and \lfun{signal} signal errors, continuable errors,
warnings, or general conditions, respectively.

The macro \lmac{ignore-errors} takes an expression argument and
returns either the values of that expression in the current environment
if there is no error, or the values \NIL\ and the error condition
signaled:
\begin{verbatim}
> (ignore-errors (values 1 2))
1
2
> (ignore-errors (error ``an error''))
NIL
#<Condition SIMPLE-ERROR: 13023072>
\end{verbatim}

The macros \lfun{assert} and \lfun{check-type} for type and predicate
checking and the macros \lfun{ccase}, \lfun{ctypecase} signal
continuable errors. The macros \lmac{check-type}, \lmac{ccase},
\lmac{ctypecase}, \lfun{ecase}, and \lfun{etypecase} signal errors of
type \lerrtype{type-error}.
\begin{warning}
  At this point the implementations of these macros are bare bones and
  may not actually provide continuable errors or the right error type
  but that should be changed soon.
\end{warning}

Conditions handlers are set up and used with the functions and macros
\begin{center}
  \begin{tabular}{lll}
    \lmac{define-condition} &
    \lfun{make-condition} &
    \lmac{handler-bind} \\
    \lmac{handler-case} &
    \lmac{with-condition-restarts}
  \end{tabular}
\end{center}

Restarts can be manipulated using the following functions and macros:
\begin{center}
  \begin{tabular}{llll}
    \lfun{compute-restarts} &
    \lfun{find-restart} &
    \lfun{invoke-restart} &
    \lfun{invoke-restart-interactively} \\
    \lfun{muffle-warning} &
    \lfun{restart-bind} &
    \lfun{restart-case} &
    \lfun{restart-name} \\
    \lfun{store-value} &
    \lfun{use-value} &
    \lfun{with-simple-restart}
  \end{tabular}
\end{center}

The function \lfun{invoke-debugger} provides a low level interface to
the debugger.

All standard predefined condition types are implemented, including the
accessor functions
\begin{center}
  \begin{tabular}{ll}
    \lfun{cell-error-name} &
    \lfun{simple-condition-format-arguments} \\
    \lfun{simple-condition-format-string} &
    \lfun{type-error-datum} \\
    \lfun{type-error-expected-type} &
  \end{tabular}
\end{center}
Conditions are currently implemented as structures and therefore do
not support multiple inheritance.
\begin{warning}
  For the most part internal errors still signal errors of type
  \lerrtype{simple-error}. This will be changed eventually. One
  exception is unbound variable and unbound function errors -- these
  are already of types \lerrtype{unbound-variable} and
  \lerrtype{unbound-function}, respectively. This may eventually be
  used to define a more sophisticated autoload facility.
\end{warning}

\begin{note}
  Currently stack overflow errors are not signalled at the system
  state where they occur, because trying to handle them without any
  stack space would lead to an infinite error recursion. Instead they
  are signaled from the most recent \lmac{handler-bind}, in such a way
  as to insure that a stack overflow in a handler is caught in the
  next most recent one.

  In the future, I will try to generate low stack errors that allow a
  limited amount of exploring the system state before a real overflow
  occurs. I think this can be done fairly easily without a performance
  penalty, but I'm not sure yet.
\end{note}


\section{Changes in the Statistical System}
\subsection{New Random Number Generators}
\label{Subsection:Random}
Three new generators in addition to the original lagged Fibonacci
generator are now available. The generators are identified by an
integer:
\begin{itemize}
\item[0] The original XLISP-STAT generator, Marsaglia's portable
  generator from CMLIB. This is a lagged Fibonacci generator.
\item[1] L'Ecuyer's \cite{LEcuyer86} version of the Wichmann-Hill
  \cite{WichmannHill82} generator, also used in Bratley, Fox and
  Schrage, \cite[program UNIFL]{BratleyFoxSchrage}.
\item[2] Marsaglia's Super-Duper, as used in {\em S}.
\item[3] Combined Tausworthe generator of Tezuka and L'Ecuyer
  \cite{TezukaLEcuyer91}.
\end{itemize}
The default generator is generator 1. Generator 0 has a period of
$2^{32}$. All three new generators have periods on the order of
$2^{60}$.

Random states are now printed as
\begin{verbatim}
> *random-state*
#$(1 #(2147483562 0 11716 54063))
\end{verbatim}
The function \lfun{make-random-state} produces a new seed from the
current generator when called with the argument {\tt t}. An
alternate generator can be specified by supplying an appropriate
integer as a second argument:
\begin{verbatim}
> (make-random-state t)
#$(1 #(2147483562 0 11716 54088))
> (make-random-state t 2)
#$(2 #(2147483647 0 0 11715 0 54105))
\end{verbatim}

When \lfun{make-random-state} is called with an old state vector, a new
state for generator 0 is returned.

\subsection{Changes in the Object System}
The object system now uses a method cache that should significantly
improve dispatch for methods in deep object hierarchies.

To help with compilation, the way in which the current object is
passed to functions \lfun{slot-value}, \lfun{call-next-method} and
\lfun{call-next-method} has changed. These functions should only be
called in the dynamic extent of a method call. Their use outside of
this scope, for example in a function closure returned by a method, is
undefined.
\begin{note}
  The current implementation uses a dynamic binding to store the
  current object. This works, but makes tail recursion optimization on
  methods impossible. I may need to make a major change in which
  things like \lfun{slot-value} and \lfun{call-next-method} become
  macros. The main implication of this is that {\tt (apply
    \#'call-next-method ...)} constructs won't work and will have to
  be handled by something like an {\tt apply-next-method} macro. Since
  this is likely to break a fair bit of code I will think about it
  before doing it, but at this point a change along these lines look
  fairly likely.
\end{note}
\begin{note}
  A more substantial revision of the object system may occur soon in
  which the current system remains more or less unchanged but becomes
  just one possible system among many supported by a metaobject
  protocol. This should allow experimentation with variations in the
  object system that might be helpful.
\end{note}

\subsubsection{Changes in the Linear Algera System}
Substantial internal changes have been mad in the linear algebra
system.  These should result in improved performance in fitting large
regression and generalized linear models.

The overall plan is to eliminate allocation of data structures at the
internal C level. Instead, data structures for efficient linear
algebra computations are allocated at the Lisp level as typed arrays.
These are operated on by low level functions, which in many cases are
simple front ends to LINPACK or BLAS routines. Standard functions,
such as \lfun{qr-decomp} are built as Lisp-level wrappers around these
lower level routines. Once the lower level is cleaned up it will be
documented so that users have the option of managing their own
allocation and directly using the low level routines.


\subsection{Other Changes}
The generalized linear model system is now part of the standard
distribution.  The {\tt :display} methods for all model objects and
the \lfun{print-matrix} function have been changed to use the new
\lfmtdir{G} format implementation.
\begin{note}
  At the moment the number of digits printed is fixed at 6. I may make
  this a user-settable option.
\end{note}

The function \lfun{eigen} is now based on the EISPACK {\tt rs}
routine.

The function \lfun{reset-system} can be used to reset the state of
various internal system parameters. If you write your own top level
loop, you can call this when your loop is restarted if it looks like
it is needed.
\begin{note}
  The need for this function is not quite clear yet -- it may be dropped.
\end{note}

The function \lfun{system-has-windows} returns non-\NIL\ if a window
system is available at runtime. This should be used on UNIX systems
rather than a readtime method, such as {\tt \#+windows}.

\section{Deleted Functions}
The function \lfun{load-help} and the \XWIN\ support function
\lfun{make-fake-menu-bar} are no longer generally available. Their
symbols are internal to the XLISP package.

\begin{warning}
The assignment of internal symbols to packages is likely to change in
the near future and should not be relied upon.
\end{warning}

The functions \lfun{get-lambda-expression}, \lfun{num-to-string}, and
\lfun{strcat} have been removed since similar \CL\ functions are
available. You should use \lfun{function-lambda-expression},
\lfun{prin1-to-string} and \lfun{concatenate} instead.

\appendix
\section{The Step Function}
\label{Appendix:Stepper}
\begin{note}
  This is a slightly modified version of the file {\tt stepper.doc}
  from the \TAXL\ distribution.
\end{note}

The new step debugger, written by Ray Comas ({\tt comas@math.lsa.umich.edu})
and modified by Tom Almy, was inspired by the {\tt step.lsp} stepper
included with \XL\ 2.1, originally written by Jonathan Engdahl ({\tt
  jengdahl} on {\em BIX}).  This version has the ability to set/reset
breakpoints, and a few bells and whistles.
 
To invoke the stepper:
\begin{verbatim}
(step (form with args))
\end{verbatim}
The stepper will stop and print every form, then wait for user input.
Forms are printed compressed, i.e. to a depth and length of 3.  This
may be changed by assigning the desired depth and length values to
\lvarstar{stepper-depth} and \lvarstar{stepper-length} before invoking the
stepper, or from within the stepper via the {\tt .} and {\tt \#}
commands.
 
For example, suppose you have the following defined:
\begin{verbatim}
(defun fib (n)
  (if (or (eql n 1) (eql n 2))
      1
      (+ (fib (- n 2)) (fib (- n 1)))))
\end{verbatim}
Then {\tt (step (fib 4))} will produce the following:
\begin{verbatim}
0 >==> (fib 4)
 1 >==> (if (or (eql n 1) (eql n 2)) 1 ...) :
\end{verbatim}
The colon is the stepper's prompt.  For a list of commands, type {\tt h}.
this produces:
\begin{verbatim}
Stepper Commands
----------------
 n or space - next form
 s or <cr>  - step over form
 f FUNCTION - go until FUNCTION is called
 b FUNCTION - set breakpoint at FUNCTION
 b <list>   - set breakpoint at each function in list
 c FUNCTION - clear breakpoint at FUNCTION
 c <list>   - clear breakpoint at each function in list
 c *all*    - clear all breakpoints
          g - go until a breakpoint is reached
          u - go up; continue until enclosing form is done
          w - where am I? -- backtrace
          t - toggle trace on/off
          q - quit stepper, continue execution
          p - pretty-print current form (uncompressed)
          e - print environment
   x <expr> - execute expression in current environment
   r <expr> - execute and return expression
       # nn - set print depth to nn
       . nn - set print length to nn
          h - print this summary
\end{verbatim}
Breakpoints may be set with the {\tt b} command.  You may set
breakpoints at one function, e.g. \verb|b FOO<cr>| sets a breakpoint
at the function {\tt FOO}, or at various functions at once, e.g.
\verb|b (FOO FIE FUM)<cr>| sets breakpoints at the functions {\tt
  FOO}, {\tt FIE}, and {\tt FUM}.  Breakpoints are cleared with the
{\tt c} command in an analogous way.  Furthermore, a special form of
the {\tt c} command, \verb|c *all* <cr>|, clears all previously set
breakpoints.  Breakpoints are remembered from one invocation of step
to the next, so it is only necessary to set them once in a debugging
session.
 
The {\tt g} command causes execution to proceed until a breakpoint is
reached, at which time more stepper commands can be entered.
 
The {\tt f} command sets a temporary breakpoint at one function, and
causes execution to proceed until that function is called.
 
The {\tt u} command continues execution until the form enclosing the
current form is done, then re-enters the stepper.
 
The {\tt w} command prints a back trace.
 
The {\tt q} command quits and causes execution to continue
uninterrupted.
 
Entry and exit to functions are traced after a {\tt g}, {\tt f}, {\tt
  u}, or {\tt q} command.  To turn off tracing, use the {\tt t}
command which toggles the trace on/off.  Also, with trace off, the
values of function parameters are not printed.
 
The {\tt s} command causes the current form to be evaluated.
 
The {\tt n} command steps into the current form.
 
The {\tt .} and {\tt \#} commands change the compression of displayed
forms.  E.g. in the previous example:
\begin{verbatim}
 1 >==> (if (or (eql n 1) (eql n 2)) 1 ...) : . 2
 1 >==> (if (or (eql n ...) ...) ...) :
\end{verbatim}
changes the print length to 2, and
\begin{verbatim}
 1 >==> (if (or (eql n ...) ...) ...) : # 2
 1 >==> (if (or #\# ...) ...) :
\end{verbatim}
changes the print depth to 2.
 
To print the entire form use the {\tt p} command, which pretty-prints
the entire form.
 
The {\tt e} command causes the current environment to be printed;
 
The {\tt x} command causes an expression to be executed in the current
environment.  Note that this permits the user to alter values while
the program is running, and may affect execution of the program.
 
The {\tt r} command causes the value of the given expression to be
returned, i.e. makes it the return value of the current form.

\begin{note}
  The stepper will not produce proper printout for \lspec{go} if the
  jump is outside the most enclosing \lspec{tagbody}, and the tag
  arguments of \lspec{catch}/\lspec{throw} must either be symbols or
  quoted symbols.  No attempt is made here to correctly handle tracing
  of \lspec{unwind-protect}, either.
\end{note}

\begin{thebibliography}{99}
\bibitem{BratleyFoxSchrage}
  {\sc Bratley, P., Fox, B.~L., and Schrage, L.~E.} (1987), {\em A
    Guide to Simulation\/} (2nd ed.), New York, NY: Springer-Verlag.
\bibitem{BrooksGabrielSteele82}
  {\sc Brooks, R.~A., Gabriel, R.~P, and Steele, G.~L.} (1982), ``An
    optimizing compiler for lexically scoped LISP,'' {\em Proc. Symp.
      on Compiler Construction, ACM SIGPLAN Notices} 17, 6, 261--275.
\bibitem{FriedmanWandHaynes92}
  {\sc Friedman, D.~P, Wand, M. and Haynes, C.~T.} (1992), {\em
  Essentials of Programming Languages}, Cambridge, MA: MIT Press.
\bibitem{KrantzEtAl86}
  {\sc Krantz, D.~A., Kelsey, R., Rees, J.~A., Hudak, P., Philbin, J.,
    and Adams, N.~I.} (1986), ``Orbit: An optimizing compiler for
    Scheme,'' {\em Proc. SIGPLAN '86 Symp. on Compiler Construction,
      SIGPLAN Notices} 21, 7, 219--223.
\bibitem{LEcuyer86}
  {\sc L'Ecuyer, P.} (1986), ``Efficient and portable combined random
  number generators,'' {\em Communications of the ACM}\/ 31, 742--749.
\bibitem{Norvig92}
  {\sc Norvig, P.} (1992), {\em Paradigms of Artificial Intelligence
  Programming: Case Studies in Common Lisp}, San Mateo, CA: Morgan
  Kaufmann.
\bibitem{CLtL2}
  {\sc Steele, Guy L.} (1990), {\em Common Lisp: The Language}, 
  second edition, Bedford, MA: Digital Press.
\bibitem{TezukaLEcuyer91}
  {\sc Tezuka, S. and L'Ecuyer, P.} (1991), ``Efficient and port\-able
  combined Tauseworthe random number generators,'' {\em ACM
    Transactions on Modeling and Computer Simulation}\/ 1, 99-112.
\bibitem{WichmannHill82}
  {\sc Wichmann, B.~A. and Hill, I.~D.} (1982) ``An efficient and
  portable pseudo-random number generator,'' (Corr: V33 p123), {\em
    Applied Statistics}\/ 31, 188--190.
\end{thebibliography}

\input{changes.ind}
\end{document}

Stuff to Unexport:
==================
%SET-AREF
%SET-GET
%SET-GETHASH
%SET-SYMBOL-FUNCTION
%SET-SYMBOL-PLIST
%SET-SYMBOL-VALUE
BYTE-CODE-CLOSE
COERCE-TO-MACRO
CPS-ANY-REFERENCES-P
CPS-CALL-NODE-ARGS
CPS-CALL-NODE-FUNCTION
CPS-CALL-NODE-P
CPS-FIND-REFERENCES
CPS-LAMBDA-NODE-ARGLIST
CPS-LAMBDA-NODE-BODY
CPS-LAMBDA-NODE-LAMBDA-LIST
CPS-LAMBDA-NODE-NAME
CPS-LAMBDA-NODE-P
CPS-LEAF-NODE-COUNT
CPS-LEAF-NODE-P
CPS-LEAF-NODE-VALUE
CPS-NODE-CHILDREN
CPS-NODE-INTERNAL
CPS-NODE-NOTE
CPS-NODE-PARENT
CPS-NODE-SIMPLIFIED-P
CPS-NODE-TRANSFORM
CPS-SET-LAMBDA-NODE-ARGLIST
CPS-SET-LAMBDA-NODE-LAMBDA-LIST
CPS-SET-LAMBDA-NODE-NAME
CPS-SET-LEAF-NODE-COUNT
CPS-SET-LEAF-NODE-VALUE
CPS-SET-NODE-CHILDREN
CPS-SET-NODE-NOTE
CPS-SET-NODE-PARENT
CPS-SET-NODE-SIMPLIFIED
DYNAMIC-VALUE
MAKE-BYTE-CODE
MAKE-CPS-NODE
MARK-AS-SPECIAL
PACKAGE-OBARRAY
  GET-INTERNAL-GC-TIME & New\\
  GET-LAMBDA-NAME & New?\\
  SPECIALP & New\\
  STACK-VALUE & New \\