@iftex
@finalout
@end iftex
-@comment $Id: user.texinfo,v 1.43 1996/03/21 15:54:09 adams Exp $
+@comment $Id: user.texinfo,v 1.44 1996/04/07 21:01:07 cph Exp $
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename user.info
@settitle MIT Scheme User's Manual
@titlepage
@title{MIT Scheme User's Manual}
-@subtitle Edition 1.40 beta
+@subtitle Edition 1.44
@subtitle for Scheme Release 7.4
-@subtitle March 10, 1996
+@subtitle 7 April 1996
@author by Stephen Adams
@author Chris Hanson
@author and the MIT Scheme Team
@menu
* Installation::
-* Release Notes::
* Running Scheme::
-* REPL::
+* Using Scheme::
+* Compiling Programs::
* Debugging::
-* Loading Files::
-* World Images::
-* Garbage Collection::
-* Compiling Files::
* GNU Emacs Interface::
* Edwin::
-* Concept Index::
+* Release Notes::
+* Known Problems::
+* Comparison of Edwin to Emacs::
+* Index::
--- The Detailed Node Listing ---
Installation
-* Unix::
-* PC Operating Systems::
+* Unix Installation::
+* HP-PA Installation::
+* OS/2 Installation::
+* Windows Installation::
-Unix
+OS/2 Installation
-* HP-PA Installation::
+* Prerequisites for OS/2 Installation::
+* OS/2 Installation Procedure::
+* Image Files for OS/2 Installation::
+* Documentation for OS/2 Installation::
+* Environment Variables for OS/2 Installation::
-PC Operating Systems
+Windows Installation
* System Requirements::
* Manifest::
-* PC Installation:: Installation
-
-Release Notes
-
-* News::
-* C Back-End Release Notes::
-* PC Release Notes::
-
-News
-
-* 7.3 News:: Changes from Release 7.2 to 7.3
-* 7.2 News:: Changes from Release 7.1 to 7.2
-
-C Back-End Release Notes
-
-* Notes on C Back-End::
-* Problems with the C Back-End::
-
-PC Release Notes
-
-* Known Problems::
+* Windows Installation Procedure::
Running Scheme
* Basics of Starting Scheme::
* Customizing Scheme::
+* Memory Usage::
* Command-Line Options::
* Environment Variables::
-* Starting Scheme from Windows 3.1/NT::
+* Starting Scheme from Windows::
* Leaving Scheme::
Environment Variables
* Microcode Environment Variables::
* Bchscheme Environment Variables::
-* PC Environment Variables::
* Runtime Environment Variables::
* Edwin Environment Variables::
+* Windows Environment Variables::
+* OS/2 Environment Variables::
+
+Using Scheme
+
+* REPL::
+* Loading Files::
+* World Images::
+* Garbage Collection::
The Read-Eval-Print Loop
* Restarting::
* The Current REPL Environment::
-Debugging
-
-* Subproblems and Reductions::
-* Debugger::
-* Debugging Aids::
-* Advising Procedures::
-
-Compiling Files
+Compiling Programs
* Compilation Procedures::
* Declarations::
* Global variables::
* Fixnum arithmetic::
* Flonum arithmetic::
-* Miscellaneous::
+
+Debugging
+
+* Subproblems and Reductions::
+* Debugger::
+* Debugging Aids::
+* Advising Procedures::
Edwin
* Starting Edwin::
* Leaving Edwin::
* Last Resorts::
-* Comparison of Edwin 3.82 to Emacs 18.57::
-Comparison of Edwin 3.82 to Emacs 18.57
+Release Notes
+
+* 7.4 News::
+* 7.3 News:: Changes from Release 7.2 to 7.3
+* 7.2 News:: Changes from Release 7.1 to 7.2
+
+Comparison of Edwin to Emacs
* Incompatibilities of Edwin::
* Deficiencies of Edwin::
* Edwin Bugs::
@end menu
-@node Installation, Release Notes, Top, Top
+@node Installation, Running Scheme, Top, Top
@chapter Installation
+This chapter describes how to install MIT Scheme release 7.4. The
+release is supported under several different operating systems: Unix,
+OS/2, Windows 3.1, Windows 95, and Windows NT. Read the section
+detailing the installation for the operating system that you are using.
+
+If you are installing on an HP 9000 series 700 or 800, you should also
+read @ref{HP-PA Installation}.
+
@menu
-* Unix::
-* PC Operating Systems::
+* Unix Installation::
+* HP-PA Installation::
+* OS/2 Installation::
+* Windows Installation::
@end menu
-@node Unix, PC Operating Systems, Installation, Installation
-@section Unix
+@node Unix Installation, HP-PA Installation, Installation, Installation
+@section Unix Installation
-We will use as an example the installation for HP 9000 series 400
-computers. The installation for other Unix systems is similar. If you
-are installing for an HP 9000 series 700 or 800, see also @ref{HP-PA
-Installation}.
+We will use as an example the installation for GNU/Linux. The
+installation for other Unix systems is similar. If you are installing
+on an HP 9000 series 700 or 800, see also @ref{HP-PA Installation}.
MIT Scheme is distributed as a compressed `tar' file. The tar file
-contains a single directory, called @file{dist-7.3}, and that directory
+contains a single directory, called @file{dist-7.4}, and that directory
contains subdirectories @file{bin}, @file{etc}, and @file{lib}. The
@file{bin} subdirectory contains two executable files, @samp{scheme} and
@samp{bchscheme}. The @file{etc} subdirectory contains several files
First unpack the distribution:
@example
-gzip -cd hp400.tar.gz | tar xvf -
+gzip -cd linux.tar.gz | tar xvf -
@end example
If you do not have the `gzip' program: we have built executables of
Next, go to the directory that you just unpacked:
@example
-cd dist-7.3
+cd dist-7.4
@end example
The easiest way to install the files is to use the "install.sh" shell
can change this by editing the definition of the @samp{install} variable
in the @file{install.sh} shell script. Some versions of @samp{cp} do
not support the @samp{p} option; using simply @samp{cp -r} in this case
-is acceptable. Note that most versions of @samp{mv} require the source
-and destination to be on the same physical device.
+is acceptable. You can also use the @samp{mv} command to move the files
+and directories into place, but note that most versions of @samp{mv}
+require the source and destination to be on the same physical device.
@item
The installation script may try to make some symbolic links during
@samp{bindir} to be this other directory.
@item
-Normally, MIT Scheme's auxiliary files are stored in the directory
+Normally, auxiliary files are stored in the directory
@file{/usr/local/lib/mit-scheme/}. If you can, we suggest that you
create such a directory and install these files there. Otherwise,
create a directory somewhere else and edit the installation script
to change the value of the variable @samp{libdir} to be this directory.
@item
-If you have GNU Emacs installed on your system, un-comment the
-definitions of the variables @samp{infodir}, @samp{emacslisp}, and
-@samp{movemail} in the installation script. You will also need to edit
-these definitions so that they correctly indicate where the GNU Emacs
-files are located.
+If you have GNU Emacs installed on your system, the installation script
+will attempt to automatically determine values for the script variables
+@samp{infodir}, @samp{emacslisp}, and @samp{movemail}. If it guesses
+incorrectly, you will have to override the guesses by editing the script
+with appropriate values.
@item
Once you are satisfied that the @file{install.sh} script is correct,
@end example
@item
-After @file{install.sh} finishes, you can delete the @file{dist-7.3}
+After @file{install.sh} finishes, you can delete the @file{dist-7.4}
directory that you unpacked earlier.
You should now be able to run MIT Scheme by typing
@samp{rehash} before @samp{scheme} will be recognized).
@end itemize
-@menu
-* HP-PA Installation::
-@end menu
-
-@node HP-PA Installation, , Unix, Unix
-@subsection HP-PA Installation
-
+@node HP-PA Installation, OS/2 Installation, Unix Installation, Installation
+@section HP-PA Installation
If you are using an HP 9000 series 700/800 computer (often called an HP
Precision Architecture machine, or HP-PA for short), read this section.
+You should also read @ref{Unix Installation}.
Scheme has built-in code that flushes the instruction and data caches
of your machine in certain circumstances. This code is sensitive to
writing, that database contains entries for the following models:
@example
-705, 710, 715, 720, 730, 735, 750, 755, 834, 835, 850, 867
+@group
+705, 710, 712, 715, 720, 725, 730, 735, 750, 755, 770,
+816, 834, 835, 850, 867, 877
+@end group
@end example
@noindent
-If you have a model that is not in the database, Scheme will not run
--- instead it will print an error message informing you of this fact,
+If you have a model that is not in the database, Scheme will not run;
+instead it will print an error message informing you of this fact,
and stop. If this happens, you must add an entry to the database.
This must be done once, at installation, for each new model.
@itemize @bullet
@item
-Run the program @file{hppacache} that is included in the distribution.
+Run the program @file{hppacach} that is included in the distribution.
You must give this program the filename of the database file as an
argument. Normally the database file name is
@file{/usr/local/lib/mit-scheme/hppacach.mod}, but if you install Scheme
commands on your machine:
@example
+@group
cd /usr/local/lib/mit-scheme
-./hppacache -update hppacach.mod
+./hppacach -update hppacach.mod
+@end group
@end example
-The reason that you must be super-user is that @file{hppacache} needs to
+The reason that you must be super-user is that @file{hppacach} needs to
read the device @file{/dev/kmem} to get the information that it needs.
Normally, @file{/dev/kmem} is readable only by the super-user, or by
users in group @code{sys}. Thus, becoming super-user is the easiest way
to read this information. An alternative method for doing this is to
-change the permissions of the @file{hppacache} program so that it is in
+change the permissions of the @file{hppacach} program so that it is in
group @code{sys}, and to turn on its ``set group ID on exec'' permission
bit, but since this also requires you to be super-user, you might as
well just execute the program as the super-user.
If you add a new model to the database, we'd appreciate it if you would
send us the model information, so that we can update the copy of the
database that we distribute to others. This can be done using the
-@file{hppacache} program, as follows:
+@file{hppacach} program, as follows:
@example
+@group
cd /usr/local/lib/mit-scheme
-./hppacache -print hppacach.mod > model-7xx
+./hppacach -print hppacach.mod > model-7xx
+@end group
@end example
(If you have previously updated the database, you do not need to be
@code{bug-cscheme@@zurich.ai.mit.edu}. Thanks!
@end itemize
-@c NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
-@node PC Operating Systems, , Unix, Installation
-@section PC Operating Systems
+@node OS/2 Installation, Windows Installation, HP-PA Installation, Installation
+@section OS/2 Installation
+
+This section describes how to install MIT Scheme on a machine running
+OS/2 2.1 or OS/2 Warp 3.0.
+
+@menu
+* Prerequisites for OS/2 Installation::
+* OS/2 Installation Procedure::
+* Image Files for OS/2 Installation::
+* Documentation for OS/2 Installation::
+* Environment Variables for OS/2 Installation::
+@end menu
+
+@node Prerequisites for OS/2 Installation, OS/2 Installation Procedure, OS/2 Installation, OS/2 Installation
+@subsection Prerequisites
+
+The Scheme files use about 20 megabytes of disk space when installed.
+An additional 5 megabytes of disk space is required during installation.
+After installation, you can reduce the amount of disk space required by
+deleting some files (@pxref{Image Files for OS/2 Installation}).
+
+MIT Scheme requires a fair amount of RAM to run well. We haven't
+tried running this on any machine with less than 36 megabytes, so we
+don't have any hard data on what the smallest practical amount of RAM
+is. However, for running Scheme under OS/2 Warp, 8 megabytes is
+probably the least you should consider, and 12 megabytes is probably
+comfortable. If you want to use the Scheme compiler or the Edwin text
+editor, you should have at least 16 megabytes of RAM.
+
+MIT Scheme has been tested only on OS/2 Warp 3.0, but it should also
+run under OS/2 versions 2.1 and 2.11. It was compiled using IBM
+Visual Age C++ version 3.0 and the OS/2 Toolkit version 3.0.
+
+@node OS/2 Installation Procedure, Image Files for OS/2 Installation, Prerequisites for OS/2 Installation, OS/2 Installation
+@subsection OS/2 Installation Procedure
+
+After unpacking the @sc{zip} file, @file{os2.zip}, you will have these
+directories containing the following files:
+
+@table @file
+@item readme
+This file.
+
+@item bin\
+The executable programs @file{scheme.exe} and @file{bchschem.exe}.
+
+@item doc\
+Documentation files. Two files, the MIT Scheme User's Manual and the MIT
+Scheme Reference Manual, are provided in @file{.inf} format; these files
+can be read with the OS/2 @file{view} command.
+
+@item etc\
+Installation command files. These are scripts that will be used during
+the installation procedure.
+
+@item icons\
+A directory containing some useful icons.
+
+@item lib\
+A directory containing the data files needed by Scheme when it is
+running.
+@end table
+
+Perform the following steps to install Scheme:
+
+@enumerate
+@item
+Run the command file @file{etc\mkbands.cmd}. This creates the image
+files @file{compiler.com}, @file{edwin.com}, and @file{all.com}, and
+deletes the files @file{compdel.com} and @file{eddel.com}.
+
+@item
+Move the executable files @file{scheme.exe} and @file{bchschem.exe} from
+@file{bin\} to any directory that appears in your @samp{PATH}
+environment variable. Depending on your needs, you may want to keep
+only one of these files; each of these files is about 450 kilobytes and
+chances are you'll only be using one of them. If you keep only
+@file{bchschem.exe} we recommend you rename it to @file{scheme.exe}. Of
+course, you can also keep both programs around if you think you might
+use them both.
+
+The only difference between these two programs is in how they handle
+garbage collection. @file{scheme.exe} allocates two memory heaps, and
+copies objects between the heaps to preserve them. This means that most
+of the time the other heap is occupying valuable memory but doesn't
+hold any interesting data. @file{bchschem.exe} allocates only one
+memory heap, creates a disk file during garbage collection, copies
+objects into the file, then copies them back into
+memory.@footnote{@xref{Memory Usage}, for more detail about this topic.}
+
+These programs provide you with some important performance trade-offs.
+If you have plenty of memory and want the best performance, use
+@file{scheme.exe}. If you don't have enough memory, or if you want to
+use less memory and will accept slower performance, use
+@file{bchschem.exe}. One way to tell that you don't have enough memory
+is to run @file{scheme.exe} for a while and see if your machine is
+paging during garbage collection.
+
+You might consider trying to use @file{scheme.exe} and letting the
+operating system's paging handle the lack of RAM. But usually you will
+find that using @file{bchschem.exe} without paging is much faster than
+using @file{scheme.exe} with paging. Of course, if you are using
+@file{bchschem.exe} and you're still paging, there's nothing you can do
+to win.
+
+@item
+Move the @file{lib\} directory anywhere you like. You may rename it to
+anything you like. (Here at MIT, we use @file{\scheme\lib}.) After you
+have chosen where it will be located, set the
+@samp{MITSCHEME_LIBRARY_PATH} environment variable in @file{config.sys}
+to be that location.
+
+For example, if you decide to store the directory as @file{c:\schdata},
+you would add the following to @file{config.sys}:
+
+@example
+SET MITSCHEME_LIBRARY_PATH=C:\SCHDATA
+@end example
+
+@noindent
+(Remember that you must reboot OS/2 after editing @file{config.sys} in
+order for the changes to take effect.)
+
+You can override the setting of this environment variable with the
+@samp{-library} command-line option to Scheme, for example:
+
+@example
+scheme -library d:\scheme\lib
+@end example
+
+@noindent
+If you supply a @samp{-library} option, it is not necessary to have the
+environment variable defined. For example, instead of editing
+@file{config.sys}, you might create a @file{.cmd} file to invoke Scheme
+and pass it the @samp{-library} option automatically.
+
+@item
+@emph{Optional:} Move the @file{doc\} directory anywhere you like, or
+delete it if you do not want to keep the documentation.
+
+@item
+@emph{Optional:} Run the command file @file{etc\mkfolder.cmd} to create
+a folder containing icons to invoke Scheme. You must give this command
+file a single argument, which is the full path name of the executable
+file that you will use. For example, if you stored the file
+@file{scheme.exe} as @file{c:\scheme\bin\scheme.exe}, then you would
+invoke this command file as follows:
+
+@example
+etc\mkfolder c:\scheme\bin\scheme.exe
+@end example
+
+@noindent
+This will create a folder containing four icons, called @samp{Scheme},
+@samp{Edwin}, @samp{Liar}, and @samp{All}, which correspond to the image
+files @file{runtime.com}, @file{edwin.com}, @file{compiler.com}, and
+@file{all.com}. If you decide to delete any of the image files, you can
+delete the corresponding icons as well.
+
+@item
+@emph{Optional:} The @file{icons\} directory contains some Scheme-ish icon
+files. If you don't like the icons created by the @file{etc\mkfolder}
+command, you can use these icon files to change their appearance.
+
+@item
+@emph{Optional:} Consider setting some of other environment variables
+described below.
+@end enumerate
+
+@node Image Files for OS/2 Installation, Documentation for OS/2 Installation, OS/2 Installation Procedure, OS/2 Installation
+@subsection Image Files
+
+@cindex image file
+Scheme stores its runtime environment in a binary @dfn{image} file,
+which is directly loaded into the Scheme process. An image file is a
+snapshot of Scheme's memory taken at a particular time (you can create
+your own image files using the @code{disk-save} procedure; @pxref{World
+Images}). This distribution comes with four different image files, each
+of which contains different mixes of programs. These image files are
+stored in the @file{lib\} directory.
+
+@enumerate
+@item
+@file{runtime.com} is the basic runtime environment with no other
+programs loaded. This is the smallest image file. All other image
+files are supersets of this file. This is the default image file
+that is used when Scheme starts up, unless it is overridden by a
+command-line option.
+
+@item
+@file{compiler.com} contains the basic runtime environment and the Liar
+native-code compiler. This is the image file that is loaded when Scheme
+is started with the @samp{-compiler} command-line option.
+
+@item
+@file{edwin.com} contains the basic runtime environment and the Edwin
+text editor. This is the image file that is loaded when Scheme is
+started with the @samp{-edwin} command-line option.
+
+@item
+@file{all.com} contains the basic runtime environment, the Liar
+compiler, and the Edwin editor. This is the largest of the image files.
+There is no command-line option corresponding to this image file, but
+the following options can be used to load this file:
+
+@example
+-large -constant 1600 -band all.com
+@end example
+@end enumerate
+
+You can delete any of these files that you aren't going to use (these
+image files take up a @emph{lot} of disk space!). However, keep in mind
+that you need at least one image file to run Scheme at all.
+
+@node Documentation for OS/2 Installation, Environment Variables for OS/2 Installation, Image Files for OS/2 Installation, OS/2 Installation
+@subsection Documentation
+
+Documentation for Scheme is included with this release, in the directory
+@file{doc\}. It consists of the following files:
+
+@itemize @bullet
+@item
+@file{user.inf} is the MIT Scheme User's Manual, which describes how to
+run and use Scheme. It describes all of the environment variables and
+command line options, how to run the compiler and editor, etc.
+
+@item
+@file{scheme.inf} is the MIT Scheme Reference Manual, which documents
+the programming language and the runtime library. This is a large and
+detailed document for writing programs.
+
+@item
+@file{console.txt} describes the procedures that can be used to control
+the appearance of the console window (i.e. Scheme's main window).
+@end itemize
+
+@noindent
+Note: the User's Manual and Reference Manual are available in other
+forms, specifically: as PostScript files and as GNU Info files. These
+alternate forms of documentation may be obtained from our @sc{ftp} site,
+@file{swiss-ftp.ai.mit.edu}.
+
+@node Environment Variables for OS/2 Installation, , Documentation for OS/2 Installation, OS/2 Installation
+@subsection Environment Variables
+
+This section documents several of the environment variables that Scheme
+uses, and gives an example for each one. These are the environment
+variables that must usually be defined when installing Scheme under
+OS/2. For complete documentation of all of the environment variables
+used by Scheme, see @ref{Environment Variables}.
+
+Note that environment variables are usually defined in the OS/2
+@file{config.sys} file. After editing the @file{config.sys} file, it is
+necessary to reboot OS/2 before the changes will take effect.
+
+@table @code
+@item MITSCHEME_LIBRARY_PATH
+@findex MITSCHEME_LIBRARY_PATH
+says where to find Scheme's data files. This is the only required
+environment variable (but is not required when Scheme is invoked with
+the @samp{-library} command line switch).
+
+@example
+SET MITSCHEME_LIBRARY_PATH=C:\SCHEME\LIB
+@end example
+
+@item MITSCHEME_INF_DIRECTORY
+@findex MITSCHEME_INF_DIRECTORY
+tells Scheme where to find debugging information for the runtime system.
+The default value for this environment variable is a subdirectory
+@file{src\} located in the directory specified by
+@samp{MITSCHEME_LIBRARY_PATH}.
+
+@example
+SET MITSCHEME_INF_DIRECTORY=C:\SCHEME\LIB\SRC
+@end example
+
+@item TEMP
+@findex TEMP
+tells Scheme the name of a directory where it can store temporary files.
+
+
+@example
+SET TEMP=C:\TMP
+@end example
+
+@item HOME
+@findex HOME
+tells Scheme where your ``home'' directory is located. This is where
+Scheme looks for init files, and it is also what the @file{~/} (or
+@file{~\\}) filename prefix expands to. If not specified, Scheme uses
+the root directory of the current drive.
+
+@example
+SET HOME=C:\CPH
+@end example
+
+@item USER
+@findex USER
+tells Scheme your user name. This is used for several purposes,
+including the name that will be used as your email address.
+
+@example
+SET USER=cph
+@end example
+
+@item SHELL
+@findex SHELL
+tells Edwin what shell program to use in shell buffers and for running
+shell commands. If not specified, this defaults to the standard OS/2
+shell, @file{cmd.exe}.
+
+@example
+SET SHELL=C:\LOCAL\PROG\4OS2251\4OS2.EXE
+@end example
+@end table
+
+@node Windows Installation, , OS/2 Installation, Installation
+@section Windows Installation
This section describes how to install MIT Scheme on DOS, Windows 3.1, and
Windows NT. We would prefer that the Windows version be used,
@menu
* System Requirements::
* Manifest::
-* PC Installation:: Installation
+* Windows Installation Procedure::
@end menu
-@node System Requirements, Manifest, PC Operating Systems, PC Operating Systems
+@node System Requirements, Manifest, Windows Installation, Windows Installation
@subsection System Requirements
MIT Scheme requires at least a 386SX with 8Mb RAM.
build the Edwin editor band requires an additional 4.3Mb. The whole
installation without source code occupies 36Mb of disk.
-@node Manifest, PC Installation, System Requirements, PC Operating Systems
+@node Manifest, Windows Installation Procedure, System Requirements, Windows Installation
@subsection Manifest
The installation is split into several files according to functional
For DOS the minimal installation comprises @file{DOSBIN.ZIP},
@file{LIB.ZIP} and one of @file{RUNTIME.ZIP} or @file{RUNNOFLO.ZIP}.
-@node PC Installation, , Manifest, PC Operating Systems
-@subsection PC Installation
+@node Windows Installation Procedure, , Manifest, Windows Installation
+@subsection Windows Installation Procedure
These installation instructions describe how to install MIT Scheme on
one or more of DOS, Windows 3.1, and Windows NT. If you are
@file{win32s.zip} file, e.g:
@example
+@group
a:
unzip @var{wherever}\win32s.zip
+@end group
@end example
Run the @file{setup} command on the floppy disk.
If for example, you choose the default:
@example
+@group
mkdir c:\scheme
cd \scheme
+@end group
@end example
@noindent
@item
In the @var{scheme} directory unzip the following essential files:
-@file{bin.zip}, @file{lib.zip} and @file{runtime.zip} [5.5Mb].
+@file{bin.zip}, @file{lib.zip} and@* @file{runtime.zip} [5.5Mb].
@example
+@group
unzip @var{wherever}\bin.zip
unzip @var{wherever}\lib.zip
unzip @var{wherever}\runtime.zip
+@end group
@end example
This will create the directory structures @file{@var{scheme}\bin},
@noindent
If you have a computer without floating-point hardware (e.g.@: a 386
machine or a 486SX) and you wish to run the DOS version then you must
-install the runtime with special floating point support instead of
+install the runtime with special floating-point support instead of
@file{runtime.zip}:
@example
First unpack the delta file @file{eddel.com} [1.6Mb]:
@example
+@group
cd @var{scheme}
unzip @var{wherever}\eddel.zip
+@end group
@end example
To build @file{edwin.com} start the `build EDWIN.COM band' icon, or run
First unpack the @file{compdel.com} delta file [2.5Mb]:
@example
+@group
cd @var{scheme}
unzip @var{wherever}\compdel.zip
+@end group
@end example
To build @file{compiler.com} start the `build COMPILER.COM band' icon,
unpacked in previous steps]:
@example
+@group
cd @var{scheme}
unzip @var{wherever}\eddel.zip
unzip @var{wherever}\compdel.zip
+@end group
@end example
To build @file{all.com} start the `build ALL.COM band' icon, or run the
@file{bcirun1.zip} through @file{bcirun3.zip} [3.6Mb installed].
If you have installed the DOS version for machines without hardware
-floating point support then @file{bcinoflo.zip} should be uncompressed
+floating-point support then @file{bcinoflo.zip} should be uncompressed
also. This must be done @emph{after} the @file{bcirun*.zip} files.
Debugging information files can be installed in the Scheme root
installed] hold the debugging information files for Edwin.
@end enumerate
-@node Release Notes, Running Scheme, Installation, Top
-@chapter Release Notes
+@node Running Scheme, Using Scheme, Installation, Top
+@chapter Running Scheme
+
+This chapter describes how to run MIT Scheme. It also describes how you
+can customize the behavior of MIT Scheme using command-line options and
+environment variables.
-This chapter describes interesting features and problems for the 7.3
-release.
+@cindex Windows
+@cindex PC
+Within this manual, we will use the term @dfn{Windows} to collectively
+refer to the Microsoft Windows operating systems: Windows 3.1, Windows
+95, and Windows NT. We will use the term @dfn{PC} to refer to any
+computer running OS/2 or Windows.
@menu
-* News::
-* C Back-End Release Notes::
-* PC Release Notes::
+* Basics of Starting Scheme::
+* Customizing Scheme::
+* Memory Usage::
+* Command-Line Options::
+* Environment Variables::
+* Starting Scheme from Windows::
+* Leaving Scheme::
@end menu
-@node News, C Back-End Release Notes, Release Notes, Release Notes
-@section News
+@node Basics of Starting Scheme, Customizing Scheme, Running Scheme, Running Scheme
+@section Basics of Starting Scheme
-The last full release of the MIT Scheme system was version 7.1.3 in
-1991. Since that time, there was a partial release of version 7.2 for
-i386/i486 machines and some MIPS R3000 machines. This section
-summarizes the changes that have occurred since version 7.1.3. The
-changes are divided into two parts: those that were incorporated in the
-7.2 partial release, and those that were subsequently incorporated.
+Usually, MIT Scheme is invoked by typing
-@menu
-* 7.3 News:: Changes from Release 7.2 to 7.3
-* 7.2 News:: Changes from Release 7.1 to 7.2
-@end menu
+@example
+scheme
+@end example
-@node 7.3 News, 7.2 News, News, News
-@subsection Changes from Release 7.2 to 7.3
+@noindent
+at your operating system's command interpreter. (Under Windows 3.1 you
+must use the Program Manager's @code{Run} command, or an icon.) Scheme
+will load itself, clear the screen, and print something like this:
-This is an abbreviated list of the changes that have been incorporated
-in the 7.3 release since the (partial) 7.2 release.
+@example
+@group
+Scheme saved on Monday March 25, 1996 at 2:15:03 PM
+ Release 7.4.2
+ Microcode 11.151
+ Runtime 14.168
+@end group
+@end example
-@itemize @bullet
-@item
-Support for MS Windows (3.1 and NT).
+@noindent
+This information, which can be printed again by evaluating
-@item
-Native compiled-code support for DEC Alpha.
+@findex identify-world
+@example
+(identify-world)
+@end example
-@item
-Compiler can now generate C code. This is used to support the Sun SPARC
-and IBM RS6000 architectures.
+@cindex release number
+@cindex microcode, version
+@cindex runtime system, version
+@cindex version numbers
+@noindent
+tells you the following version information. @samp{Release} is the
+release number for the entire Scheme system. This number is changed
+each time a new version of Scheme is released. An @samp{(alpha)} or
+@samp{(beta)} following the release number indicates that this is a
+alpha- or beta-test release. @samp{Microcode} is the version number for
+the part of the system that is written in C. @samp{Runtime} is the
+version number for the part of the system that is written in Scheme.
-@item
-Support for dynamic loading of compiled C code on several operating
-systems, including HP-UX, OSF/1, SunOS 4, and AIX.
+@cindex subsystem versions
+@cindex SF, version
+@cindex compiler, version
+@cindex Edwin, version
+@cindex student package, version
+@cindex compatibility package, version
+Following this there may be additional version numbers for specific
+subsystems. @samp{SF} refers to the scode optimization program
+@code{sf}, @samp{Liar} is the native-code compiler,
+@samp{Edwin} is the Emacs-like text editor,
+and @samp{Student} is the @sc{sicp} compatibility package.
-@item
-New data structures: red/black trees and weight-balanced trees.
+@cindex compiler, starting
+If the compiler is supported for your machine, you can invoke it by
+giving Scheme the @samp{-compiler} option:
-@item
-Redesign of hash tables makes them much faster and somewhat more
-flexible.
+@example
+scheme -compiler
+@end example
-@item
-Completely new random-number generator. The interface to the
-random-number generator has been changed to be like that of Common Lisp.
+@noindent
+This option causes Scheme to use a larger constant space and heap, and
+to load the world image containing the compiler.
-@item
-Record abstraction now uses a special @dfn{record} type to represent
-records (previously it used vectors). @code{define-structure} now
-creates records by default; these records are identical to those created
-with the record abstraction.
-
-@item
-@code{call-with-current-continuation} is now properly tail-recursive.
-
-@item
-New command-line switch @code{-no-suspend-file} prevents the generation
-of @file{scheme_suspend} files.
-
-@item
-Uncompression of compiled-code debugging information is now memoized
-to save time when doing many accesses to the same information (a
-common occurrence).
-
-@item
-Constant space now grows automatically when needed.
-
-@item
-New procedures:
-
-@example
-call-with-values @r{;replaces} with-values
-current-load-pathname
-error-output-port
-fold-left
-fold-right
-interaction-i/o-port
-notification-output-port
-prompt-for-command-char
-prompt-for-command-expression
-prompt-for-confirmation
-prompt-for-evaluated-expression
-prompt-for-expression
-standard-unparser-method @r{;replaces} unparser/standard-method
-stream-first
-stream-rest
-symbol<?
-trace-output-port
-@end example
+@node Customizing Scheme, Memory Usage, Basics of Starting Scheme, Running Scheme
+@section Customizing Scheme
-@item
-@code{string-pad-left} now truncates from the left instead of the right.
+You can customize your setup by using a variety of tools:
+@itemize @bullet
@item
-Argument to @code{make-graphics-device} is now a symbol.
+@cindex command-line options
+@dfn{Command-line options}.
+Many parameters, like memory usage and the location of libraries, may be
+varied by command line options. @xref{Command-Line Options}.
@item
-Each @sc{repl} now has its own working directory pathname and pathname
-defaults. @code{set-working-directory-pathname!} changes only the value
-for the current @sc{repl}.
+@cindex command scripts
+@dfn{Command scripts or batch files}.
+You might like to write scripts that invoke Scheme with your favorite
+command line options. For example, you might not have enough memory to
+run Edwin or the compiler with its default memory parameters (it will
+print something like ``Not enough memory for this configuration'' and
+halt when started), so you can write a shell script (Unix), @file{.bat}
+file (Windows), or @file{.cmd} file (OS/2) that will invoke Scheme with
+the appropriate @samp{-heap} and other parameters.
@item
-The definitions of the following procedures have been changed to
-implement more useful behavior:
+@cindex init file
+Scheme supports @dfn{init files}: an init file is a file containing
+Scheme code that is loaded when Scheme is started, immediately after the
+identification banner, and before the input prompt is printed. This
+file is stored in your home directory, which is normally specified by
+the @samp{HOME} environment variable. Under Unix, the file is called
+@file{.scheme.init}; on the PC it is called @file{scheme.ini}.
-@example
-string-capitalized?
-string-lower-case?
-string-upper-case?
-substring-capitalized?
-substring-lower-case?
-substring-upper-case?
-@end example
+In addition, when Edwin starts up, it loads a separate init file from
+your home directory into the Edwin environment. This file is called
+@file{.edwin} under Unix, and @file{edwin.ini} on the PC.
-@item
-New Edwin features:
+You can use both of these files to define new procedures or commands, or
+to change defaults in the system.
-@display
-@code{M-x dabbrev-expand}
-@code{M-x describe-syntax}
-@code{M-x rcs-ci-locked-files}
-@code{M-x rcs-diff}
-@code{M-x rcs-list-locked-files}
-@code{M-x rcs-log}
-@code{M-x recover-file}
-@code{M-x show-parameter-list}
-@code{M-x sort-lines and other sorting commands}
-@code{auto-mode-alist} variable (as in Emacs)
-Encryption/decryption of files in @code{Dired}
-Undo upgraded to match GNU Emacs 18.57
-Buffers grow/shrink with constant amortized time
-Emacs 19 tags support (multiple tags files, inclusion)
-@end display
+The @samp{-no-init-file} command line option causes Scheme to ignore the
+@file{.scheme.init} file (@pxref{Command-Line Options}).
@item
-Edwin compression/uncompression commands changed to use @code{gzip}
-instead of @code{compress}.
+@dfn{Environment variables}. Most microcode parameters, and some
+runtime system and Edwin parameters, can be specified by means of
+environment variables. @xref{Environment Variables}.
@item
-Edwin now has text-properties mechanism that permits implementation
-of highlighted and mouse-sensitive regions.
+@dfn{Icons}.
+@cindex icons
+Under OS/2 and Windows it is possible to create icons that invoke Scheme
+with different parameters.
@end itemize
-@node 7.2 News, , 7.3 News, News
-@subsection Changes from Release 7.1 to 7.2
+@node Memory Usage, Command-Line Options, Customizing Scheme, Running Scheme
+@section Memory Usage
-This is an abbreviated list of the changes that were incorporated
-in the (partial) 7.2 release since the 7.1 release.
+Some of the parameters that can be customized determine how much memory
+Scheme uses and how that memory is used. This section describes how
+Scheme's memory is organized and used; subsequent sections describe
+command-line options and environment variables that you can use to
+customize this usage for your needs.
-@itemize @bullet
-@item
-Support for MS DOS.
+Scheme uses four kinds of memory:
+@cindex memory
+@itemize @bullet
@item
-Native compiled-code support for the Intel i386 and i486 architectures.
+@cindex stack space
+A @dfn{stack} that is used for recursive procedure calls,
@item
-Fixes to MIPS compiled-code support MIPS R3000 with large cache-line
-sizes.
+@cindex heap space
+A @dfn{heap} that is used for dynamically allocated objects, like @samp{cons}
+cells and strings.
+Storage used for objects in the heap that become unreferenced is
+eventually reclaimed by @dfn{garbage collection}.
@item
-Complete redesign of the error system.
+@cindex constant space
+A @dfn{constant space} that is used for allocated objects, like the
+heap.
+Unlike the heap, storage used for objects in constant space is not
+reclaimed by garbage collection.
+Constant space is used for objects that are essentially permanent, like
+procedures in the runtime system.
@item
-X11 graphics interface redesigned. The new design is smarter about
-interaction with the window manager (for example, it implements the
-@code{WM_DELETE_WINDOW} protocol) and has some limited support for event
-handling. Windows are now closed when they are reclaimed by the garbage
-collector.
+Some extra storage that is used by the microcode (the part of the system
+that is implemented in C).
+@end itemize
-@item
-Redesign of @sc{i/o} ports. New design supports ports that perform both
-input and output.
+@noindent
+@findex scheme
+@findex bchscheme
+All kinds of memory except the last may be controlled either by
+command-line options or by environment variables.
-@item
-Ports now have better-defined control over blocking mode and terminal
-mode. Flushing of output buffers is not done automatically, except for
-the console port.
+MIT Scheme uses a two-space copying garbage collector for reclaiming
+storage in the heap. There are two versions of Scheme which handle
+garbage collection differently. The standard Scheme, called
+@file{scheme} under Unix and @file{scheme.exe} on the PC, has two heaps,
+one for each ``space''. An alternative, called @file{bchscheme} under
+Unix and @file{bchschem.exe} on the PC, has one heap and uses a disk
+file for the other ``space'', thus trading memory usage against garbage
+collection speed.
-@item
-New procedures:
+The total storage required by @file{scheme} is:
@example
-*default-pathname-defaults*
-->namestring
-->truename
-close-port
-directory-namestring
-directory-pathname
-directory-pathname-as-file
-enough-namestring
-enough-pathname
-file-access
-file-attributes-direct @r{;same as} file-attributes
-file-modification-time-direct
-file-modification-time-indirect @r{;same as} file-modification-time
-file-namestring
-file-pathname
-file-readable?
-host-namestring
-i/o-port?
-make-generic-i/o-port
-make-i/o-port
-open-i/o-file
-pathname-simplify
-pathname-wild?
-pathname=?
-port/copy
-port/input-channel
-port/operation
-port/operation-names
-port/output-channel
-port/state
-port?
-record-copy
-record-modifier @r{;replaces} record-updater
-set-port/state!
+@var{stack} + (@var{constant} + 2*@var{heap}) + @var{extra}
@end example
-@item
-@code{with-input-from-file} and @code{with-output-to-file} no longer
-close the port when they are exited abnormally.
+@noindent
+where @var{stack}, @var{constant} and @var{heap} are parameters that are
+selected when @samp{scheme} starts. For @file{bchscheme}, which has
+only one heap in memory, the equation is
-@item
-Redefined @code{#!optional} and @code{#!rest} to be something distinct
-from symbols.
+@example
+@var{stack} + (@var{constant} + @var{heap}) + @var{extra}
+@end example
-@item
-Strings now accept @code{"\@var{nnn}}" octal character escapes, much
-like those in C.
+Once the storage is allocated for the constant space and the heap,
+Scheme will dynamically adjust the proportion of the total that is used
+for constant space; the stack and extra microcode storage is not
+included in this adjustment. Previous versions of MIT Scheme needed to
+be told the amount of constant space that was required when loading
+bands with the @samp{-band} option. Dynamic adjustment of the heap and
+constant space avoids this problem; now all that is required is that the
+total space be sufficient.
-@item
-Redesign of pathname abstraction. New design is very similar to the
-Common Lisp pathname abstraction.
+The Scheme expression @samp{(print-gc-statistics)} shows how much heap
+and constant space is available (@pxref{Garbage Collection}).
-@itemize @bullet
-@item
-->PATHNAME no longer accepts a symbol as an argument. Only strings
-and pathnames are valid.
+@node Command-Line Options, Environment Variables, Memory Usage, Running Scheme
+@section Command-Line Options
-@item
-Procedures eliminated:
+Scheme accepts the command-line options detailed in the following
+sections. The options may appear in any order, with the restriction
+that the microcode options must appear before the runtime options, and
+the runtime options must appear before any other arguments on the
+command line. (At present, any arguments other than these options will
+generate a warning message when Scheme starts. In the future, there
+will be an advertised mechanism by which the extra arguments can be
+handled by user code.)
-@example
-canonicalize-input-filename
-canonicalize-input-pathname
-canonicalize-output-filename
-canonicalize-output-pathname
-canonicalize-overwrite-filename
-canonicalize-overwrite-pathname
-home-directory-pathname
-init-file-truename
-pathname->absolute-pathname
-pathname->input-truename
-pathname->output-truename
-pathname->overwrite-truename
-pathname->string
-pathname-components
-pathname-default-host
-pathname-directory-path
-pathname-directory-string
-pathname-name-path
-pathname-name-string
-pathname-new-host
-pathname-relative?
-string->pathname
-symbol->pathname
-@end example
+These are the microcode options:
-@item
-@code{pathname-default} no longer accepts a @var{host} argument.
+@table @code
+@item -band @var{filename}
+@findex -band
+@findex MITSCHEME_BAND
+@cindex world image
+@cindex band
+Specifies the initial world image file (@dfn{band}) to be loaded.
+Searches for @var{filename} in the working directory and the library
+directories, using the full pathname of the first readable file of that
+name. If @var{filename} is an absolute pathname (on Unix, this means it
+starts with @samp{/}), then no search occurs --- @var{filename} is
+tested for readability and then used directly. If this option isn't
+given, the filename is the value of the environment variable
+@samp{MITSCHEME_BAND}, or if that isn't defined, @file{runtime.com}; in
+these cases the library directories are searched, but not the working
+directory.
-@item
-Representation of pathname directories changed to match Common Lisp.
-Directory is now either @code{#f} or a list of symbols and strings with
-first element either @code{absolute} or @code{relative}.
+@item -compiler
+@findex -compiler
+@findex MITSCHEME_COMPILER_BAND
+This option specifies defaults appropriate for loading the compiler. It
+specifies the use of large sizes, exactly like @samp{-large}; if the
+@samp{-band} option is also specified, that is the only effect of this
+option. Otherwise, the default band's filename is the value of the
+environment variable @samp{MITSCHEME_COMPILER_BAND}, if defined, or
+@file{compiler.com}; the library directories are searched to locate this
+file. Note that the @samp{-compiler} option is available only on
+machines with compiled-code support.
-@item
-Unix pathnames now set @var{device} and @var{version} to
-@code{unspecific}. @code{unspecific} now means that the field is not
-used by the operating system.
+@item -edwin
+@findex -edwin
+@findex MITSCHEME_EDWIN_BAND
+This option specifies defaults appropriate for loading the editor. It
+specifies the use of large sizes, exactly like @samp{-large}; if the
+@samp{-band} option is also specified, that is the only effect of this
+option. Otherwise, the default band's filename is the value of the
+environment variable @samp{MITSCHEME_EDWIN_BAND}, if defined, or
+@file{edwin.com}; the library directories are searched to locate this
+file. Note that the @samp{-edwin} option is available only on machines
+with compiled-code support.
-@item
-Parsing rules for unix filenames changed: the file type is the part of
-the name after the last dot, if any. If the dot occurs at the beginning
-or end of the filename, then it doesn't count -- in that case there is
-no type. Thus, names like @file{.} and @file{..} have no type.
-@end itemize
+@item -large
+@findex -large
+Specifies that large heap, constant, and stack sizes should be used.
+These are specified by the environment variables
-@item
-New Edwin features:
+@findex MITSCHEME_LARGE_HEAP
+@findex MITSCHEME_LARGE_CONSTANT
+@findex MITSCHEME_LARGE_STACK
+@example
+@group
+MITSCHEME_LARGE_HEAP
+MITSCHEME_LARGE_CONSTANT
+MITSCHEME_LARGE_STACK
+@end group
+@end example
-@display
-@code{M-x manual-entry}
-@code{M-x outline-mode}
-@code{M-x shell-resync-dirs}
-@code{M-x shell-command}
-@code{M-x shell-command-on-region}
-@code{M-x telnet}
-@sc{rmail} summary
-@sc{rmail} sort
-@sc{repl} mode and asynchronous evaluation
-Printing commands
-``run light'' for evaluation commands
-Reading and writing of compressed files (@code{".Z"} suffix)
-Reading and writing of encrypted files (@code{".KY"} suffix)
-Compress/uncompress commands for @code{Dired}
-Support for X protocols: @code{WM_DELETE_WINDOW} and @code{WM_TAKE_FOCUS}
-Time, load, and mail notification in mode line
-@end display
-@end itemize
+@noindent
+If this option isn't given, the small sizes are used, specified by the
+environment variables
-@c @node Unix Release Notes, C Back-End Release Notes, News, Release Notes
-@c @section Unix Release Notes
+@findex MITSCHEME_SMALL_HEAP
+@findex MITSCHEME_SMALL_CONSTANT
+@findex MITSCHEME_SMALL_STACK
+@example
+@group
+MITSCHEME_SMALL_HEAP
+MITSCHEME_SMALL_CONSTANT
+MITSCHEME_SMALL_STACK
+@end group
+@end example
-@node C Back-End Release Notes, PC Release Notes, News, Release Notes
-@section C Back-End Release Notes
+@noindent
+There are reasonable built-in defaults for all of these environment
+variables, should any of them be undefined. Note that any or all of the
+defaults can be individually overridden by the @samp{-heap},
+@samp{-constant}, and @samp{-stack} options.
-This release introduces an important new feature: the compiler can
-generate output in C, which can then be compiled and linked using the
-usual C development tools. This feature is being used to support
-architectures, such as the SPARC and IBM RS6000, for which the compiler
-does not have native-code support.
+@findex print-gc-statistics
+Note: the Scheme expression @samp{(print-gc-statistics)} shows how much
+heap and constant space is available and in use (@pxref{Garbage
+Collection}).
-@cindex C back-end
-MIT Scheme systems that have been built using this compiler feature are
-referred to as @dfn{C back-end} systems. This section provides a brief
-description of the features and known problems for such systems.
+@item -heap @var{blocks}
+@findex -heap
+Specifies the size of the heap in 1024-word blocks. Overrides any
+default. Normally two such heaps are allocated; @file{bchscheme}
+allocates only one, and uses a disk file for the other.
-@menu
-* Notes on C Back-End::
-* Problems with the C Back-End::
-@end menu
+@item -constant @var{blocks}
+@findex -constant
+Specifies the size of constant space in 1024-word blocks. Overrides any
+default. Constant space holds the compiled code for the runtime system
+and other subsystems.
-@node Notes on C Back-End, Problems with the C Back-End, C Back-End Release Notes, C Back-End Release Notes
-@subsection General Notes
+@item -stack @var{blocks}
+@findex -stack
+Specifies the size of the stack in 1024-word blocks. Overrides any
+default. This is Scheme's stack, @emph{not} the Unix stack used by C
+programs.
-This section describes the general design of C back-end systems.
+@item -option-summary
+@findex -option-summary
+Causes Scheme to write an option summary to standard error. This shows
+the values of all of the settable microcode option variables.
-@itemize @bullet
-@item
-The C back end was written very recently, and we do not use it
-ourselves for development--we have native back ends for the
-hardware that we use regularly. Furthermore, most of the
-system-building tools and changes were put together and tested
-immediately preceding the release. It is not unlikely that there
-are serious problems and shortcomings. We'd like to hear about
-them so we can fix them or bypass them for a future release. If
-something does not work, do not assume that we know about it.
-Please report it. The worse that can happen is that we hear about
-it several times.
+@item -emacs
+@findex -emacs
+Specifies that Scheme is running as a subprocess of GNU Emacs. This
+option is automatically supplied by GNU Emacs, and should not be given
+under other circumstances.
-@item
-The compiler produces C code that works in the context of the MIT
-Scheme runtime library. It is not stand-alone code, and there is
-currently no way to generate stand-alone executables.
+@item -interactive
+@findex -interactive
+If this option isn't specified, and Scheme's standard @sc{i/o} is not a
+terminal, Scheme will detach itself from its controlling terminal, which
+prevents it from getting signals sent to the process group of that
+terminal. If this option is specified, Scheme will not detach itself
+from the controlling terminal.
-@item
-We have done some performance testing on machines where we have
-both a native back end and the C back end. The C back end code is
-somewhat larger and slower than the native code. The speed varies
-depending primarily on the number of inter-C-procedure calls (even
-within a single source file). In some cases the C code is
-somewhat faster than the native code, but it is usually noticeably
-slower. The average is about 2.5 times slower.
+This detaching behavior is useful for running Scheme as a background
+job. For example, using the C shell in Unix, the following will run
+Scheme as a background job, redirecting its input and output to files,
+and preventing it from being killed by keyboard interrupts or by logging
+out:
-@item
-The output code should work on virtually any modern
-general-purpose architecture with an ANSI-compliant (perhaps even
-a traditional K&R) C compiler. We've tried it on several 32-bit
-architectures (HP PA, SPARC, Motorola 68040, RS6000/Power) and a
-64-bit architecture (Alpha).
+@example
+scheme < /usr/cph/foo.in >& /usr/cph/foo.out &
+@end example
-However, there may very well be assumptions of the following form:
+This option is ignored under non-Unix operating systems.
-@itemize @bullet
-@item
-Memory is byte-addressable.
+@item -nocore
+@findex -nocore
+Specifies that Scheme should not generate a core dump under any
+circumstances. If this option is not given, and Scheme terminates
+abnormally, you will be prompted to decide whether a core dump should be
+generated.
-@item
-Addresses and ordinary data live in the same memory. Some
-special-purpose processors do not satisfy this constraint.
+This option is ignored under non-Unix operating systems.
-@item
-@code{unsigned} data items and addresses fit into the same memory, and
-if @code{union}-ed, take the same space.
+@item -library @var{path}
+@findex -library
+@findex MITSCHEME_LIBRARY_PATH
+Sets the library search path to @var{path}. This is a
+list of directories that is searched to find various library files, such
+as bands. If this option is not given, the value of the environment
+variable @samp{MITSCHEME_LIBRARY_PATH} is used; if that isn't defined,
+the default is used.
-@item
-Signed integers are represented using 2s-complement representation.
+On Unix, the elements of the list are separated by colons, and the
+default value is @samp{/usr/local/lib/mit-scheme}. On PCs, the elements
+of the list are separated by semicolons, and the default value is
+@samp{c:\scheme}.
-@item
-The machine/OS uses the @sc{ascii} character set. This is not a
-property of the compiler per-se, but of the MIT Scheme system.
-@end itemize
+@item -utabmd @var{filename}
+@findex -utabmd
+@findex -utab
+@findex MITSCHEME_UTABMD_FILE
+Specifies that @var{filename} contains the microcode tables (the
+microcode tables are information that informs the runtime system about
+the microcode's structure). @var{Filename} is searched for in the
+working directory and the library directories. If this option isn't
+given, the filename is the value of the environment variable
+@samp{MITSCHEME_UTABMD_FILE}, or if that isn't defined,
+@file{utabmd.bin}; in these cases the library directories are searched,
+but not the working directory.
-In addition, some configuration of the compiler, microcode and
-build-scripts would have to be done for new architectures/operating
-systems. The things that come to mind are:
+@samp{-utab} is an alternate name for the @samp{-utabmd} option; at most
+one of these options may be given.
-@itemize @bullet
-@item
-Dynamic loading primitives are OS-dependent.
+@item -fasl @var{filename}
+@findex -fasl
+Specifies that a @dfn{cold load} should be performed, using
+@var{filename} as the initial file to be loaded. If this option isn't
+given, a normal load is performed instead. This option may not be used
+together with the @samp{-band} option. This option is useful only for
+maintenance and development of the MIT Scheme runtime system.
+@end table
-@item
-Basic microcode configuration, including:
+@noindent
+In addition to the above, @file{bchscheme} recognizes the following
+command line options, all of which specify parameters affecting how
+@file{bchscheme} uses disk storage to do garbage collection:
-@itemize @bullet
-@item
-OS interface.
+@table @code
+@item -gc-directory @var{directory}
+@findex -gc-directory
+@findex MITSCHEME_GC_DIRECTORY
+Specifies that @var{directory} should be used to create files for
+garbage collection. If the option is not given, the value of
+environment variable @samp{MITSCHEME_GC_DIRECTORY} is used instead, and
+if that is not defined, @file{/tmp} is used.
-@item
-Choosing a new machine type (FASL numbers in @file{config. h}).
-@end itemize
+@item -gc-file @var{filename}
+@findex -gc-file
+@findex -gcfile
+@findex MITSCHEME_GC_FILE
+Specifies that @var{filename} should be used for garbage collection. If
+the option is not given, the value of environment variable
+@samp{MITSCHEME_GC_FILE} is used, and if this is not defined, a unique
+filename is generated in the directory specified with
+@samp{-gc-directory}.
-@item
-Build scripts dispatch on the OS and architecture type, and only
-understand a handful of types.
+@samp{-gcfile} is an alias for @samp{-gc-file}; at most one of these
+options should be specified.
-@item
-The compiler has a table of C compiler and linker switches
-for the configurations we have tried. It needs to be extended
-for new configurations, although this can be done easily.
-@end itemize
+@item -gc-keep
+@findex -gc-keep
+Specifies that the @sc{gc} file used for garbage collection should not be
+deleted when Scheme terminates.
+The @sc{gc} file is deleted only if the file was created
+by this invocation of Scheme, and this option is not set.
-If you are interested in bringing up the system on a new configuration,
-please contact us for further instructions, and to obtain the set of
-crude tools that we use to do this.
+@item -gc-start-position @var{number}
+@findex -gc-start-position
+@findex MITSCHEME_GC_START_POSITION
+Specifies the first byte position in @samp{-gc-file} at which the Scheme
+process can write. If not given, the value of the environment variable
+@samp{MITSCHEME_GC_START_POSITION} is used, and if that is not defined,
+@samp{0} is used, meaning the beginning of the file. The area of the
+file used (and locked if possible) is the region between
+@samp{-gc-start-position} and @samp{-gc-end-position}.
-@item
-The performance of the output code could be greatly improved by
-judicious use of assembly language to achieve faster cross-module tail
-recursion. So far, we've given more weight to portability than to
-performance.
+@item -gc-end-position @var{number}
+@findex -gc-end-position
+@findex MITSCHEME_GC_END_POSITION
+Specifies the last byte position in @samp{-gc-file} at which the Scheme
+process can write. If not given, the value of the environment variable
+@samp{MITSCHEME_GC_END_POSITION} is used, and if that is not defined,
+the sum of the start position (as specified by
+@samp{-gc-start-position}) and the heap size is used. The area of the
+file used (and locked if possible) is the region between
+@samp{-gc-start-position} and @samp{-gc-end-position}.
-@item
-The resulting C code can be compiled and statically linked with the MIT
-Scheme @emph{microcode} (the runtime library is linked in this way), or
-compiled and dynamically loaded and linked if the operating system
-supports this feature. The C code must be compiled defining the
-@code{COMPILE_FOR_STATIC_LINKING} if it is to be statically linked into
-the @emph{microcode} or collected into a larger dynamically-loadable
-library (e.g.@: edwin or the compiler). If you'd like to put together a
-shared library of a large subsystem that you have written, please
-contact us for advice on how it can be done.
-@end itemize
+@item -gc-window-size @var{blocks}
+@findex -gc-window-size
+@findex MITSCHEME_GC_WINDOW_SIZE
+Specifies the size of the windows into new space during garbage
+collection. If this option is not given, the value of environment
+variable @samp{MITSCHEME_GC_WINDOW_SIZE} is used instead, and if that is
+not defined, the value 16 is used.
+@end table
-@node Problems with the C Back-End, , Notes on C Back-End, C Back-End Release Notes
-@subsection Problems with the C Back-End
+@noindent
+The following command line options are only used by an experimental
+version of @file{bchscheme} that uses Unix System V-style shared memory,
+and then only if the @file{gcdrone} program is installed in the library
+directory.
-This section details problems and shortcomings of the system that are
-specific to the C back-end.
+@table @code
+@item -gc-drone @var{program}
+@findex -gc-drone
+@findex MITSCHEME_GC_DRONE
+Specifies that @var{program} should be used as the drone program for
+overlapped @sc{i/o} during garbage collection. If the option is not
+given, the value of environment variable @samp{MITSCHEME_GC_DRONE} is
+used instead, and if that is not defined, @file{gcdrone} is used.
-@itemize @bullet
-@item
-@code{compile-procedure} and @code{compile-scode} do not work. This
-will be fixed for a future release and is not very hard to bypass in
-most cases. @code{compile-procedure} gives an error.
-@code{compile-scode} returns something which is not a compiled
-expression. @code{cf} and @code{compile-bin-file} work.
+@item -gc-read-overlap @var{n}
+@findex -gc-read-overlap
+@findex MITSCHEME_GC_READ_OVERLAP
+Specifies that Scheme should delegate at most @var{n} simultaneous disk
+read operations during garbage collection. If the option is not given,
+the value of environment variable @samp{MITSCHEME_GC_READ_OVERLAP} is
+used instead, and if that is not defined, @samp{0} is used, disabling
+overlapped reads.
-@item
-Dynamically loaded compiled modules are not unloaded when no longer
-accessed. In particular, after a @code{disk-restore}, previously loaded
-modules are still mapped. In addition, at least in some versions of
-unix, the shared object file cannot be deleted while it is loaded, so
-re-compilation of a module in place will fail if some process has it
-already loaded.
+@item -gc-write-overlap @var{n}
+@findex -gc-write-overlap
+@findex MITSCHEME_GC_WRITE_OVERLAP
+Specifies that Scheme should delegate at most @var{n} simultaneous disk
+write operations during garbage collection. If the option is not given,
+the value of environment variable @samp{MITSCHEME_GC_WRITE_OVERLAP} is
+used instead, and if that is not defined, @samp{0} is used, disabling
+overlapped writes.
+@end table
-@item
-Multiple loading does not work. This is bad for development. After
-loading a compiled module once, it cannot be reloaded (presumably after
-re-compilation).
+@noindent
+The following options are runtime options. They are processed after the
+microcode options and after the image file is loaded.
-@item
-@code{fasdump} does not work for compiled code. It gives an error.
-Only bands can be dumped.
+@table @code
+@item -no-init-file
+@findex -no-init-file
+This option causes Scheme to ignore the @file{~/.scheme.init} or
+@file{scheme.ini} file, normally loaded automatically when Scheme starts
+(if it exists).
-@item
-Several C compilers are unhappy about the size of the resulting C
-procedures. They often turn their optimizers off.
+@item -suspend-file
+@findex -suspend-file
+Under some circumstances Scheme can write out a file called
+@file{scheme_suspend} in the user's home directory.@footnote{Under Unix,
+this file is written when Scheme is terminated by the @samp{SIGUSR1},
+@samp{SIGHUP}, or @samp{SIGPWR} signals. Under other operating systems,
+this file is never written.} This file is a world image containing the
+complete state of the Scheme process; restoring this file continues the
+computation that Scheme was performing at the time the file was written.
-@item
-Some C compilers/optimizers produce non-working code for some of the
-output. In particular, we've had serious problems with the
-RS6000/AIX-3.2 C compiler.
+Normally this file is never written, but the @samp{-suspend-file} option
+enables writing of this file.
-@item
-Several C compilers give copious ``statement not reached'' warnings
-about the resulting code. This arises from the heavy use of macros
-expanding into the pattern
+@item -eval
+@findex -eval
+This option causes Scheme to evaluate the expressions following it on
+the command line, up to (but not including) the next option that starts
+with a hyphen. The expressions are evaluated in the
+@code{user-initial-environment}.
+Unless explicitly handled, errors during evaluation are silently ignored.
-@example
-do
-@{
- @var{body}
-@} while (0)
-@end example
+@item -load
+@findex -load
+This option causes Scheme to load the files (or lists of files)
+following it on the command line, up to (but not including) the next
+option that starts with a hyphen. The files are loaded in the
+@code{user-initial-environment} using the default syntax table.
+Unless explicitly handled, errors during loading are silently ignored.
+@end table
-@noindent
-Most of these macros are not really necessary, and the code generator
-could just issue the @var{body} directly.
+@node Environment Variables, Starting Scheme from Windows, Command-Line Options, Running Scheme
+@section Environment Variables
-@item
-The mechanism for accreting object files into large dynamically-loadable
-libraries is currently ad-hoc.
-@end itemize
+Scheme refers to many environment variables. This section lists these
+variables and describes how each is used. The environment variables are
+organized according to the parts of MIT Scheme that they affect.
-@node PC Release Notes, , C Back-End Release Notes, Release Notes
-@section PC Release Notes
+Environment variables that affect the microcode must be defined before
+you start Scheme; under Unix or Windows, others can be defined or
+overwritten within Scheme by using the @code{set-environment-variable!}
+procedure, e.g.@:
+
+@example
+(set-environment-variable! "EDWIN_FOREGROUND" "32")
+@end example
@menu
-* Known Problems::
+* Microcode Environment Variables::
+* Bchscheme Environment Variables::
+* Runtime Environment Variables::
+* Edwin Environment Variables::
+* Windows Environment Variables::
+* OS/2 Environment Variables::
@end menu
-@node Known Problems, , PC Release Notes, PC Release Notes
-@subsection Known Problems in this Beta Release
+@node Microcode Environment Variables, Bchscheme Environment Variables, Environment Variables, Environment Variables
+@subsection Environment Variables for the Microcode
-@itemize @bullet
-@item
-The Windows version of MIT Scheme is more robust under NT than Windows
-3.1
+These environment variables are referred to by the microcode (the
+executable C programs called @file{scheme} and @file{bchscheme} under
+Unix, and @file{scheme.exe} and @file{bchschem.exe} on the PC).
-@item
-[NT] Exclusive file access problems. Edwin sometimes can't write a file
-that is still open for reading.
+@table @asis
+@item @samp{MITSCHEME_BAND} (default: @file{runtime.com} on the library path)
+@findex MITSCHEME_BAND
+The initial band to be loaded. Overridden by @samp{-band},
+@samp{-compiler}, or @samp{-edwin}.
-Typically you will have entered @code{(load "foo.scm")} in the
-interaction buffer and got an error, say a mis-matched parenthesis.
-You then switch to the @code{foo.scm} buffer, fix the problem and then
-try to save the file.
-Edwin refuses, saying
+@item @code{MITSCHEME_COMPILER_BAND} (default: @file{compiler.com} on the library path)
+@findex MITSCHEME_COMPILER_BAND
+The initial band to be loaded if the @samp{-compiler} option is given.
+Overridden by @samp{-band}.
-@example
-Unable to open file "@var{your-path}\\foo.scm" because: Unknown
-@end example
+@item @code{MITSCHEME_EDWIN_BAND} (default: @file{edwin.com} on the library path)
+@findex MITSCHEME_EDWIN_BAND
+The initial band to be loaded if the @samp{-edwin} option is given.
+Overridden by @samp{-band}.
-@noindent
-Work-around: In the interaction buffer: Quit to top level. Do a
-@code{(gc-flip)}, which forces the file to be closed when the file port
-is garbage-collected. Now you will be able to save the file.
+@item @code{MITSCHEME_LARGE_CONSTANT} (default: @samp{1000})
+@findex MITSCHEME_LARGE_CONSTANT
+The size of constant space, in 1024-word blocks, if the @samp{-large},
+@samp{-compiler}, or @samp{-edwin} options are given. Overridden by
+@samp{-constant}. Note: default depends on machine; on most machines it
+is larger than @samp{1000}.
-@item
-@code{MITSCHEME_INF_DIRECTORY} sometimes does not work.
-The runtime system cannot find the debugging information unless it is on
-the @file{C:} drive.
-To test if the debugging information is available, try
+@item @code{MITSCHEME_LARGE_HEAP} (default: @samp{1000})
+@findex MITSCHEME_LARGE_HEAP
+The size of the heap, in 1024-word blocks, if the @samp{-large},
+@samp{-compiler}, or @samp{-edwin} options are given. Overridden by
+@samp{-heap}.
-@example
-(pp pp)
-@end example
+@item @code{MITSCHEME_LARGE_STACK} (default: @samp{100})
+@findex MITSCHEME_LARGE_STACK
+The size of the stack, in 1024-word blocks, if the @samp{-large},
+@samp{-compiler}, or @samp{-edwin} options are given. Overridden by
+@samp{-stack}.
-@noindent
-If the debugging information is available the @code{pp} procedure
-pretty-prints procedures as Scheme code.
-If the information cannot be found then it prints the procedure as an
-opaque object, similar to this:
+@item @code{MITSCHEME_LIBRARY_PATH}
+@findex MITSCHEME_LIBRARY_PATH
+A list of directories. These directories are searched,
+left to right, to find bands and various other files.
+On Unix systems the list is colon separated, with the default
+@file{/usr/local/lib/mit-scheme}.
+On PC systems the list is semi-colon separated with the default
+@file{c:\scheme\lib}.
-@example
-#[compiled-procedure 13 ("pp" #x2) #xF #x646BF7]
-@end example
+@item @code{MITSCHEME_SMALL_CONSTANT} (default: @samp{450})
+@findex MITSCHEME_SMALL_CONSTANT
+The size of constant space, in 1024-word blocks, if the size options are
+not given. Overridden by @samp{-constant}, @samp{-large},
+@samp{-compiler}, or @samp{-edwin}. Note: default depends on machine;
+on most machines it is larger than @samp{450}.
-@item
-Edwin autoloads.
-A few files that are automatically part of Edwin under unix are not part
-of Edwin in the PC. These can be loaded manually from the auto-load
-directory, for example, by putting
+@item @code{MITSCHEME_SMALL_HEAP} (default: @samp{250})
+@findex MITSCHEME_SMALL_HEAP
+The size of the heap, in 1024-word blocks, if the size options are not
+given. Overridden by @samp{-heap}, @samp{-large}, @samp{-compiler}, or
+@samp{-edwin}.
-@example
-(edwin-load "dabbrev")
-@end example
+@item @code{MITSCHEME_SMALL_STACK} (default: @samp{100})
+@findex MITSCHEME_SMALL_STACK
+The size of the stack, in 1024-word blocks, if the size options are not
+given. Overridden by @samp{-stack}, @samp{-large}, @samp{-compiler}, or
+@samp{-edwin}.
-@noindent
-in your @file{edwin.ini} file.
+@item @code{MITSCHEME_UTABMD_FILE} (default: @file{utabmd.bin} in the library path)
+@findex MITSCHEME_UTABMD_FILE
+The file containing the microcode tables. Overridden by @samp{-utabmd}
+and @samp{-utab}. It is only necessary when re-building
+@file{runtime.com}.
+@end table
-@item
-DOS version 6. Although we have not tested the DOS version under
-anything other than MS-DOS 5.0, we have the following anecdotal evidence:
+@node Bchscheme Environment Variables, Runtime Environment Variables, Microcode Environment Variables, Environment Variables
+@subsection Environment Variables for @file{bchscheme}
-@itemize @bullet
-@item
-On DOS 6.2 with @code{emm386} you may have to put the following in
-@file{config.sys}:
+These environment variables are referred to by @file{bchscheme}
+(@emph{not} by @file{scheme}).
-@example
-device=emm386 noems novcpi
-@end example
-@end itemize
-@end itemize
+@table @asis
+@item @code{MITSCHEME_GC_DIRECTORY} (default: @file{/tmp})
+@findex MITSCHEME_GC_DIRECTORY
+The directory in which @sc{gc} files are written. Overridden by
+@samp{-gc-directory}.
-@c @node
-@c @subsection NT build
-@c
-@c
-@c @table @asis
-@c @item Build
-@c The Windows/NT version can be built only under Windows NT.
-@c
-@c @item no TOUCH command
-@c Create the following 1 line script in @file{TOUCH.BAT}:
-@c
-@c @example
-@c echo on > %1
-@c @end example
-@c
-@c @item can't find @file{w32sut.h}
-@c These files are a part of Win32S: @file{w32sut.h}, @file{?.dll}, @file{?.dll}
-@c You need to copy @file{w32sut.h} from
-@c @end table
-@c
-@c
-@c w32sut.h & dlls to ntutl/config?
+@item @code{MITSCHEME_GC_FILE} (default: @file{GCXXXXXX})
+@findex MITSCHEME_GC_FILE
+The name of the file to use for garbage collection. If it ends in 6 Xs,
+the Xs are replaced by a letter and process id of the scheme process,
+thus generating a unique name. Overridden by @samp{-gc-file}.
-@c NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
-@node Running Scheme, REPL, Release Notes, Top
-@chapter Running Scheme
+@item @code{MITSCHEME_GC_START_POSITION} (default: @samp{0})
+@findex MITSCHEME_GC_START_POSITION
+The first position in the @sc{gc} file to use. Overridden by
+@samp{-gc-start-position}.
-This chapter describes how to run MIT Scheme on a unix system or a PC
-running DOS, Windows 3.1, or Windows NT.
-It also describes how you can customize the behavior of MIT Scheme
-using command-line options and environment variables.
+@item @code{MITSCHEME_GC_END_POSITION} (default: @var{start-position}+@var{heap-size})
+@findex MITSCHEME_GC_END_POSITION
+The last position in the @sc{gc} file to use. Overridden by
+@samp{-gc-end-position}.
-@menu
-* Basics of Starting Scheme::
-* Customizing Scheme::
-* Command-Line Options::
-* Environment Variables::
-* Starting Scheme from Windows 3.1/NT::
-* Leaving Scheme::
-@end menu
+@item @code{MITSCHEME_GC_WINDOW_SIZE} (default: @samp{16})
+@findex MITSCHEME_GC_WINDOW_SIZE
+The size in blocks of windows into new space (in the @sc{gc} file).@*
+Overridden by @samp{-gc-window-size}.
+@end table
-@node Basics of Starting Scheme, Customizing Scheme, Running Scheme, Running Scheme
-@section Basics of Starting Scheme
+@noindent
+The following environment variables are only used by an experimental
+version of Bchscheme that uses Unix System V-style shared memory, and
+then only if the @file{gcdrone} program is installed:
-Usually, MIT Scheme is invoked by typing
+@table @asis
+@item @code{MITSCHEME_GC_DRONE} (default: @file{gcdrone})
+@findex MITSCHEME_GC_DRONE
+The program to use as the @sc{i/o} drone during garbage collection.@*
+Overridden by @samp{-gc-drone}.
-@example
-scheme
-@end example
+@item @code{MITSCHEME_GC_READ_OVERLAP} (default: @samp{0})
+@findex MITSCHEME_GC_READ_OVERLAP
+The maximum number of simultaneous read operations.@*
+Overridden by @samp{-gc-read-overlap}.
-@noindent
-at your operating system's command interpreter. (Under Windows 3.1 you
-must use the Program Manager's @var{Run} command, or an icon.) Scheme
-will load itself, clear the screen, and print something like this:
+@item @code{MITSCHEME_GC_WRITE_OVERLAP} (default: @samp{0})
+@findex MITSCHEME_GC_WRITE_OVERLAP
+The maximum number of simultaneous write operations.@*
+Overridden by @samp{-gc-write-overlap}.
+@end table
-@example
-Scheme saved on Thursday December 2, 1993 at 6:18:35 PM
- Release 7.3.0 (beta)
- Microcode 11.146
- Runtime 14.166
-@end example
+@node Runtime Environment Variables, Edwin Environment Variables, Bchscheme Environment Variables, Environment Variables
+@subsection Environment Variables for the Runtime System
-@noindent
-This information, which can be printed again by evaluating
+These environment variables are referred to by the runtime system.
-@findex identify-world
-@lisp
-(identify-world)
-@end lisp
+@table @asis
+@item @code{HOME}
+@findex HOME
+Directory in which to look for init files. E.g.@: @samp{c:\users\joe} or
+@samp{/home/joe}.
-@cindex release number
-@cindex microcode, version
-@cindex runtime system, version
-@cindex version numbers
-@noindent
-tells you the following version information. ``Release'' is the release
-number for the entire Scheme system. This number is changed each time a
-new version of Scheme is released. An ``(alpha)'' or ``(beta)''
-following the release number indicates that this is a alpha- or
-beta-test release. ``Microcode'' is the version number for the part of
-the system that is written in C. ``Runtime'' is the version number for
-the part of the system that is written in Scheme.
+@item @code{TEMP}
+@itemx @code{TMP}
+@findex TEMP
+@findex TMP
+Directory for various temporary files. @samp{TEMP} is given preference
+to @samp{TMP}.
+
+@item @code{MITSCHEME_INF_DIRECTORY} (default: @samp{SRC} on the library path)
+@findex MITSCHEME_INF_DIRECTORY
+Directory containing the debugging information files for the Scheme
+system. Should contain subdirectories corresponding to the
+subdirectories in the source tree. For example, if its value is
+@file{f:\random}, runtime system debugging files will be expected in
+@file{f:\random\runtime}, while Edwin debugging files will be expected
+in @file{f:\random\edwin}.
-@cindex subsystem versions
-@cindex SF, version
-@cindex compiler, version
-@cindex Edwin, version
-@cindex student package, version
-@cindex compatibility package, version
-Following this there may be additional version numbers for specific
-subsystems. @samp{SF} refers to the scode optimization program
-@code{sf}, @samp{Liar} is the native-code compiler,
-@samp{Edwin} is the Emacs-like text editor,
-and @samp{Student} is the S&ICP compatibility package.
+@item @code{MITSCHEME_LOAD_OPTIONS} (default: @file{optiondb.scm} on the library path)
+@findex MITSCHEME_LOAD_OPTIONS
+Specifies the location of the options database file used by the
+@code{load-option} procedure.
+@end table
-@cindex compiler, starting
-If the compiler is supported for your machine, you can invoke it by
-giving Scheme the @samp{-compiler} option:
+@node Edwin Environment Variables, Windows Environment Variables, Runtime Environment Variables, Environment Variables
+@subsection Environment Variables for Edwin
-@example
-scheme -compiler
-@end example
+These environment variables are referred to by Edwin.
-@noindent
-This option causes Scheme to use a larger constant space and heap, and
-to load the world image containing the compiler.
+@table @asis
+@item @code{EDWIN_BINARY_DIRECTORY} (default: @file{edwin/autoload} on the library path)
+@findex EDWIN_BINARY_DIRECTORY
+Directory where Edwin expects to find files providing autoloaded
+facilities.
-@node Customizing Scheme, Command-Line Options, Basics of Starting Scheme, Running Scheme
-@section Customizing Scheme
+@item @code{EDWIN_INFO_DIRECTORY} (default: @file{edwin/info} on the library path)
+@findex EDWIN_INFO_DIRECTORY
+Directory where Edwin expects to find files for the `info' documentation
+subsystem.
-You can customize your setup by using a variety of tools:
+@item @code{EDWIN_ETC_DIRECTORY} (default: @file{edwin/etc} on the library path)
+@findex EDWIN_ETC_DIRECTORY
+Directory where Edwin expects to find utility programs and documentation
+strings.
-@itemize @bullet
-@item
-@cindex command line options
-@dfn{Command-line options}.
-Many parameters, like memory usage and the location of libraries, may be
-varied by command line options.
+@item @code{ESHELL}
+@findex ESHELL
+Unix and OS/2 only.
+Filename of the shell program to use in shell buffers. If not defined,
+@samp{SHELL} is used instead.
+
+@item @code{SHELL} (default: @file{/bin/sh} (Unix), @file{cmd.exe} (OS/2))
+@findex SHELL
+Unix and OS/2 only.
+Filename of the shell program to use in shell buffers and when executing
+shell commands. Used to initialize the @code{shell-path-name} editor
+variable.
-@item
-@dfn{Command scripts or batch files}.
-@cindex command scripts
-You might like to write scripts that invoke Scheme with your favourite
-command line options. For example, under DOS you might not have enough
-memory to run edwin or the compiler with its default memory parameters
-(it will print something like ``Not enough memory for this
-configuration'' and halt when started), so you can write a shell script
-(unix) or a @file{.bat} file (PC) that will invoke Scheme with the
-appropriate @samp{-heap} and other parameters.
+@item @code{PATH}
+@findex PATH
+Unix and OS/2 only.
+Used to initialize the @code{exec-path} editor variable, which is
+subsequently used for finding programs to be run as subprocesses.
-@item
-@cindex init file
-Scheme supports @dfn{init files}: if the file @file{.scheme.init} exists
-in your home directory, it is loaded immediately after the
-identification banner, and before the input prompt is printed.
-In addition, when it starts up, edwin loads the file @file{.edwin} from
-your home directory into the edwin environment. You can use both of
-these files to define new procedures, commands, or change defaults in
-the system.
-
-The @code{-no-init-file} command line option causes Scheme to ignore the
-@file{.scheme.init} file (@pxref{Command-Line Options}).
+@item @code{DISPLAY}
+@findex DISPLAY
+Unix running X11 only.
+Specifies the display on which Edwin will create windows.
-On PC systems these initialization files are called @file{scheme.ini}
-and @file{edwin.ini} respectively and are searched for in the directory
-identified by the @code{HOME} environment variable.
+@item @code{TERM}
+@findex TERM
+Unix terminals only.
+Terminal type.
-@item
-@dfn{Environment variables}. Most microcode parameters, and some runtime
-system and Edwin parameters, can be specified by means of environment
-variables. @xref{Environment Variables}.
+@item @code{LINES} (default: auto-sense)
+@findex LINES
+Unix terminals only.
+Number of text lines on the screen, for systems that don't support
+@samp{TIOCGWINSZ}.
-@item
-@dfn{Icons}.
-@cindex icons
-Under Windows and Windows NT it is possible to create icons in
-the Program Manager that invoke Scheme with different parameters.
-@end itemize
+@item @code{COLUMNS} (default: auto-sense)
+@findex COLUMNS
+Unix terminals only.
+Number of text columns on the screen, for systems that don't support
+@samp{TIOCGWINSZ}.
+@end table
-One of the important parameters that can be customized is how much
-memory Scheme uses and how that memory is used. Scheme uses four kinds
-of memory:
-@cindex memory
-@cindex heap space
-@cindex stack space
-@cindex constant space
+@node Windows Environment Variables, OS/2 Environment Variables, Edwin Environment Variables, Environment Variables
+@subsection Environment Variables for Windows
-@itemize @bullet
-@item
-A @dfn{stack} which is used for recursive procedure calls,
+These environment variables are specific to the Windows implementation.
-@item
-A @dfn{heap} which is used for dynamically allocated objects, like @samp{cons}
-cells and strings.
-Storage used for objects in the heap which become unreferenced is
-eventually reclaimed by @dfn{garbage collection}.
+@table @asis
+@item @code{MITSCHEME_FONT} (default: determined by operating system)
+@findex MITSCHEME_FONT
+@cindex fonts
+A string specifying a font name and characteristics, for example,
+@samp{Courier New 16 bold}.
+Allowed characteristics are @var{integer}, specifiying the font size,
+and the following style modifiers: @samp{bold}, @samp{italic},
+@samp{regular}, @samp{underline} and @samp{strikeout}.
+Note that the size is the total height in pixels, and @strong{not} the
+point size.
+Thus the fonts tend to be 20-50% smaller than you might expect.
+You should specifiy only fixed-width fonts as variable width fonts are
+not drawn correctly.
-@item
-A @dfn{constant space}, which is used for allocated objects, like the
-heap.
-Unlike the heap, storage used for objects in constant space is not
-reclaimed by garbage collection.
-Constant space is used for objects that are essentially permanent, like
-procedures from the runtime system.
+Once in Edwin, the font can be changed with the @samp{set-font} and
+@samp{set-default-font} commands.
-@item
-An amount of extra storage which is used by the Microcode (the part
-of the system that is implemented in C).
-@end itemize
+@item @code{MITSCHEME_GEOMETRY} (default: @samp{-1,-1,-1,-1})
+@findex MITSCHEME_GEOMETRY
+@cindex window position
+Four integers separated by
+commas or spaces that specify the placement and size of the MIT Scheme
+window as a @var{left,top,width,height} quadruple. The units are screen
+pixels, and @samp{-1} means allow the system to choose this parameter.
+E.g.@: @samp{-1,-1,500,300} places a 500 by 300 pixel window at some
+system-determined position on the screen. The width and height include
+the window border and title.
-@findex bchscheme
-All aspects except the last may be controlled both by command-line
-options and by environment variables. MIT Scheme uses a two-space
-copying garbage collector for reclaiming storage in the heap. There are
-two version of Scheme which handle garbage collection differently.
-Ordinary @code{scheme} has two heaps, one for each `space'.
-@code{bchscheme} has one heap and uses a disk file for the other
-`space', thus trading memory usage against garbage collection speed.
+@item @code{MITSCHEME_FOREGROUND} (default: according to desktop color scheme)
+@findex MITSCHEME_FOREGROUND
+@cindex window color
+A value specifying the window
+text color. The color is specified as hex blue, green and red values
+(@emph{not} RGB): e.g.@: @code{0xff0000} for blue.
-The total storage required by @code{scheme} is:
+@item @code{MITSCHEME_BACKGROUND} (default: according to desktop color scheme)
+@findex MITSCHEME_BACKGROUND
+A value specifying the window background color. See
+@samp{MITSCHEME_FOREGROUND}.
+
+@item @code{HOMEDRIVE}
+@itemx @code{HOMEPATH}
+@findex HOMEDRIVE
+@findex HOMEPATH
+These variables are used together to indicate the user's home
+directory. This is the preferred way to specify the home directory.
+
+@item @code{USERNAME}
+@itemx @code{USER}
+@findex USERNAME
+@findex USER
+Specifies the login name of the user running Scheme. This is used for
+several different purposes. @samp{USERNAME} is preferred; @samp{USER}
+is used if @samp{USERNAME} is not defined. If neither of these
+variables is defined, @code{"nouser"} is used as the user's name.
+
+@item @code{USERDIR}
+@findex USERDIR
+Specifies a directory that contains the home directories of users. One
+of the places in which Scheme looks for the user's home directory, by
+searching for a subdirectory with the user's login name.
+@c
+@c @item @code{MITSCHEME_TRAP_ALT_TAB} (default: @samp{false})
+@c @itemx @code{MITSCHEME_TRAP_ALT_ESCAPE} (default: @samp{false})
+@c @findex MITSCHEME_TRAP_ALT_TAB
+@c @findex MITSCHEME_TRAP_ALT_ESCAPE
+@c Boolean option specifying the handling of system command accelerators.
+@c These options do not actually work.
+@end table
-@example
-@var{stack} + (@var{constant} + 2*@var{heap}) + @var{extra}
-@end example
+@node OS/2 Environment Variables, , Windows Environment Variables, Environment Variables
+@subsection Environment Variables for OS/2
-@noindent
-where @var{stack}, @var{constant} and @var{heap} are parameters that may
-be selected when @samp{scheme} starts.
-For @code{bchscheme}, which has only one heap in memory, the equation is
+These environment variables are specific to the OS/2 implementation.
-@example
-@var{stack} + (@var{constant} + @var{heap}) + @var{extra}
-@end example
+@table @asis
+@item @code{USER}
+@findex USER
+Specifies the login name of the user running Scheme. This is used for
+several different purposes. If this variable is undefined,
+@code{"nouser"} is used as the user's name.
+
+@item @code{USERDIR}
+@findex USERDIR
+Specifies a directory that contains the home directories of users. One
+of the places in which Scheme looks for the user's home directory, by
+searching for a subdirectory with the user's login name.
+@end table
-Once the storage is allocated for the constant space and the heap,
-Scheme will dynamically adjust the proportion of the total that is used
-for constant space. The stack and the extra microcode storage is not
-included in this adjustment. Previous versions of MIT Scheme needed to
-be told the amount of constant space that was required when loading your
-own bands with the @code{-band} option. Dynamic adjustment of the heap
-and constant space avoids this problem; now all that is required is that
-the total space is sufficient.
+@node Starting Scheme from Windows, Leaving Scheme, Environment Variables, Running Scheme
+@section Starting Scheme from Windows
-The Scheme procedure @code{(print-gc-statistics)} shows how much heap
-and constant space is available.
+The Windows version of MIT Scheme runs as a graphics-based application
+under Windows 3.1, Windows 95, and Windows NT.
-@node Command-Line Options, Environment Variables, Customizing Scheme, Running Scheme
-@section Command-Line Options
+Under Windows 3.1, Scheme must be run from the Program Manager or the
+File Manager. Scheme cannot be run from the command line, because only
+DOS programs can be run from the command line. Windows 95 and Windows
+NT overcome this restriction, but it is still useful to know how to run
+Scheme from the Desktop.
-Scheme accepts the command-line options detailed in the following
-sections. The options may appear in any order, with the restriction
-that the microcode options must appear before the runtime options, and
-the runtime options must appear before any other arguments on the
-command line. (At present, any arguments other than these options will
-generate a warning message when Scheme starts. In the future, there
-will be an advertised mechanism by which the extra arguments can be
-handled by user code.)
+Once an icon is set up to run Scheme with some particular command line
+options, Scheme is run by double-clicking that icon.
+The rest of this section gives some tips on how to set up
+Program Manager icons that run Scheme. If you are unfamiliar with this
+concept you should read about it under the help topic of the Program
+Manager.
-These are the microcode options:
+Under Windows NT program manager groups can be @emph{common} or
+@emph{personal}. When setting up icons in a common group it is
+important to make the icons independent of the vagaries of the
+environment of the user who is running them. It is often worthwhile
+doing this under Windows 3.1 and for personal groups too. Here are some
+guidelines to accomplish this:
-@table @code
-@item -band @var{filename}
-@findex -band
-@findex MITSCHEME_BAND
-@cindex world image
-@cindex band
-Specifies the initial world image file (@dfn{band}) to be loaded.
-Searches for @var{filename} in the working directory and the library
-directories, using the full pathname of the first readable file of that
-name. If @var{filename} is an absolute pathname (on unix, this means it
-starts with @samp{/}), then no search occurs --- @var{filename} is
-tested for readability and then used directly. If this option isn't
-given, the filename is the value of the environment variable
-@code{MITSCHEME_BAND}, or if that isn't defined, @file{runtime.com}; in
-these cases the library directories are searched, but not the working
-directory.
+@itemize @bullet
+@item
+Give the icon an accurate @var{Description}.
-@item -compiler
-@findex -compiler
-@findex MITSCHEME_COMPILER_BAND
-This option specifies defaults appropriate for loading the compiler. It
-specifies the use of large sizes, exactly like @code{-large}. If the
-@code{-band} option is also specified, that is the only effect of this
-option. Otherwise, the default band's filename is the value of the
-environment variable @code{MITSCHEME_COMPILER_BAND}, if defined, or
-@file{compiler.com}; the library directories are searched to locate this
-file. Note that the @code{-compiler} option is available only on
-machines with compiled-code support.
+@item
+Include absolute pathnames to @file{scheme.exe} and @file{bchscheme.exe}
+in the icon @var{Command line} if these executables are not in a
+directory on the default @samp{PATH}.
-@item -edwin
-@findex -edwin
-@findex MITSCHEME_EDWIN_BAND
-This option specifies defaults appropriate for loading the editor. It
-specifies the use of large sizes, exactly like @code{-large}. If the
-@code{-band} option is also specified, that is the only effect of this
-option. Otherwise, the default band's filename is the value of the
-environment variable @code{MITSCHEME_EDWIN_BAND}, if defined, or
-@file{edwin.com}; the library directories are searched to locate this
-file. Note that the @code{-edwin} option is available only on machines
-with compiled-code support.
+@item
+Set the icon's @var{Working Directory} to: @samp{%HOMEPATH%}
-@item -large
-@findex -large
-Specifies that large heap, constant, and stack sizes should be used.
-These are specified by the environment variables
+@item
+There are several icons available --- choose one that best represents
+the options given on the command line.
+
+@item
+Specifying a band that contains Edwin is not sufficient to invoke the
+editor. You also have to put
-@findex MITSCHEME_LARGE_HEAP
-@findex MITSCHEME_LARGE_CONSTANT
-@findex MITSCHEME_LARGE_STACK
@example
-MITSCHEME_LARGE_HEAP
-MITSCHEME_LARGE_CONSTANT
-MITSCHEME_LARGE_STACK
+-eval (edit)
@end example
-@noindent
-If this option isn't given, the small sizes are used, specified by the
-environment variables
+at the end of the command line.
+@end itemize
-@findex MITSCHEME_SMALL_HEAP
-@findex MITSCHEME_SMALL_CONSTANT
-@findex MITSCHEME_SMALL_STACK
+@node Leaving Scheme, , Starting Scheme from Windows, Running Scheme
+@section Leaving Scheme
+
+There are several ways that you can leave Scheme: there are two Scheme
+procedures that you can call; there are several Edwin commands that you
+can execute; and there are are graphical-interface buttons (and their
+associated keyboard accelerators) that you can activate.
+
+@itemize @bullet
+@item
+@emph{Two Scheme procedures that you can call.} The first is to
+evaluate
+
+@findex exit
@example
-MITSCHEME_SMALL_HEAP
-MITSCHEME_SMALL_CONSTANT
-MITSCHEME_SMALL_STACK
+(exit)
@end example
@noindent
-There are reasonable built-in defaults for all of these environment
-variables, should any of them be undefined. Note that any or all of the
-defaults can be individually overridden by the @code{-heap},
-@code{-constant}, and @code{-stack} options.
+which will halt the Scheme system, after first requesting confirmation.
+Any information that was in the environment is lost, so this should not
+be done lightly.
-@findex print-gc-statistics
-Note: the Scheme procedure @code{(print-gc-statistics)} shows how much
-heap and constant space is available and in use.
+The second procedure suspends Scheme; when this is done you may later
+restart where you left off. Unfortunately this is not possible in all
+operating systems; currently it works under Unix versions that support
+job control (i.e.@: all of the Unix versions for which we distribute
+Scheme). To suspend Scheme, evaluate
-@item -heap @var{blocks}
-@findex -heap
-Specifies the size of the heap in 1024-word blocks. Overrides any
-default. Normally two such heaps are allocated; @code{bchscheme}
-allocates only one, and uses a disk file for the other.
+@findex quit
+@example
+(quit)
+@end example
-@item -constant @var{blocks}
-@findex -constant
-Specifies the size of constant space in 1024-word blocks. Overrides any
-default. Constant space holds the compiled code for the runtime system
-and other subsystems.
+@noindent
+If your system supports suspension, this will cause Scheme to stop, and
+you will be returned to the operating system's command interpreter.
+Scheme remains stopped, and can be continued using the job-control
+commands of your command interpreter. If your system doesn't support
+suspension, this procedure does nothing. (Calling the @code{quit}
+procedure is analogous to typing @kbd{C-z}, but it allows Scheme
+to respond by typing a prompt when it is unsuspended.)
-@item -stack @var{blocks}
-@findex -stack
-Specifies the size of the stack in 1024-word blocks. Overrides any
-default. This is Scheme's stack, @emph{not} the unix stack used by C
-programs.
+@item
+@emph{Several Edwin commands that you can execute.} These commands
+include @code{save-buffers-kill-scheme}, normally bound to @kbd{C-x
+C-c}, and @code{suspend-scheme}, normally bound to @kbd{C-x C-z}. These
+two commands correspond to the procedures @code{exit} and @code{quit},
+respectively.
-@item -option-summary
-@findex -option-summary
-Causes Scheme to write an option summary to standard error. This shows
-the values of all of the settable microcode option variables.
+@item
+@emph{Graphical-interface buttons that you can activate.} Under OS/2
+and Windows, closing the console window (Scheme's main window) causes
+Scheme to be terminated. Under any operating system, closing an Edwin
+window causes that window to go away, and if it is the only Edwin
+window, it terminates Scheme as well.
-@item -emacs
-@findex -emacs
-Specifies that Scheme is running as a subprocess of GNU Emacs. This
-option is automatically supplied by GNU Emacs, and should not be given
-under other circumstances.
+Under OS/2, there are two distinct ways to close the console window.
+The first is to use any of the usual window-closing methods, such as the
+@samp{Close} system-menu item or double-clicking on the system-menu
+icon. When this is done, you will be presented with a dialog that gives
+you the option to close the window with or without termating Scheme.
+The second way is to select the @samp{Exit} item from the @samp{File}
+menu, which terminates Scheme immediately with no dialog.
+@end itemize
-@item -interactive
-@findex -interactive
-If this option isn't specified, and Scheme's standard @sc{i/o} is not a
-terminal, Scheme will detach itself from its controlling terminal. This
-will prevent it from getting signals sent to the process group of that
-terminal. If this option is specified, Scheme will not detach itself
-from the controlling terminal.
+@node Using Scheme, Compiling Programs, Running Scheme, Top
+@chapter Using Scheme
-This detaching behavior is useful for running Scheme as a background
-job. For example, using the C shell in unix, the following will run
-Scheme as a background job, redirecting its input and output to files,
-and preventing it from being killed by keyboard interrupts or by logging
-out:
+This chapter describes how to use Scheme to evaluate expressions and
+load programs. It also describes how to save custom ``world images'',
+and how to control the garbage collector. Subsequent chapters will
+describe how to use the compiler, and how to debug your programs.
-@example
-scheme < /usr/cph/foo.in >& /usr/cph/foo.out &
-@end example
+@menu
+* REPL::
+* Loading Files::
+* World Images::
+* Garbage Collection::
+@end menu
-This option only makes sense under unix.
+@node REPL, Loading Files, Using Scheme, Using Scheme
+@section The Read-Eval-Print Loop
-@item -nocore
-@findex -nocore
-Specifies that Scheme should not generate a core dump under any
-circumstances. Under unix, if this option is not given, and Scheme
-terminates abnormally, you will be prompted to decide whether a core
-dump should be generated.
+@cindex REPL
+When you first start up Scheme from the command line (i.e.@: not under
+Edwin), you will be typing at a program called the @dfn{Read-Eval-Print
+Loop} (abbreviated @dfn{REPL}). It displays a prompt at the left hand
+side of the screen whenever it is waiting for input. You then type an
+expression (terminating it with @key{RET}). Scheme evaluates the
+expression, prints the result, and gives you another prompt.
-This option is ignored on PC versions.
+@menu
+* The Prompt and Level Number::
+* Interrupting::
+* Restarting::
+* The Current REPL Environment::
+@end menu
-@item -library @var{path}
-@findex -library
-@findex MITSCHEME_LIBRARY_PATH
-Sets the library search path to @var{path}. This is a
-list of directories that is searched to find various library files, such
-as bands. If this option is not given, the value of the environment
-variable @code{MITSCHEME_LIBRARY_PATH} is used; if that isn't defined,
-the default is used.
+@node The Prompt and Level Number, Interrupting, REPL, REPL
+@subsection The Prompt and Level Number
-On unix, the elements of the list are separated by colons, and the
-default value is @samp{/usr/local/lib/mit-scheme}. On PCs, the elements
-of the list are separated by semicolons, and the default value is
-@samp{c:\scheme}.
+@cindex prompt, REPL
+The @sc{repl} @dfn{prompt} normally has the form
-@item -utabmd @var{filename}
-@item -utab @var{filename}
-@findex -utabmd
-@findex -utab
-@findex MITSCHEME_UTABMD_FILE
-Specifies that @var{filename} contains the microcode tables (the
-microcode tables are information that informs the runtime system about
-the microcode's structure). @var{Filename} is searched for in the
-working directory and the library directories. If this option isn't
-given, the filename is the value of the environment variable
-@code{MITSCHEME_UTABMD_FILE}, or if that isn't defined,
-@file{utabmd.bin}; in these cases the library directories are searched,
-but not the working directory.
+@example
+1 ]=>
+@end example
-@code{-utab} is an alternate name for the @code{-utabmd} option. At
-most one of these options may be given.
+@cindex level number, REPL
+@noindent
+The @samp{1} in the prompt is a @dfn{level number}, which is always a
+positive integer. This number is incremented under certain
+circumstances, the most common being an error. For example, here is
+what you will see if you type @kbd{f o o @key{RET}} after starting
+Scheme:
-@item -fasl @var{filename}
-@findex -fasl
-Specifies that a @dfn{cold load} should be performed, using
-@var{filename} as the initial file to be loaded. If this option isn't
-given, a normal load is performed instead. This option may not be used
-together with the @code{-band} option. This option is useful only for
-maintenance and development of the MIT Scheme runtime system.
-@end table
+@example
+@group
+;Unbound variable: foo
+;To continue, call RESTART with an option number:
+; (RESTART 3) => Specify a value to use instead of foo.
+; (RESTART 2) => Define foo to a given value.
+; (RESTART 1) => Return to read-eval-print level 1.
+
+2 error>
+@end group
+@end example
@noindent
-The following options are runtime options. They are processed after the
-microcode options and after the runtime, Edwin or some other band is
-loaded.
+In this case, the level number has been incremented to @samp{2}, which
+indicates that a new @sc{repl} has been started (also the prompt string
+has been changed to remind you that the @sc{repl} was started because of
+an error). The @samp{2} means that this new @sc{repl} is ``over'' the
+old one. The original @sc{repl} still exists, and is waiting for you to
+return to it, for example, by entering @code{(restart 1)}. Furthermore,
+if an error occurs while you are in this @sc{repl}, yet another
+@sc{repl} will be started, and the level number will be increased to
+@samp{3}. This can continue ad infinitum, but normally it is rare to
+use more than a few levels.
-@table @code
-@item -no-init-file
-@findex -no-init-file
-This option causes Scheme to ignore the @file{~/.scheme.init} or
-@file{scheme.ini} file, normally loaded automatically when Scheme starts
-(if it exists).
+The normal way to get out of an error @sc{repl} and back to the top
+level @sc{repl} is to use the @kbd{C-g} interrupt. This is a
+single-keystroke command executed by holding down the @key{CTRL} key and
+pressing the @key{G} key. @kbd{C-g} always terminates whatever is
+running and returns you to the top level @sc{repl} immediately.
-@item -no-suspend-file
-@findex -no-suspend-file
-Under some circumstances Scheme will write out a file called
-@file{scheme_suspend} in the user's home directory.@footnote{On unix,
-this file is written when Scheme is terminated by the @code{SIGUSR1},
-@code{SIGHUP}, or @code{SIGPWR} signals. On the PC, this file is never
-written.} This file is a ``band'' containing the complete state of the
-Scheme process; restoring this file continues the computation that
-Scheme was performing at the time the file was written.
+Note: The appearance of the @samp{error>} prompt does not mean that
+Scheme is in some weird inconsistent state that you should avoid. It is
+merely a reminder that your program was in error: an illegal operation
+was attempted, but it was detected and avoided. Often the best way to
+find out what is in error is to do some poking around in the error
+@sc{repl}. If you abort out of it, the context of the error will be
+destroyed, and you may not be able to find out what happened.
-If the @code{-no-suspend-file} option is given, Scheme will not write a
-@file{scheme_suspend} file under any circumstances.
+@node Interrupting, Restarting, The Prompt and Level Number, REPL
+@subsection Interrupting
-@item -eval
-@findex -eval
-This option causes Scheme to evaluate the expressions following it on
-the command line, up to (but not including) the next option that starts
-with a hyphen. The expressions are evaluated in the
-@code{user-initial-environment}.
-Unless explicitly handled, errors during evaluation are silently ignored.
+@kindex C-g
+@kindex C-c
+Scheme has several interrupt keys, which vary depending on the
+underlying operating system: under Unix, @kbd{C-g} and @kbd{C-c}; under
+Windows, @kbd{C-b}, @kbd{C-x}, @kbd{C-u}, @kbd{C-g} and @kbd{C-c}; under
+OS/2, @kbd{C-b}, @kbd{C-x}, @kbd{C-u} and @kbd{C-g}. The @kbd{C-g} key
+stops any Scheme evaluation that is running and returns you to the top
+level @sc{repl}. @kbd{C-c} prompts you for another character and
+performs some action based on that character. It is not necessary to
+type @key{RET} after @kbd{C-g} or @kbd{C-c}, nor is it needed after the
+character that @kbd{C-c} will ask you for.
+
+Here are the definitions of the more common interrupt keys; on systems
+that support @kbd{C-c}, type @kbd{C-c ?} for more possibilities.
-@item -load
-@findex -load
-This option causes Scheme to load the files (or lists of files)
-following it on the command line, up to (but not including) the next
-option that starts with a hyphen. The files are loaded in the
-@code{user-initial-environment} using the default syntax table.
-Unless explicitly handled, errors during loading are silently ignored.
-@end table
+@table @asis
+@item @kbd{C-c C-c}
+@itemx @kbd{C-g}
+@kindex C-c C-c
+@kindex C-g
+Abort whatever Scheme evaluation is currently running and return to the
+top-level @sc{repl}. If no evaluation is running, this is equivalent to
+evaluating
-@noindent
-In addition to the above, @code{bchscheme} recognizes the following
-command line options, all of which specify parameters affecting how
-@code{bchscheme} uses disk storage to do garbage collection:
-
-@table @code
-@item -gc-directory @var{directory}
-@findex -gc-directory
-@findex MITSCHEME_GC_DIRECTORY
-Specifies that @var{directory} should be used to create files for
-garbage collection. If the option is not given, the value of
-environment variable @code{MITSCHEME_GC_DIRECTORY} is used instead, and
-if that is not defined, @file{/tmp} is used.
+@findex cmdl-interrupt/abort-top-level
+@example
+(cmdl-interrupt/abort-top-level)
+@end example
-@item -gc-end-position @var{number}
-@findex -gc-end-position
-@findex MITSCHEME_GC_END_POSITION
-It specifies the last byte position in @code{-gc-file} at which this
-invocation of scheme can write. If the option is not given, the value
-of environment variable @code{MITSCHEME_GC_END_POSITION} is used
-instead, and if that is not defined, it is computed from the start
-position (as provided with -gc-start-position) and the heap size. The
-area of the file used (and locked if possible) is the region between
-@code{-gc-start-position} and @code{-gc-end-position}.
+@item @kbd{C-c C-x}
+@itemx @kbd{C-x}
+@kindex C-c C-x
+@kindex C-x
+Abort whatever Scheme evaluation is currently running and return to the
+``current'' @sc{repl}. If no evaluation is running, this is equivalent
+to evaluating
-@item -gc-file @var{filename}
-@itemx -gcfile @var{filename}
-@findex -gc-file
-@findex -gcfile
-@findex MITSCHEME_GC_FILE
-Specifies that @var{filename} should be used for garbage collection. If
-the option is not given, the value of environment variable
-@code{MITSCHEME_GC_FILE} is used, and if this is not defined, a unique
-filename is generated in the directory specified with
-@code{-gc-directory}.
+@findex cmdl-interrupt/abort-nearest
+@example
+(cmdl-interrupt/abort-nearest)
+@end example
-@code{-gcfile} is an alias for @code{-gc-file}. At most one of these
-options should be specified.
+@item @kbd{C-c C-u}
+@itemx @kbd{C-u}
+@kindex C-c C-u
+@kindex C-u
+Abort whatever Scheme evaluation is running and go up one level. If you
+are already at level number 1, the evaluation is aborted, leaving you at
+level 1. If no evaluation is running, this is equivalent to evaluating
-@item -gc-keep
-@findex -gc-keep
-Specifies that the gc file used for garbage collection should not be
-deleted when scheme terminates.
-The gc file is deleted only if the file was created
-by this invocation of scheme, and this option is not set.
+@findex cmdl-interrupt/abort-previous
+@example
+(cmdl-interrupt/abort-previous)
+@end example
-@item -gc-start-position @var{number}
-@findex -gc-start-position
-@findex MITSCHEME_GC_START_POSITION
-It specifies the first byte position in @code{-gc-file} at which this
-invocation of scheme can write. If the option is not given, the value
-of environment variable @code{MITSCHEME_GC_START_POSITION} is used
-instead, and if that is not defined, 0 is used, meaning the beginning of
-the file. The area of the file used (and locked if possible) is the
-region between @code{-gc-start-position} and @code{-gc-end-position}.
+@item @kbd{C-c C-b}
+@itemx @kbd{C-b}
+@kindex C-c C-b
+@kindex C-b
+@cindex breakpoint
+Suspend whatever Scheme evaluation is running and start a
+@dfn{breakpoint} @sc{repl}. The evaluation can be resumed by evaluating
-@item -gc-window-size @var{blocks}
-@findex -gc-window-size
-@findex MITSCHEME_GC_WINDOW_SIZE
-Specifies the size of the windows into new space during garbage
-collection. If this option is not given, the value of environment
-variable @code{MITSCHEME_GC_WINDOW_SIZE} is used instead, and if that is
-not defined, the value 16 is used.
-@end table
+@findex continue
+@example
+(continue)
+@end example
@noindent
-The following command line options are only used by an experimental
-version of @code{bchscheme} that uses Unix System V-style shared memory,
-and only then if the @code{gcdrone} program is installed in the lib
-directory.
+in that @sc{repl} at any time.
-@table @code
-@item -gc-drone @var{program}
-@findex -gc-drone
-@findex MITSCHEME_GC_DRONE
-Specifies that @var{program} should be used as the drone program for
-overlapped I/O during garbage collection. This option is recognized
-only by @code{bchscheme}. If the option is not given, the value of
-environment variable @code{MITSCHEME_GC_DRONE} is used instead, and if
-that is not defined, @file{gcdrone} is used.
+@item @kbd{C-c q}
+@kindex C-c q
+@findex exit
+Similar to typing @code{(exit)} at the @sc{repl}, except that it works
+even if Scheme is running an evaluation, and does not request
+confirmation.
-@item -gc-read-overlap @var{N}
-@findex -gc-read-overlap
-@findex MITSCHEME_GC_READ_OVERLAP
-Specifies that scheme should delegate at most @var{N} simultaneous disk
-read operations during garbage collection. This option is recognized
-only by @code{bchscheme}. If the option is not given, the value of
-environment variable @code{MITSCHEME_GC_READ_OVERLAP} is used instead,
-and if that is not defined, 0 is used, disabling overlapped reads.
+@item @kbd{C-c z}
+@kindex C-c z
+@findex quit
+Similar to typing @code{(quit)} at the @sc{repl}, except that it works
+even if Scheme is running an evaluation.
-@item -gc-write-overlap @var{N}
-@findex -gc-write-overlap
-@findex MITSCHEME_GC_WRITE_OVERLAP
-Specifies that scheme should delegate at most @var{N} simultaneous disk
-write operations during garbage collection. This option is recognized
-only by @code{bchscheme}. If the option is not given, the value of
-environment variable @code{MITSCHEME_GC_WRITE_OVERLAP} is used instead,
-and if that is not defined, 0 is used, disabling overlapped writes.
-@end table
+@item @kbd{C-c i}
+@kindex C-c i
+Ignore the interrupt. Type this if you made a mistake and didn't
+really mean to type @kbd{C-c}.
-@node Environment Variables, Starting Scheme from Windows 3.1/NT, Command-Line Options, Running Scheme
-@section Environment Variables
+@item @kbd{C-c ?}
+@kindex C-c ?
+Print help information. This will describe any other options not
+documented here.
+@end table
-There are many environment variables that Scheme (and Edwin, etc.) look
-for. Environment variables that affect the microcode must be defined
-before you start Scheme, but others can be defined or overwritten within
-Scheme by using the @code{set-environment-variable!} procedure, e.g.@:
+@node Restarting, The Current REPL Environment, Interrupting, REPL
+@subsection Restarting
-@example
-(set-environment-variable! "EDWIN_FOREGROUND" "32")
-@end example
+Another way to exit a @sc{repl} is to use the @code{restart} procedure:
-The rest of this section is a summary of the environment variables that
-are specific to MIT Scheme. The environment variables are organized
-according to the parts of MIT Scheme that they affect.
+@deffn {procedure+} restart [k]
+@cindex REPL, restarting from
+This procedure selects and invokes a @dfn{restart method}. The list of
+restart methods is different for each @sc{repl}; in the case of an error
+@sc{repl}, this list is printed when the @sc{repl} is started:
-@menu
-* Microcode Environment Variables::
-* Bchscheme Environment Variables::
-* PC Environment Variables::
-* Runtime Environment Variables::
-* Edwin Environment Variables::
-@end menu
+@example
+@group
+;Unbound variable: foo
+;To continue, call RESTART with an option number:
+; (RESTART 3) => Specify a value to use instead of foo.
+; (RESTART 2) => Define foo to a given value.
+; (RESTART 1) => Return to read-eval-print level 1.
-@node Microcode Environment Variables, Bchscheme Environment Variables, Environment Variables, Environment Variables
-@subsection Environment Variables Affecting the Microcode
+2 error>
+@end group
+@end example
-These environment variables are referred to by the microcode (the
-executable C programs called @file{scheme} and @file{bchscheme}).
+If the @var{k} argument is given, it must be a positive integer index
+into the list (in the example it must be between one and three
+inclusive). The integer @var{k} selects an item from the list and
+invokes it. If @var{k} is not given, @code{restart} prints the list and
+prompts for the integer index:
-@table @asis
-@item @code{MITSCHEME_BAND} (default: @file{runtime.com} on the library path)
-@findex MITSCHEME_BAND
-The initial band to be loaded. Overridden by @code{-band},
-@code{-compiler}, or @code{-edwin}.
+@example
+@group
+2 error> (restart)
+;Choose an option by number:
+; 3: Specify a value to use instead of foo.
+; 2: Define foo to a given value.
+; 1: Return to read-eval-print level 1.
-@item @code{MITSCHEME_COMPILER_BAND} (default: @file{compiler.com} on the library path)
-@findex MITSCHEME_COMPILER_BAND
-The initial band to be loaded if the @code{-compiler} option is given.
-Overridden by @code{-band}.
+Option number:
+@end group
+@end example
-@item @code{MITSCHEME_EDWIN_BAND} (default: @file{edwin.com} on the library path)
-@findex MITSCHEME_EDWIN_BAND
-The initial band to be loaded if the @code{-edwin} option is given.
-Overridden by @code{-band}.
+The simplest restart methods just perform their actions. For example:
-@item @code{MITSCHEME_LARGE_CONSTANT} (default: @samp{1000})
-@findex MITSCHEME_LARGE_CONSTANT
-The size of constant space, in 1024-word blocks, if the @code{-large},
-@code{-compiler}, or @code{-edwin} options are given. Overridden by
-@code{-constant}. Note: default is somewhat larger on RISC machines.
+@example
+@group
+2 error> (restart 1)
+;Abort!
-@item @code{MITSCHEME_LARGE_HEAP} (default: @samp{1000})
-@findex MITSCHEME_LARGE_HEAP
-The size of the heap, in 1024-word blocks, if the @code{-large},
-@code{-compiler}, or @code{-edwin} options are given. Overridden by
-@code{-heap}.
+1 ]=>
+@end group
+@end example
-@item @code{MITSCHEME_LARGE_STACK} (default: @samp{100})
-@findex MITSCHEME_LARGE_STACK
-The size of the stack, in 1024-word blocks, if the @code{-large},
-@code{-compiler}, or @code{-edwin} options are given. Overridden by
-@code{-stack}.
+Other methods will prompt for more input before continuing:
-@item @code{MITSCHEME_LIBRARY_PATH}
-@findex MITSCHEME_LIBRARY_PATH
-A list of directories. These directories are searched,
-left to right, to find bands and various other files.
-On Unix systems the list is colon separated, with the default
-@file{/usr/local/lib/mit-scheme}.
-On PC systems the list is semi-colon separated with the default
-@file{c:\scheme\lib}.
+@example
+@group
+2 error> (restart)
+;Choose an option by number:
+; 3: Specify a value to use instead of foo.
+; 2: Define foo to a given value.
+; 1: Return to read-eval-print level 1.
-@item @code{MITSCHEME_INF_DIRECTORY}
-Directory containing the debugging information files for the system. It
-should contain subdirectories corresponding to the subdirectories in the
-source tree. For example, if its value is @file{f:\random}, then
-runtime system debugging files will be expected in
-@file{f:\random\runtime}, while edwin debugging files will be expected
-in @file{f:\random\edwin}.
+Option number: 3
-@item @code{MITSCHEME_SMALL_CONSTANT} (default: @samp{400})
-@findex MITSCHEME_SMALL_CONSTANT
-The size of constant space, in 1024-word blocks, if the size options are
-not given. Overridden by @code{-constant}, @code{-large},
-@code{-compiler}, or @code{-edwin}. Note: default is somewhat larger on
-RISC machines.
+Value to use instead of foo: '(a b)
+;Value: (a b)
-@item @code{MITSCHEME_SMALL_HEAP} (default: @samp{250})
-@findex MITSCHEME_SMALL_HEAP
-The size of the heap, in 1024-word blocks, if the size options are not
-given. Overridden by @code{-heap}, @code{-large}, @code{-compiler}, or
-@code{-edwin}.
+1 ]=>
+@end group
+@end example
+@end deffn
-@item @code{MITSCHEME_SMALL_STACK} (default: @samp{100})
-@findex MITSCHEME_SMALL_STACK
-The size of the stack, in 1024-word blocks, if the size options are not
-given. Overridden by @code{-stack}, @code{-large}, @code{-compiler}, or
-@code{-edwin}.
+@node The Current REPL Environment, , Restarting, REPL
+@subsection The Current REPL Environment
-@item @code{MITSCHEME_UTABMD_FILE} (default: @file{utabmd.bin} in the library path)
-@findex MITSCHEME_UTABMD_FILE
-The file containing the microcode tables. Overridden by @code{-utabmd}
-and @code{-utab}. It is only necessary when re-building
-@file{runtime.com}.
-@end table
+@cindex current REPL environment
+@findex user-initial-environment
+@findex system-global-environment
+Every @sc{repl} has a @dfn{current environment}, which is the place
+where expressions are evaluated and definitions are stored. When Scheme
+is started, this environment is the value of the variable
+@code{user-initial-environment}. There are a number of other
+environments in the system, for example
+@code{system-global-environment}, where the runtime system's bindings
+are stored.
-@node Bchscheme Environment Variables, PC Environment Variables, Microcode Environment Variables, Environment Variables
-@subsection Environment Variables for Bchscheme
+You can get the current @sc{repl} environment by evaluating
-These environment variables are referred to by @file{bchscheme}
-(@emph{not} by @file{scheme}).
+@findex nearest-repl/environment
+@example
+(nearest-repl/environment)
+@end example
-@table @asis
-@item @code{MITSCHEME_GC_DIRECTORY} (default: @file{/tmp})
-@findex MITSCHEME_GC_DIRECTORY
-The directory where to write gc files. Overridden by @code{-gc-directory}.
+There are several other ways to obtain environments. For example, if
+you have a procedure object, you can get a pointer to the environment in
+which it was closed by evaluating
-@item @code{MITSCHEME_GC_END_POSITION} (default: start-position + heap-size)
-@findex MITSCHEME_GC_END_POSITION
-The last position in the gc file to use. Overridden by
-@code{-gc-end-position}.
+@findex procedure-environment
+@example
+(procedure-environment @var{procedure})
+@end example
-@item @code{MITSCHEME_GC_FILE} (default: @file{GCXXXXXX})
-@findex MITSCHEME_GC_FILE
-The name of the file to use for garbage collection. If it ends in 6 Xs,
-the Xs are replaced by a letter and process id of the scheme process,
-thus generating a unique name. Overridden by @code{-gc-file}.
+Your programs create new environments whenever a procedure is called.
-@item @code{MITSCHEME_GC_START_POSITION} (default: 0)
-@findex MITSCHEME_GC_START_POSITION
-The first position in the gc file to use. Overridden by
-@code{-gc-start-position}.
+Here is the procedure that changes the @sc{repl}'s environment:
-@item @code{MITSCHEME_GC_WINDOW_SIZE} (default: 16)
-@findex MITSCHEME_GC_WINDOW_SIZE
-The size in blocks of windows into new space (in the gc file).
-Overridden by @code{-gc-window-size}.
-@end table
+@deffn {procedure+} ge environment
+Changes the current @sc{repl} environment to be @var{environment}
+(@code{ge} stands for ``Goto Environment''). @var{Environment} is
+allowed to be a procedure as well as an environment object. If it is a
+procedure, then the closing environment of that procedure is used in its
+place.
+@end deffn
-@noindent
-The following environment variables are only used by an experimental
-version of Bchscheme that uses Unix System V-style shared memory, and
-only then if the @code{gcdrone} program is installed:
+@deffn {procedure+} pe
+This procedure is useful for finding out which environment you are in
+(@code{pe} stands for ``Print Environment''). If the current @sc{repl}
+environment belongs to a package, then @code{pe} returns the package
+name (a list of symbols). If the current @sc{repl} environment does not
+belong to a package then the environment is returned.
+@end deffn
-@table @asis
-@item @code{MITSCHEME_GC_DRONE} (default: @file{gcdrone})
-@findex MITSCHEME_GC_DRONE
-The program to use as the I/O drone during garbage collection.
-Overridden by @code{-gc-drone}.
+@deffn {procedure+} gst syntax-table
+In addition to the current environment, each @sc{repl} maintains a
+current @dfn{syntax table}. The current syntax table tells the
+@sc{repl} which keywords are used to identify special forms (e.g.@:
+@code{if}, @code{lambda}). If you write macros, you may want to
+make your own syntax table, in which case it is useful to be able to
+make that syntax table be the current one; @code{gst} allows you to do
+that.
+@end deffn
-@item @code{MITSCHEME_GC_READ_OVERLAP} (default: 0)
-@findex MITSCHEME_GC_READ_OVERLAP
-The maximum number of simultaneous read operations. Overridden by
-@code{-gc-read-overlap}.
+@node Loading Files, World Images, REPL, Using Scheme
+@section Loading Files
-@item @code{MITSCHEME_GC_WRITE_OVERLAP} (default: 0)
-@findex MITSCHEME_GC_WRITE_OVERLAP
-The maximum number of simultaneous write operations. Overridden by
-@code{-gc-write-overlap}.
-@end table
+To load files of Scheme code, use the procedure @code{load}:
-@node PC Environment Variables, Runtime Environment Variables, Bchscheme Environment Variables, Environment Variables
-@subsection Environment Variables for the PC
+@deffn {procedure} load filename [environment [syntax-table]]
+@var{Filename} may be a string naming a file, or a list of strings
+naming multiple files. @var{Environment}, if given, is the environment to
+evaluate the file in; if not given the current @sc{repl} environment is
+used. Likewise @var{syntax-table} is the syntax table to use.
-These environment variables are referred to by the Windows, Windows NT,
-and DOS versions of MIT Scheme.
-
-@table @asis
-@item @code{MITSCHEME_DPMI_EXT_KBD} (default: @samp{false})
-@findex MITSCHEME_DPMI_EXT_KBD
-DOS only.
-Boolean option specifying whether Scheme inserts its own keyboard handling
-routine when running under DPMI (DOS Protected Mode Interface) or Windows.
-
-@item @code{MITSCHEME_X32_EXT_KBD} (default: @samp{false})
-@findex MITSCHEME_X32_EXT_KBD
-DOS only.
-Boolean option specifying whether Scheme inserts its own keyboard handling
-routine when @emph{not} running under DPMI or Windows.
-
-@item @code{MITSCHEME_TRAP_ALT_TAB} (default: @samp{false})
-@itemx @code{MITSCHEME_TRAP_ALT_ESCAPE} (default: @samp{false})
-@findex MITSCHEME_TRAP_ALT_TAB
-@findex MITSCHEME_TRAP_ALT_ESCAPE
-Windows and Windows NT only.
-Boolean option specifying the handling of system command accelerators.
-These options do not actually work.
-
-@item @code{MITSCHEME_FONT} (default: determined by operating system)
-@findex MITSCHEME_FONT
-@cindex fonts
-Windows and Windows NT only.
-A string specifying a font name and characteristics, for example,
-@samp{Courier New 16 bold}.
-Allowed characteristics are @var{integer}, specifiying the font size,
-and the following style modifiers: @samp{bold}, @samp{italic},
-@samp{regular}, @samp{underline} and @samp{strikeout}.
-Note that the size is the total height in pixels, and @strong{not} the
-point size.
-Thus the fonts tend to be 20-50% smaller than you might expect.
-You should specifiy only fixed-width fonts as variable width fonts are
-not drawn correctly.
-
-Once in Edwin, the font can be changed with the @samp{set-font} and
-@samp{set-default-font} commands.
-
-@item @code{MITSCHEME_GEOMETRY} (default: @samp{-1,-1,-1,-1})
-@findex MITSCHEME_GEOMETRY
-@cindex window position
-Windows and Windows NT only. Four integers separated by
-commas or spaces that specify the placement and size of the MIT Scheme
-window as a @var{left,top,width,height} quadruple. The units are screen
-pixels, and @samp{-1} means allow the system to choose this parameter.
-E.g.@: @samp{-1,-1,500,300} places a 500 by 300 pixel window at some
-system determined position on the screen. The width and height include
-the window border and title.
+@findex pathname-type
+@code{load} determines whether the file to be loaded is binary or source
+code, and performs the appropriate action. By convention, files of
+source code have a pathname type of @code{"scm"}, and files of binary
+SCode have pathname type @code{"bin"}. Native-code binaries have
+pathname type @code{"com"}. (See the description of
+@code{pathname-type} in the reference manual.)
+@end deffn
-@item @code{MITSCHEME_FOREGROUND} (default: according to desktop color scheme)
-@findex MITSCHEME_FOREGROUND
-@cindex window color
-Windows and Windows NT only. An value specifying the window
-text color. The color is specified as hex blue, green and red values
-(@emph{not} RGB): e.g.@: @code{0xff0000} for blue.
+@defvr {variable+} load-noisily?
+If @code{load-noisily?} is set to @code{#t}, @code{load} will print the
+value of each expression in the file as it is evaluated. Otherwise,
+nothing is printed except for the value of the last expression in the
+file. (Note: the noisy loading feature is implemented for source-code
+files only.)
+@end defvr
-@item @code{MITSCHEME_BACKGROUND} (default: according to desktop color scheme)
-@findex MITSCHEME_BACKGROUND
-Windows and Windows NT only. A value specifying the window
-background color. See @code{MITSCHEME_FOREGROUND}.
-@end table
+@defvr {variable+} load/default-types
+When load is given a pathname without a type, it uses the value of this
+variable to determine what pathname types to look for and how to load
+the file. @code{load/default-types} is a list of associations that maps
+pathname types (strings) to loader procedures. @code{load} tries the
+pathname types in the order that they appear in the list. The initial
+value of this variable has pathname types in this order:
-@node Runtime Environment Variables, Edwin Environment Variables, PC Environment Variables, Environment Variables
-@subsection Environment Variables Affecting the Runtime System
+@example
+"com" "so" "sl" "bin" "scm"
+@end example
-These environment variables are referred to by the runtime system.
+This means that, for example, @code{(load "foo")} will try to load
+@file{foo.com} first, and @file{foo.scm} only after looking for and
+failing to find the other pathname types.
+@end defvr
-@table @asis
-@item @code{HOME}
-@findex HOME
-Directory where to look for init files. E.g.@: @samp{c:\users\joe} or
-@samp{/homes/joe}.
+@cindex working directory
+@findex pwd
+@findex cd
+All pathnames are interpreted relative to a working directory, which is
+initialized when Scheme is started. The working directory can be
+obtained by calling the procedure @code{pwd} or modified by calling the
+procedure @code{cd}; see the reference manual for details. Files may be
+loaded when Scheme first starts; see the @code{-load} command-line
+option for details.
-@item @code{TEMP}, @code{TMP}
-@findex TMP
-@findex TEMP
-Directory for various temporary files. @code{TEMP} is given preference
-to @code{TMP}.
-@end table
+@node World Images, Garbage Collection, Loading Files, Using Scheme
+@section World Images
-@node Edwin Environment Variables, , Runtime Environment Variables, Environment Variables
-@subsection Environment Variables Affecting Edwin
+@cindex world image
+@cindex band
+A @dfn{world image}, also called a @dfn{band}, is a file that contains a
+complete Scheme system, perhaps additionally including user application
+code. Scheme provides a method for saving and restoring world images.
+The method writes a file containing all of the Scheme code in the
+running process. The file @file{runtime.com} that is loaded by the
+microcode is just such a band. To make your own band, use the procedure
+@code{disk-save}.
-These environment variables are referred to by Edwin.
+@deffn {procedure+} disk-save filename [identify]
+Causes a band to be written to the file specified by @var{filename}.
+The optional argument @var{identify} controls what happens when that
+band is restored, as follows:
@table @asis
-@item @code{EDWIN_BINARY_DIRECTORY} (default: @file{edwin/autoload} on the library path)
-@findex EDWIN_BINARY_DIRECTORY
-Directory where edwin expects to find files providing autoloaded
-facilities.
-
-@item @code{EDWIN_INFO_DIRECTORY} (default: @file{edwin/info} on the library path)
-@findex EDWIN_INFO_DIRECTORY
-Directory where edwin expects to find files for the `info' documentation
-subsystem.
-
-@item @code{EDWIN_ETC_DIRECTORY} (default: @file{edwin/etc} on the library path)
-@findex EDWIN_ETC_DIRECTORY
-Directory where edwin expects to find utility programs and documentation
-strings.
-
-@item @code{EDWIN_FOREGROUND} (default: none (white))
-@findex EDWIN_FOREGROUND
-DOS version only.
-ANSI foreground color specifier. Must be a two-digit sequence in the range
-30-37. E.g.@: 32 (green).
+@item not specified
+Start up in the top-level @sc{repl}, identifying the world in the normal
+way.
-@item @code{EDWIN_BACKGROUND} (default: none (black))
-@findex EDWIN_BACKGROUND
-DOS version only.
-ANSI background color specifier. Must be a two-digit sequence in the range
-40-47. E.g.@: 40 (black).
+@item a string
+Do the same thing except print that string instead of @samp{Scheme} when
+restarting.
-@item @code{TERM}
-@findex TERM
-Terminal type. For DOS, should be @samp{ansi.sys} or
-@samp{ibm_pc_bios}. For Windows and Windows NT it should be
-@samp{ansi.sys}, which is the default if not set.
+@item the constant @code{#t}
+Restart exactly where you were when the call to @code{disk-save} was
+performed. This is especially useful for saving your state when an
+error has occurred and you are not in the top-level @sc{repl}.
-@item @code{LINES} (default: auto-sense)
-@findex LINES
-Unix only.
-Number of text lines on the screen, depending on the terminal type.
+@item the constant @code{#f}
+Just like @code{#t}, except that the runtime system will not perform
+normal restart initializations; in particular, it will not load your
+init file.
+@end table
+@end deffn
-@item @code{MITSCHEME_LINES} (default: auto-sense or 25)
-@findex MITSCHEME_LINES
-DOS only. Number of text lines on the screen, depending on the video
-adapter and support software. E.g.@: 43.
+@findex disk-restore
+To restore a saved band, give the @samp{-band} option when starting
+Scheme. Alternatively, evaluate @code{(disk-restore @var{filename})},
+which will destroy the current world, replacing it with the saved world.
+The argument to @code{disk-restore} may be omitted, in which case it
+defaults to the filename from which the current world was last restored.
-@item @code{COLUMNS} (default: auto-sense)
-@findex COLUMNS
-Unix only.
-Number of text columns on the screen, depending on the terminal type (Unix) or
-video adapter and support software (DOS). E.g.@: 132.
-
-@item @code{MITSCHEME_COLUMNS} (default: auto-sense, or 80)
-@findex MITSCHEME_COLUMNS
-DOS only. Number of text columns on the screen, depending on the video
-adapter and support software. E.g.@: 132.
-@end table
+Note: with the C back end, @code{disk-save} is not very useful. The
+reason is that compiled procedures are compiled C code that has been
+dynamically linked in, and @code{disk-save} does not save any C
+procedures. Your system is a C back end system if the following
+expression does not evaluate to @code{#f}:
-@node Starting Scheme from Windows 3.1/NT, Leaving Scheme, Environment Variables, Running Scheme
-@section Starting Scheme from Windows 3.1/NT
+@example
+(system-library-directory-pathname "shared")
+@end example
-There are two distinct versions of MIT Scheme that run on IBM
-`compatible' PCs: the DOS version is a character-mode only
-implementation, which can also run under Windows 3.1 as a DOS application.
-The Windows version runs as a graphics-based application under
-Windows 3.1 or Windows NT.
-The DOS version does not run under Windows NT.
+Note: when restoring a saved band, the Scheme executable must be
+configured with a large enough constant space and heap to hold the
+band's contents. If you attempt to restore a band using the
+@samp{-band} option, and the band is too large, Scheme will write an
+error message that tells you the appropriate command-line options needed
+to load that band. If you attempt restore a too-large band using
+@code{disk-restore}, Scheme will signal an error, but will not provide
+the configuration information. In general, the configuration that was
+used to save a band is sufficiently large to restore it.
+@c
+@c @findex dump-world
+@c Another method for saving the world is the @code{dump-world} procedure,
+@c which accepts the same arguments as @code{disk-save} and works in much
+@c the same way. However, rather than dumping a band, @code{dump-world}
+@c saves an executable image, which is started just like any other program.
+@c This has the advantage of being considerably faster to start on some
+@c systems, but the image file is typically much larger than the
+@c corresponding band. However, @code{dump-world} is only supported for a
+@c few operating systems, and is not built into the distributed executable
+@c files --- if you wish to use @code{dump-world}, you must build your own
+@c executable file from the source code.
+@c Note that @code{dump-world} is unlikely to work with this release as MIT
+@c Scheme now uses shared libraries.
+
+@node Garbage Collection, , World Images, Using Scheme
+@section Garbage Collection
+
+This section describes procedures that control garbage collection.
+@xref{Memory Usage}, for a discussion of how MIT Scheme uses memory.
-Under Windows 3.1, Scheme must be run from the Program Manager or
-the File Manager. Scheme cannot be run from the command line, because
-only DOS programs can be run from the command line.
-(This is the case even with WXSERVER as it appears not to work with
-win32s-based programs).
-Windows NT overcomes this restriction, but it is still useful to know
-how to run Scheme from the Program Manager.
+@deffn {procedure+} gc-flip [safety-margin]
+Forces a garbage collection to occur. Returns the number of words of
+storage available after collection, an exact non-negative integer.
-Once an icon is set up to run Scheme with some particular command line
-options, Scheme is run by double-clicking that icon.
-The rest of this section gives some tips on how to set up icons in the
-Program Manager that run Scheme. If you are unfamiliar with this
-concept you should read about it under the help topic of the Program
-Manager.
+@var{Safety-margin} determines the number of words of storage available
+for system tasks in-between detecting the need for a garbage collection
+and entering the garbage collector proper. (An example of such a system
+task is changing the run-light to show ``gc'' when scheme is running under
+Emacs.) Note well: you should not specify @var{safety-margin} unless
+you know what you are doing. If you specify a value that is too small,
+you can put Scheme in an unusable state.
+@end deffn
-Under Windows NT program manager groups can be @emph{common} or
-@emph{personal}. When setting up icons in a common group it is
-important to make the icons independent of the vagaries of the
-environment of the user who is running them. It is often worthwhile
-doing this under Windows 3.1 and for personal groups too:
+@deffn {procedure+} purify object [pure-space? [queue?]]
+Moves @var{object} from the heap into constant space. Has no effect if
+@var{object} is already stored in constant space. @var{Object} is moved
+in its entirety; if it is a compound object such as a list, a vector, or
+a record, then all of the objects that @var{object} points to are also
+moved to constant space.
+
+There are three important effects associated with moving an object to
+constant space. The first and most important effect is that the object
+takes up half as much space, because when in the heap, the system must
+reserve space for the object in both the active heap and the inactive
+heap; if the object is in constant space it is not copied and therefore
+no extra space is required. The second effect is that garbage
+collection will take less time, because @var{object} will no longer be
+copied. The third effect is that the space allocated to @var{object} is
+permanently allocated, because constant space is never cleaned; any
+unreachable objects in constant space remain there until the Scheme
+process is terminated.
+
+The optional argument @var{pure-space?} is obsolete; it defaults to
+@code{#t} and when explicitly specified should always be @code{#t}.
+
+The optional argument @var{queue?} specifies whether @var{object} should
+be moved to constant space immediately, or should be queued to be moved
+during the next garbage collection. This argument defaults to
+@code{#t}. The reason for queuing these requests is that moving an
+object to constant space requires a garbage collection to occur, a
+relatively slow process. By queuing the requests, this overhead is
+avoided, because moving an object during a garbage collection has no
+effect on the time of the garbage collection. Furthermore, if several
+requests are queued, they can all be processed together in one garbage
+collection, while if done separately they would each require their own
+garbage collection.
+@end deffn
-@itemize @bullet
-@item
-Give the icon an accurate @var{Description}.
+@deffn {procedure+} flush-purification-queue!
+Forces any pending queued purification requests to be processed. This
+examines the @code{purify} queue, and if it contains any requests,
+forces a garbage collection to process them. If the queue is empty,
+does nothing.
+@end deffn
-@item
-Include absolute pathnames to @code{scheme.exe} and @code{bchscheme.exe}
-in the icon @var{Command line} if these executables are not in a
-directory on the default @code{PATH}.
+@deffn {procedure+} print-gc-statistics
+Prints out information about memory allocation and the garbage
+collector. The information is printed to the current output port.
+Shows how much space is ``in use'' and how much is ``free'', separately
+for the heap and constant space. The amounts are shown in words, and
+also in 1024-word blocks; the block figures make it convenient to use
+these numbers to adjust the arguments given to the @samp{-heap} and
+@samp{-constant} command-line options. Following the allocation
+figures, information about the most recent 8 garbage collections is
+shown, in the same format as a @sc{gc} notification.
+
+Note that these numbers are accurate at the time that
+@code{print-gc-statistics} is called. In the case of the heap, the ``in
+use'' figure shows how much memory has been used since the last garbage
+collection, and includes all live objects as well as any uncollected
+garbage that has accumulated since then. The only accurate way to
+determine the size of live storage is to subtract the value of
+@samp{(gc-flip)} from the size of the heap. The size of the heap can be
+determined by adding the ``in use'' and ``free'' figures reported by
+@code{print-gc-statistics}.
-@item
-Set the icon's @var{Working Directory} to: @code{%HOMEPATH%}
+@example
+(print-gc-statistics)
+constant in use: 534121 words = 521 blocks + 617 words
+constant free: 128 words = 0 blocks + 128 words
+heap in use: 34845 words = 34 blocks + 29 words
+heap free: 205530 words = 200 blocks + 730 words
+GC #1: took: 0.13 (81%) CPU time, 0.15 (1%) real time; free: 207210
+;No value
+@end example
+@end deffn
-@item
-There are several icons available --- choose one that best represents
-the options given on the command line.
+@deffn {procedure+} set-gc-notification! [on?]
+Controls whether the user is notified of garbage collections. If
+@var{on?} is given and @code{#f}, notification is enabled; otherwise
+notification is disabled. By default, notification is disabled.
-@item
-Specifying a band that contains Edwin is not sufficient to invoke the
-editor. You also have to put
+The notification appears as a single line like the following, showing
+how many garbage collections have occurred, the time taken to perform the
+garbage collection and the free storage remaining (in words) after
+collection.
@example
--eval (edit)
+GC #5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346
@end example
-at the end of the command line.
-@end itemize
+To operate comfortably, the amount of free storage after garbage
+collection should be a substantial proportion of the heap size. If the
+percentage CPU time is consistently high (over 20%), you should consider
+running with a larger heap. A rough rule of thumb to halve the @sc{gc}
+overhead is to take the amount of free storage, divide by 1000, and add
+this figure to the current value used for the @samp{-heap} command line
+option. Unfortunately there is no way to adjust the heap size without
+restarting Scheme.
+@end deffn
-@node Leaving Scheme, , Starting Scheme from Windows 3.1/NT, Running Scheme
-@section Leaving Scheme
+@deffn {procedure+} toggle-gc-notification!
+Toggles @sc{gc} notification on and off. If @sc{gc} notification is
+turned on, turns it off; otherwise turns it on.
+@end deffn
-There are two ways you can leave Scheme. The first is to evaluate
+@node Compiling Programs, Debugging, Using Scheme, Top
+@chapter Compiling Programs
-@findex exit
-@lisp
-(exit)
-@end lisp
+Note: the procedures described in this section are only available when
+the compiler is loaded, as in the @file{compiler.com} world image.
+Furthermore, @code{cf} is only available on machines that support
+native-code compilation.
-@noindent
-which will halt the Scheme system, after first requesting confirmation.
-Any information that was in the environment is lost, so this should not
-be done lightly.
+@menu
+* Compilation Procedures::
+* Declarations::
+* Efficiency Tips::
+@end menu
-The second way to leave Scheme is to suspend it; when this is done you
-may later restart where you left off. Unfortunately this is not
-possible in all operating systems --- currently it works only on unix
-versions that support job control (i.e.@: all of the unix versions for
-which we distribute Scheme), but not on PCs.
+@node Compilation Procedures, Declarations, Compiling Programs, Compiling Programs
+@section Compilation Procedures
-Scheme is suspended by evaluating
+@deffn {procedure+} cf filename [destination]
+This is the program that transforms a source-code file into native-code
+binary form. If @var{destination} is not given, as in
-@findex quit
-@lisp
-(quit)
-@end lisp
+@example
+(cf "foo")
+@end example
@noindent
-If your system supports suspension, this will cause Scheme to stop, and
-you will be returned to the operating system's command interpreter.
-Scheme remains stopped, and can be continued using the job-control
-commands of your command interpreter. If your system doesn't support
-suspension, this procedure does nothing. (Calling the @code{quit}
-procedure is analogous to typing Control-@code{Z}, but it allows Scheme
-to respond by typing a prompt when it is unsuspended.)
-
-@node REPL, Debugging, Running Scheme, Top
-@chapter The Read-Eval-Print Loop
-
-@cindex REPL
-When you first start up Scheme from the command line (i.e not under
-Edwin), you will be typing at a program called the @dfn{Read-Eval-Print
-Loop} (abbreviated @dfn{REPL}). It displays a prompt at the left hand
-side of the screen whenever it is waiting for input. You then type an
-expression (terminating it with @key{RET}). Scheme evaluates the
-expression, prints the result, and gives you another prompt.
+@code{cf} compiles the file @file{foo.scm}, producing the file
+@file{foo.com} (incidentally it will also produce @file{foo.bin},
+@file{foo.bci}, and possibly @file{foo.ext}). If you later evaluate
-@menu
-* The Prompt and Level Number::
-* Interrupting::
-* Restarting::
-* The Current REPL Environment::
-@end menu
+@example
+(load "foo")
+@end example
-@node The Prompt and Level Number, Interrupting, REPL, REPL
-@section The Prompt and Level Number
+@noindent
+@file{foo.com} will be loaded rather than @file{foo.scm}.
-@cindex prompt, REPL
-The @sc{repl} @dfn{prompt} normally has the form
+If @var{destination} is given, it says where the output files should go.
+If this argument is a directory, they go in that directory, e.g.:
@example
-1 ]=>
+(cf "foo" "../bar/")
@end example
-@cindex level number, REPL
@noindent
-The @samp{1} in the prompt is a @dfn{level number}, which is always a
-positive integer. This number is incremented under certain
-circumstances, the most common being an error. For example, here is
-what you will see if you type @kbd{f o o @key{RET}} after starting
-Scheme:
+will take @file{foo.scm} and generate the file @file{../bar/foo.com}.
+If @var{destination} is not a directory, it is the root name of the
+output:
@example
-;Unbound variable: foo
-;To continue, call RESTART with an option number:
-; (RESTART 3) => Specify a value to use instead of foo.
-; (RESTART 2) => Define foo to a given value.
-; (RESTART 1) => Return to read-eval-print level 1.
-
-2 error>
+(cf "foo" "bar")
@end example
@noindent
-In this case, the level number has been incremented to @samp{2}, which
-indicates that a new @sc{repl} has been started (also the prompt string
-has been changed to remind you that the @sc{repl} was started because of
-an error). The @samp{2} means that this new @sc{repl} is ``over'' the
-old one. The original @sc{repl} still exists, and is waiting for you to
-return to it, for example, by entering @code{(restart 1)}. Furthermore,
-if an error occurs while you are in this @sc{repl}, yet another
-@sc{repl} will be started, and the level number will be increased to
-@samp{3}. This can continue ad infinitum, but normally it is rare to
-use more than a few levels.
-
-The normal way to get out of an error @sc{repl} and back to the top
-level @sc{repl} is to use the @kbd{C-g} interrupt. This is a
-single-keystroke command executed by holding down the @key{CTRL} key and
-pressing the @key{G} key. @kbd{C-g} always terminates whatever is
-running and returns you to the top level @sc{repl} immediately.
-
-Note: The appearance of the @samp{error>} prompt does not mean that
-Scheme is in some weird inconsistent state that you should avoid. It is
-merely a reminder that your program was in error: an illegal operation
-was attempted, but it was detected and avoided. Often the best way to
-find out what is in error is to do some poking around in the error
-@sc{repl}. If you abort out of it, the context of the error will be
-destroyed, and you may not be able to find out what happened.
-
-@node Interrupting, Restarting, The Prompt and Level Number, REPL
-@section Interrupting
-
-@kindex C-g
-@kindex C-c
-Scheme has two interrupt keys under unix: @kbd{C-g} and @kbd{C-c}.
-Other systems, like the PC, may have more than two.
-The PC version has @kbd{C-b}, @kbd{C-x}, and @kbd{C-u} as well as
-@kbd{C-g} and @kbd{C-c}.
-The @kbd{C-g} key stops any Scheme
-evaluation that is running and returns you to the top level @sc{repl}.
-@kbd{C-c} prompts you for another character and performs some action
-based on that character. It is not necessary to type @key{RET} after
-@kbd{C-g} or @kbd{C-c}, nor is it needed after the character that
-@kbd{C-c} will ask you for.
-
-Here are the more common options for @kbd{C-c}.
-
-@table @kbd
-@item C-c i
-@kindex C-c i
-Ignore the interrupt. Type this if you made a mistake and didn't
-really mean to type @kbd{C-c}.
-
-@item C-c ?
-@kindex C-c ?
-Print help information. This will describe any other options not
-documented here.
-
-@item C-c q
-@kindex C-c q
-@findex exit
-Similar to typing @code{(exit)} at the @sc{repl}, except that it works
-even if Scheme is running an evaluation, and does not request
-confirmation.
+takes @file{foo.scm} and generates @file{bar.com}.
+@end deffn
-@item C-c z
-@kindex C-c z
-@findex quit
-Similar to typing @code{(quit)} at the @sc{repl}, except that it works
-even if Scheme is running an evaluation.
+About the @file{.bci} files: these files contain the debugging
+information that Scheme uses when you call @code{debug} to examine
+compiled code. When you load a @file{.com} file, Scheme remembers where
+it was loaded from, and when the debugger (or @code{pp}) looks at the
+compiled code from that file, it attempts to find the @file{.bci} file
+in the same directory from which the @file{.com} file was loaded. Thus
+it is a good idea to leave these files together.
-@item C-c C-c
-@kindex C-c C-c
-Identical to typing @kbd{C-g}. If no evaluation is running, this is
-equivalent to evaluating
+@file{.bci} files are stored in a compressed format.
+The debugger has to uncompress the files when it looks at them,
+and on a slow machine this can take a noticeable time.
+The system takes steps to reduce the impact of this behaviour:
+debugging information is cached in memory,
+and uncompressed versions of @file{.bci} files are kept around.
+The default behavior is that a temporary file is created and the
+@file{.bci} file is uncompressed into it. The temporary file is kept
+around for a while afterwards, and during that time if the uncompressed
+@file{.bci} file is needed the temporary file is used. Each such
+reference updates an `access time' that is associated with the temporary
+file. The garbage collector checks the access times of all such
+temporary files, and deletes any that have not been accessed in five
+minutes or more. All of the temporaries are deleted automatically when
+the Scheme process is killed.
-@findex cmdl-interrupt/abort-top-level
-@lisp
-(cmdl-interrupt/abort-top-level)
-@end lisp
+Two other behaviors are available. One of them uncompresses the @file{.bci}
+file each time it is referenced, and the other uncompresses the @file{.bci}
+file and writes it back out as a @file{.bif} file.
+The @file{.bif} file remains after Scheme exits.
+The time interval and the behavior are controlled by variables.
-@noindent
-@kindex C-c C-g
-@kindex C-c g
-The options @kbd{C-c C-g} and @kbd{C-c g}, supplied for compatibility
-with older implementations, are equivalent to @kbd{C-c C-c}.
+@defvr {variable+} *save-uncompressed-files?*
+This variable affects what happens when @file{.bci} files are
+uncompressed. It allows a trade-off between performance and disk space.
+There are three possible values:
-@item C-c C-x
-@kindex C-c C-x
-Abort whatever Scheme evaluation is currently running and return to the
-``current'' @sc{repl}. If no evaluation is running, this is equivalent
-to evaluating
+@table @code
+@item #f
+The uncompressed versions of @file{.bci} files are never saved. Each
+time the information is needed the @file{.bci} file is uncompressed.
+This option requires the minimum amount of disk space and is the
+slowest.
-@findex cmdl-interrupt/abort-nearest
-@lisp
-(cmdl-interrupt/abort-nearest)
-@end lisp
+@item automatic
+Uncompressed versions of @file{.bci} files are kept as temporary files.
+The temporary files are deleted when Scheme exits, and if they have not
+been used for a while. This is the default.
-@kindex C-c x
-The option @kbd{C-c x}, supplied for compatibility with older
-implementations, is equivalent to @kbd{C-c C-x}.
+@item #t
+The @file{.bci} files are uncompressed to permanent @file{.bif} files.
+These files remain on disk after Scheme exits, and are rather large -
+about twice the size of the corresponding @file{.bci} files. If you
+choose this option and you are running out of disk space you may delete
+the @file{.bif} files. They will be regenerated as needed.
+@end table
+@end defvr
-@kindex C-x
-On the PC version @kbd{C-x} is equivalent to @kbd{C-c C-x}.
+@defvr {variable+} *uncompressed-file-lifetime*
+The minimum length of time that a temporary uncompressed version of
+a @file{.bci} file will stay on disk after it is last used.
+The time is in milliseconds; the default is @samp{300000} (five
+minutes).
+@end defvr
-@item C-c C-u
-@kindex C-c C-u
-Abort whatever Scheme evaluation is running and go up one level. If you
-are already at level number 1, it just aborts the evaluation, leaving
-you at level 1. If no evaluation is running, this is equivalent to
-evaluating
+@defvr {variable+} load-debugging-info-on-demand?
+If this variable is @file{#f}, then printing a compiled procedure
+will print the procedure's name only if the debugging information for
+that procedure is already loaded. Otherwise, it will force
+loading of the debugging information.
+The default value is @code{#f}.
+@end defvr
-@findex cmdl-interrupt/abort-previous
-@lisp
-(cmdl-interrupt/abort-previous)
-@end lisp
+@deffn {procedure+} sf filename [destination]
+@code{sf} is the program that transforms a source-code file into binary
+SCode form; it is used on machines that do not support native-code
+compilation. It performs numerous optimizations that can make your
+programs run considerably faster than unoptimized interpreted code.
+Also, the binary files that it generates load very quickly compared to
+source-code files.
-@kindex C-c u
-The option @kbd{C-c u}, supplied for compatibility with older
-implementations, is equivalent to @kbd{C-c C-u}.
+The simplest way to use @code{sf} is just to say:
-@kindex C-u
-On the PC version @kbd{C-u} is equivalent to @kbd{C-c C-u}.
+@example
+(sf @var{filename})
+@end example
-@item C-c C-b
-@kindex C-c C-b
-@cindex breakpoint
-Suspend whatever Scheme evaluation is running and start a
-@dfn{breakpoint} @sc{repl}. The evaluation can be resumed by evaluating
+@noindent
+This will cause your file to be transformed, and the resulting binary
+file to be written out with the same name, but with pathname type
+@code{"bin"}. If you do not specify a pathname type on the input file,
+@code{"scm"} is assumed.
-@findex proceed
-@lisp
-(proceed)
-@end lisp
+Like @code{load}, the first argument to @code{sf} may be a list of
+filenames rather than a single filename.
-@noindent
-in that @sc{repl} at any time.
+@code{sf} takes an optional second argument, which is the filename of
+the output file. If this argument is a directory, then the output file
+has its normal name but is put in that directory instead.
+@end deffn
-@kindex C-c b
-The option @kbd{C-c b}, supplied for compatibility with older
-implementations, is equivalent to @kbd{C-c C-b}.
+@node Declarations, Efficiency Tips, Compilation Procedures, Compiling Programs
+@section Declarations
+@cindex declarations
-@kindex C-b
-On the PC version @kbd{C-b} is equivalent to @kbd{C-c C-b}.
-@end table
+Several declarations can be added to your programs to help @code{cf} and
+@code{sf} make them more efficient.
-@node Restarting, The Current REPL Environment, Interrupting, REPL
-@section Restarting
+@menu
+* Standard Names::
+* In-line Coding::
+* Replacement of Operators::
+* Reduction of Operators::
+@end menu
-Another way of exiting a @sc{repl} is to use the @code{restart}
-procedure:
+@node Standard Names, In-line Coding, Declarations, Declarations
+@subsection Standard Names
-@deffn {procedure+} restart [K]
-@cindex REPL, restarting from
-This procedure selects and invokes a @dfn{restart method}. The list of
-restart methods is different for each @sc{repl}; in the case of an error
-@sc{repl}, this list is printed when the @sc{repl} is started:
+Normally, all files have a line
+@findex usual-integrations
@example
-@group
-;Unbound variable: foo
-;To continue, call RESTART with an option number:
-; (RESTART 3) => Specify a value to use instead of foo.
-; (RESTART 2) => Define foo to a given value.
-; (RESTART 1) => Return to read-eval-print level 1.
-
-2 error>
-@end group
+(declare (usual-integrations))
@end example
-If the @var{k} argument is given, it must be a positive integer index
-into the list (in this example it must be between one and three
-inclusive). The integer @var{k} selects an item from the list and
-invokes it. If @var{k} is not given, @code{restart} prints the list and
-prompts for the integer index:
+@noindent
+near their beginning, which tells the compiler that free variables whose
+names are defined in @code{system-global-environment} will not be
+shadowed by other definitions when the program is loaded. If you
+redefine some global name in your code, for example @code{car},
+@code{cdr}, and @code{cons}, you should indicate it in the declaration:
@example
-@group
-2 error> (restart)
-;Choose an option by number:
-; 3: Specify a value to use instead of foo.
-; 2: Define foo to a given value.
-; 1: Return to read-eval-print level 1.
-
-Option number:
-@end group
+(declare (usual-integrations car cdr cons))
@end example
-The simplest restart methods just perform their actions. For example:
+You can obtain an alphabetically-sorted list of the names that the
+@code{usual-integrations} declaration affects by evaluating the
+following expression:
@example
@group
-2 error> (restart 1)
-;Abort!
-
-1 ]=>
+(eval '(sort (append usual-integrations/constant-names
+ usual-integrations/expansion-names)
+ (lambda (x y)
+ (string<=? (symbol->string x)
+ (symbol->string y))))
+ (->environment '(scode-optimizer)))
@end group
@end example
-Other methods will prompt for more input before continuing:
-
-@example
-@group
-2 error> (restart)
-;Choose an option by number:
-; 3: Specify a value to use instead of foo.
-; 2: Define foo to a given value.
-; 1: Return to read-eval-print level 1.
-
-Option number: 3
+@node In-line Coding, Replacement of Operators, Standard Names, Declarations
+@subsection In-line Coding
-Value to use instead of foo: '(a b)
-;Value: (a b)
+Another useful facility is the ability to in-line code procedure
+definitions. In fact, the compiler will perform full beta conversion,
+with automatic renaming, if you request it. Here are the relevant
+declarations:
-1 ]=>
-@end group
-@end example
+@deffn {declaration+} integrate name @dots{}
+The variables @var{name}s must be defined in the same file as this
+declaration. Any reference to one of the named variables that appears
+in the same block as the declaration, or one of its descendant blocks,
+will be replaced by the corresponding binding's value expression.
@end deffn
-@node The Current REPL Environment, , Restarting, REPL
-@section The Current REPL Environment
+@deffn {declaration+} integrate-operator name @dots{}
+Similar to the @code{integrate} declaration, except that it only
+substitutes for references that appear in the operator position of a
+combination. All other references are ignored.
+@end deffn
-@cindex current REPL environment
-@findex user-initial-environment
-@findex system-global-environment
-Every @sc{repl} has a @dfn{current environment}, which is the place
-where expressions are evaluated and definitions are stored. When Scheme
-is started, this environment is the value of the variable
-@code{user-initial-environment}. There are a number of other
-environments in the system, for example
-@code{system-global-environment}, where the runtime system's bindings
-are stored.
+@deffn {declaration+} integrate-external filename
+Causes the compiler to use the top-level integrations provided by
+@var{filename}. @var{filename} should not specify a file type, and the
+source-code file that it names must have been previously processed by
+the compiler.
-You can get the current @sc{repl} environment by evaluating
+If @var{filename} is a relative filename (the normal case), it is
+interpreted as being relative to the file in which the declaration
+appears. Thus if the declaration appears in file @file{/usr/cph/foo.scm},
+then the compiler looks for a file called @file{/usr/cph/@var{filename}.ext}.
-@findex nearest-repl/environment
-@lisp
-(nearest-repl/environment)
-@end lisp
+Note: When the compiler finds top-level integrations, it collects them
+and outputs them into an auxiliary file with extension @file{.ext}.
+This @file{.ext} file is what the @code{integrate-external} declaration
+refers to.
+@end deffn
-There are several other ways to obtain environments. For example, if
-you have a procedure object, you can get a pointer to the environment in
-which it was closed by evaluating
+@findex define-integrable
+@findex define
+Note that the most common use of this facility, in-line coding of
+procedure definitions, requires a somewhat complicated use of these
+declarations. Because this is so common, there is a special form,
+@code{define-integrable}, which is like @code{define} but performs the
+appropriate declarations. For example:
-@findex procedure-environment
-@lisp
-(procedure-environment @var{procedure})
-@end lisp
+@example
+@group
+(define-integrable (foo-bar foo bar)
+ (vector-ref (vector-ref foo bar) 3))
+@end group
+@end example
-Your programs create new environments whenever a procedure is called.
+Here is how you do the same thing without this special form: there
+should be an @code{integrate-operator} declaration for the procedure's
+name, and (internal to the procedure's definition) an @code{integrate}
+declaration for each of the procedure's parameters, like this:
-Here is the procedure that changes the @sc{repl}'s environment:
+@example
+@group
+(declare (integrate-operator foo-bar))
-@deffn {procedure+} ge environment
-Changes the current @sc{repl} environment to be @var{environment}
-(@code{ge} stands for ``Goto Environment''). @var{Environment} is
-allowed to be a procedure as well as an environment object. If it is a
-procedure, then the closing environment of that procedure is used in its
-place.
-@end deffn
+(define foo-bar
+ (lambda (foo bar)
+ (declare (integrate foo bar))
+ (vector-ref (vector-ref foo bar) 3)))
+@end group
+@end example
-@deffn {procedure+} pe
-This procedure is useful for finding out which environment you are in
-(@code{pe} stands for ``Print Ennvironment''). If the current @sc{repl}
-environment belongs to a package, then @code{pe} returns the package
-name (a list of symbols). If the current @sc{repl} environment does not
-belong to a package then the environment is returned.
-@end deffn
+The reason for this complication is as follows: the
+@code{integrate-operator} declaration finds all the references to
+@code{foo-bar} and replaces them with the lambda expression from the
+definition. Then, the @code{integrate} declarations take effect because
+the combination in which the reference to @code{foo-bar} occurred
+supplies code that is substituted throughout the body of the procedure
+definition. For example:
-@deffn {procedure+} gst syntax-table
-In addition to the current environment, each @sc{repl} maintains a
-current @dfn{syntax table}. The current syntax table tells the
-@sc{repl} which keywords are used to identify special forms (e.g.@:
-@code{if}, @code{lambda}). If you write macros, often you will want to
-make your own syntax table, in which case it is useful to be able to
-make that syntax table be the current one. @code{gst} allows you to do
-that.
-@end deffn
+@example
+(foo-bar (car baz) (cdr baz))
+@end example
-@node Debugging, Loading Files, REPL, Top
-@chapter Debugging
+@noindent
+First use the @code{integrate-operator} declaration:
-@strong{This chapter is out of date and currently under revision}.
+@example
+@group
+((lambda (foo bar)
+ (declare (integrate foo bar))
+ (vector-ref (vector-ref foo bar) 3))
+ (car baz)
+ (cdr baz))
+@end group
+@end example
-This chapter is adapted from @cite{Don't Panic: A 6.001 User's Guide to
-the Chipmunk System}, by Arthur A. Gleckler.
+@noindent
+Next use the internal @code{integrate} declaration:
-@cindex bugs
-@cindex debugging
-Even computer software that has been planned carefully and written well
-may not always work correctly. Mysterious creatures called @dfn{bugs}
-may creep in and wreak havoc, leaving the programmer to clean up the
-mess. Some have theorized that a program fails only because its author
-made a mistake, but experienced computer programmers know that bugs are
-always to blame. This is why the task of fixing broken computer
-software is called @dfn{debugging}.
+@example
+@group
+((lambda (foo bar)
+ (vector-ref (vector-ref (car baz) (cdr baz)) 3))
+ (car baz)
+ (cdr baz))
+@end group
+@end example
-It is impossible to prove the correctness of any non-trivial program;
-hence the Cynic's First Law of Debugging:
+@noindent
+Next notice that the variables @code{foo} and @code{bar} are not used,
+and eliminate them:
-@quotation
-Programs don't become more reliable as they are debugged; the bugs just
-get harder to find.
-@end quotation
+@example
+@group
+((lambda ()
+ (vector-ref (vector-ref (car baz) (cdr baz)) 3)))
+@end group
+@end example
-@cindex breakpoints
-Scheme is equipped with a variety of special software for finding and
-removing bugs. The debugging tools include facilities for tracing a
-program's use of specified procedures, for examining Scheme
-environments, and for setting @dfn{breakpoints}, places where the
-program will pause for inspection.
+@noindent
+Finally, remove the @code{((lambda () @dots{}))} to produce
-@cindex error
-Many bugs are detected when programs try to do something which is
-impossible, like adding a number to a symbol, or using a variable which
-does not exist; this type of mistake is called an @dfn{error}.
-Whenever an error occurs, Scheme prints an error message and starts a
-new @sc{repl}. For example, using a nonexistent variable @code{foo} will
-cause Scheme to respond
+@example
+(vector-ref (vector-ref (car baz) (cdr baz)) 3)
+@end example
+
+@subsubheading Useful tip
+@cindex integrations, seeing effects of
+To see the effect of integration declarations (and of macros) on a
+source file, pretty-print the @file{.bin} file like this (be prepared
+for a lot of output).
@example
-1 ]=> foo
+@group
+(sf "foo.scm")
+(pp (fasload "foo.bin"))
+@end group
+@end example
-;Unbound variable: foo
-;To continue, call RESTART with an option number:
-; (RESTART 3) => Specify a value to use instead of foo.
-; (RESTART 2) => Define foo to a given value.
-; (RESTART 1) => Return to read-eval-print level 1.
+@node Replacement of Operators, Reduction of Operators, In-line Coding, Declarations
+@subsection Operator Replacement
-2 error>
+The @code{replace-operator} declaration is provided to inform the
+compiler that certain operators may be replaced by other operators
+depending on the number of arguments.
+For example:
+
+@noindent
+Declaration:
+
+@example
+(declare (replace-operator (map (2 map-2) (3 map-3))))
@end example
-Sometimes, a bug will never cause an error, but will still cause the
-program to operate incorrectly. For instance,
+@noindent
+Replacements:
-@lisp
-(prime? 7) @result{} #f
-@end lisp
+@example
+@group
+(map @var{f} @var{x} @var{y} @var{z}) @expansion{} (map @var{f} @var{x} @var{y} @var{z})
+(map @var{f} @var{x} @var{y}) @expansion{} (map-3 @var{f} @var{x} @var{y})
+(map @var{f} @var{x}) @expansion{} (map-2 @var{f} @var{x})
+(map @var{f}) @expansion{} (map @var{f})
+(map) @expansion{} (map)
+@end group
+@end example
-In this situation, Scheme does not know that the program is misbehaving.
-The programmer must notice the problem and, if necessary, start the
-debugging tools manually.
+@noindent
+Presumably @code{map-2} and @code{map-3} are efficient versions of
+@code{map} that are written for exactly two and three arguments
+respectively. All the other cases are not expanded but are handled by the
+original, general @code{map} procedure, which is less efficient because
+it must handle a variable number of arguments.
-There are several approaches to finding bugs in a Scheme program:
+@deffn {declaration+} replace-operator name ...
+
+The syntax of this declaration is
+
+@example
+@group
+(replace-operator
+ (@var{name}
+ (@var{nargs1} @var{value1})
+ (@var{nargs2} @var{value2})
+ ...))
+@end group
+@end example
+
+where
@itemize @bullet
@item
-Inspect the original Scheme program.
+@var{name} is a symbol.
@item
-Use the debugging tools to follow your program's progress.
+@var{nargs1}, @var{nargs2} etc.@: are non-negative integers, or one of the
+following symbols: @code{any}, @code{else} or @code{otherwise}.
@item
-Edit the program to insert checks and breakpoints.
-@end itemize
+@var{value1}, @var{value2} etc.@: are simple
+expressions in one of these forms:
-@noindent
-Only experience can teach how to debug programs, so be sure to
-experiment with all these approaches while doing your own debugging.
-Planning ahead is the best way to ward off bugs, but when bugs do
-appear, be prepared to attack them with all the tools available.
+@table @code
+@item '@var{constant}
+A constant.
-@menu
-* Subproblems and Reductions::
-* Debugger::
-* Debugging Aids::
-* Advising Procedures::
-@end menu
+@item @var{variable}
+A variable.
-@node Subproblems and Reductions, Debugger, Debugging, Debugging
-@section Subproblems and Reductions
+@item (primitive @var{primitive-name} @r{[}@var{arity}@r{]})
+The primitive procedure named @var{primitive-name}. The optional
+element @var{arity}, a non-negative integer, specifies the number of
+arguments that the primitive accepts.
-@cindex subproblem
-@cindex reduction
-@cindex subexpression
-Understanding the concepts of @dfn{reduction} and @dfn{subproblem} is
-essential to good use of the debugging tools. The Scheme interpreter
-evaluates an expression by @dfn{reducing} it to a simpler expression.
-In general, Scheme's evaluation rules designate that evaluation proceeds
-from one expression to the next by either starting to work on a
-@dfn{subexpression} of the given expression, or by reducing the entire
-expression to a new (simpler, or reduced) form. Thus, a history of the
-successive forms processed during the evaluation of an expression will
-show a sequence of subproblems, where each subproblem may consist of a
-sequence of reductions.
+@item (global @var{var})
+A global variable.
+@end table
+@end itemize
-For example, both @code{(+ 5 6)} and @code{(+ 7 9)} are subproblems of
-the following combination:
+The meanings of these fields are:
-@lisp
-(* (+ 5 6) (+ 7 9))
-@end lisp
+@itemize @bullet
+@item
+@var{name} is the name of the operator to be reduced. If is is not
+shadowed (for example, by a let) then it may be replaced according to
+the following rules.
-If @code{(prime? n)} is true, then @code{(cons 'prime n)} is a reduction
-for the following expression:
+@item
+If the operator has @var{nargsN} arguments then it is replaced with a
+call to @var{valueN} with the same arguments.
-@lisp
-(if (prime? n)
- (cons 'prime n)
- (cons 'not-prime n))
-@end lisp
+@item
+If the number of arguments is not listed, and one of the @var{nargsN} is
+@code{any}, @code{else} or @code{otherwise}, then the operation is
+replaced with a call to the corresponding @var{valueN}.
+Only one of the @var{nargsN} may be of this form.
-This is because the entire subproblem of the @code{if} expression can
-be reduced to the problem @code{(cons 'prime n)}, once we know that
-@code{(prime? n)} is true; the @code{(cons 'not-prime n)} can be
-ignored, because it will never be needed. On the other hand, if
-@code{(prime? n)} were false, then @code{(cons 'not-prime n)} would be
-the reduction for the @code{if} expression.
+@item
+If the number of arguments is not listed and none of the @var{nargsN} is
+@code{any}, @code{else} or @code{otherwise}, then the operation is not
+replaced.
+@end itemize
+@end deffn
-The @emph{subproblem level} is a number representing how far back in the
-history of the current computation a particular evaluation is. Consider
-@code{factorial}:
+@node Reduction of Operators, , Replacement of Operators, Declarations
+@subsection Operator Reduction
-@lisp
-(define (factorial n)
- (if (< n 2)
- 1
- (* n (factorial (- n 1)))))
-@end lisp
+@findex reduce-operator
+The @code{reduce-operator} declaration is provided to inform the
+compiler that certain names are n-ary versions of binary operators.
+Here are some examples:
@noindent
-If we stop @code{factorial} in the middle of evaluating @code{(- n 1)},
-the @code{(- n 1)} is at subproblem level 0. Following the history of
-the computation ``upwards,'' @code{(factorial (- n 1))} is at subproblem
-level 1, and @code{(* n (factorial (- n 1)))} is at subproblem level 2.
-These expressions all have @emph{reduction number} 0. Continuing
-upwards, the @code{if} expression has reduction number 1.
-
-Moving backwards in the history of a computation, subproblem levels and
-reduction numbers increase, starting from zero at the expression
-currently being evaluated. Reduction numbers increase until the next
-subproblem, where they start over at zero. The best way to get a feel
-for subproblem levels and reduction numbers is to experiment with the
-debugging tools, especially @code{debug}.
+Declaration:
-@node Debugger, Debugging Aids, Subproblems and Reductions, Debugging
-@section The Debugger
+@example
+(declare (reduce-operator (cons* cons)))
+@end example
-@cindex debugger
-@cindex continuation Browser
-@cindex browser, Continuation
-@findex debug
-There are three debuggers available with MIT Scheme. Two of them
-require and run under Edwin, and are described in that section of this
-document (@pxref{Edwin}). The third is command oriented, does not
-require Edwin, and is described here.
+@noindent
+Replacements:
-The @dfn{debugger}, called @code{debug}, is the tool you should use when
-Scheme signals an error and you want to find out what caused the error.
-When Scheme signals an error, it records all the information necessary
-to continue running the Scheme program that caused the error; the
-debugger provides you with the means to inspect this information. For
-this reason, the debugger is sometimes called a @dfn{continuation
-browser}.
+@example
+@group
+(cons* @var{x} @var{y} @var{z} @var{w}) @expansion{} (cons @var{x} (cons @var{y} (cons @var{z} @var{w}))),
+(cons* @var{x} @var{y}) @expansion{} (cons @var{x} @var{y})
+(cons* @var{x}) @expansion{} @var{x}
+(cons*) @error{} too few arguments
+@end group
+@end example
-Here is the transcript of a typical Scheme session, showing a user
-evaluating the expression @code{(fib 10)}, Scheme responding with an
-unbound variable error for the variable @code{fob}, and the user
-starting the debugger:
+@noindent
+Declaration:
@example
-1 ]=> (fib 10)
-
-;Unbound variable: fob
-;To continue, call RESTART with an option number:
-; (RESTART 3) => Specify a value to use instead of fob.
-; (RESTART 2) => Define fob to a given value.
-; (RESTART 1) => Return to read-eval-print level 1.
+(declare (reduce-operator (list cons (null-value '() any))))
+@end example
-2 error> (debug)
+@noindent
+Replacements:
-There are 6 subproblems on the stack.
+@example
+@group
+(list @var{x} @var{y} @var{z} @var{w}) @expansion{} (cons @var{x} (cons @var{y} (cons @var{z} (cons @var{w} '()))))
+(list @var{x} @var{y}) @expansion{} (cons @var{x} (cons @var{y} '()))
+(list @var{x}) @expansion{} (cons @var{x} '())
+(list) @expansion{} '()
+@end group
+@end example
-Subproblem level: 0 (this is the lowest subproblem level)
-Expression (from stack):
- fob
-Environment created by the procedure: FIB
- applied to: (10)
-The execution history for this subproblem contains 1 reduction.
-You are now in the debugger. Type q to quit, ? for commands.
+@noindent
+Declaration:
-3 debug>
+@example
+(declare (reduce-operator (- %- (null-value 0 single) (group left))))
@end example
@noindent
-@cindex execution history
-This tells us that the error occurred while trying to evaluate the
-expression @code{fob} while running @code{(fib 10)}. It also tells us
-this is subproblem level 0, the first of 8 subproblems that are
-available for us to examine. The expression shown is marked ``(from
-stack)'', which tells us that this expression was reconstructed from the
-interpreter's internal data structures. Another source of information
-is the @dfn{execution history}, which keeps a record of expressions
-evaluated by the interpreter. The debugger informs us that the
-execution history has recorded some information for this subproblem,
-specifically a description of one reduction.
-
-@node Debugging Aids, Advising Procedures, Debugger, Debugging
-@section Debugging Aids
+Replacements:
-An important step in debugging is to locate the piece of code from which
-the error is signalled. The Scheme debugger contains a history examiner
-and an environment examiner to aid the user in locating a bug.
+@example
+@group
+(- @var{x} @var{y} @var{z} @var{w}) @expansion{} (%- (%- (%- @var{x} @var{y}) @var{z}) @var{w})
+(- @var{x} @var{y}) @expansion{} (%- @var{x} @var{y})
+(- @var{x}) @expansion{} (%- 0 @var{x})
+(-) @expansion{} 0
+@end group
+@end example
-@deffn {special form+} bkpt message irritant
-Sets a breakpoint. When the breakpoint is encountered, @var{message}
-and @var{irritant} are typed and a read-eval-print loop is entered in
-the current environment. To exit from the breakpoint and proceed with
-the interrupted process, call the procedure @code{proceed}. Sample
-usage:
+@noindent
+Declaration:
@example
-1 ]=> (begin (write-line 'foo)
- (bkpt 'test-2 'test-3)
- (write-line 'bar)
- 'done)
+(declare (reduce-operator (+ %+ (null-value 0 none) (group right))))
+@end example
-foo
- test-2 test-3
-;To continue, call RESTART with an option number:
-; (RESTART 2) => Return from BKPT.
-; (RESTART 1) => Return to read-eval-print level 1.
+@noindent
+Replacements:
-2 bkpt> (+ 3 3)
+@example
+@group
+(+ @var{x} @var{y} @var{z} @var{w}) @expansion{} (%+ @var{x} (%+ @var{y} (%+ @var{z} @var{w})))
+(+ @var{x} @var{y}) @expansion{} (%+ @var{x} @var{y})
+(+ @var{x}) @expansion{} @var{x}
+(+) @expansion{} 0
+@end group
+@end example
-;Value: 6
+Note: This declaration does not cause an appropriate definition of
+@code{%+} (in the last example) to appear in your code. It merely
+informs the compiler that certain optimizations can be performed on
+calls to @code{+} by replacing them with calls to @code{%+}. You should
+provide a definition of @code{%+} as well, although it is not required.
-2 bkpt> (proceed)
+@noindent
+Declaration:
-bar
-;Value: done
+@example
+@group
+(declare (reduce-operator (apply (primitive cons)
+ (group right)
+ (wrapper (global apply) 1))))
+@end group
@end example
-@end deffn
-@deffn {procedure+} pp object [output-port [as-code?]]
-@deffnx {procedure+} pa procedure
-@cindex inspecting procedures
-@code{pp} procedure is described in the MIT Scheme Reference Manual. We
-just note here that, by default, MIT Scheme keeps debugging information,
-so @code{pp} is useful for looking at the source code of a procedure
-(compiled or interpreted).
+@noindent
+Replacements:
-@code{pa} prints the arguments of @var{procedure}. This can be used to
-remind yourself, for example, of the correct order of the arguments to a
-procedure.
+@example
+@group
+(apply @var{f} @var{x} @var{y} @var{z} @var{w}) @expansion{} ((access apply ()) @var{f} (cons @var{x} (cons @var{y} (cons @var{z} @var{w}))))
+(apply @var{f} @var{x} @var{y}) @expansion{} ((access apply ()) @var{f} (cons @var{x} @var{y}))
+(apply @var{f} @var{x}) @expansion{} (apply @var{f} @var{x})
+(apply @var{f}) @expansion{} (apply @var{f})
+(apply) @expansion{} (apply)
+@end group
+@end example
+
+@deffn {declaration+} reduce-operator name ...
+The general format of the declaration is (brackets denote optional
+elements):
@example
-1 ]=> for-all?
-;Value 40: #[compiled-procedure 40 (for-all? "boole" #x6) #xC #x20ECB0]
+@group
+(reduce-operator
+ (@var{name}
+ @var{binop}
+ @r{[}(group @var{ordering})@r{]}
+ @r{[}(null-value @var{value} @var{null-option})@r{]}
+ @r{[}(singleton @var{unop})@r{]}
+ @r{[}(wrapper @var{wrap} @r{[}n@r{]})@r{]}
+ @r{[}(maximum @var{m})@r{]}
+ ))
+@end group
+@end example
-1 ]=> (pa for-all?)
-(items predicate)
-;No value
+@noindent
+where
-1 ]=> (pp for-all?)
-(named-lambda (for-all? items predicate)
- (let loop ((items items))
- (or (null? items)
- (and (predicate (car items))
- (loop (cdr items))))))
-@end example
-@end deffn
-
-@deffn {procedure+} where [obj]
-@cindex environments, examining
-@cindex inspecting environments
-@cindex examining environments
-The procedure @code{where} enters the environment examination system.
-This allows environments and variable bindings to be examined and
-modified. @code{where} accepts one letter commands. The commands can
-be found by typing @kbd{?} to the @samp{where>} prompt. The optional
-argument, @var{obj}, is an object with an environment associated with
-it: an environment, a procedure, or a promise. If @var{obj} is omitted,
-the environment examined is the read-eval-print environment from which
-@code{where} was called (or an error or breakpoint environment if called
-from the debugger). If a compound procedure is supplied, @code{where}
-lets the user examine the environment of definition of the procedure.
-This is useful for debugging procedure arguments and values.
-@end deffn
-
-@deffn {procedure+} apropos text [package/env [search-parents?]]
-@cindex finding procedures
-@cindex procedures, finding
-@cindex help
-Search an environment for bound names containing @var{text} and print
-out the matching bound names. If @var{package/env} is specified, it
-must be an environment or package name, and it defaults to the current
-@sc{repl} environment. The flag @var{search-parents?} specifies whether
-the environmnet's parents should be included in the search. The default
-is @code{#F} if @var{package/env} is specified, and @code{#T} if
-@var{package/env} is not specified.
+@itemize @bullet
+@item
+@var{n} and @var{m} are non-negative integers.
-@example
-1 ]=> (apropos "search")
-#[package 41 (user)]
-#[package 33 ()]
-list-search-negative
-list-search-positive
-search-ordered-subvector
-search-ordered-vector
-vector-binary-search
-;No value
-@end example
-@end deffn
+@item
+@var{name} is a symbol.
-@node Advising Procedures, , Debugging Aids, Debugging
-@section Advising Procedures
+@item
+@var{binop}, @var{value}, @var{unop}, and @var{wrap} are simple
+expressions in one of these forms:
-Giving advice to procedures is a powerful debugging technique.
-@code{trace} and @code{break} are useful examples of advice-giving
-procedures.
-Note that the advice system only works for interpreted procedures.
+@table @code
+@item '@var{constant}
+A constant.
-@deffn {procedure+} trace-entry proc
-Causes an informative message to be printed whenever the procedure
-@var{proc} is entered. The message is of the form
+@item @var{variable}
+A variable.
-@example
-[Entering #[compound-procedure 1 foo]
- Args: @var{val1}
- @var{val2}
- ...]
-@end example
+@item (primitive @var{primitive-name} @r{[}@var{arity}@r{]})
+The primitive procedure named @var{primitive-name}. The optional
+element @var{arity} specifies the number of arguments that the primitive
+accepts.
-where @var{val1}, @var{val2} etc.@: are the evaluated arguments supplied
-to the procedure.
-@end deffn
+@item (global @var{var})
+A global variable.
+@end table
-@deffn {procedure+} trace-exit proc
-Causes and informative message to be printed when procedure @var{proc}
-terminates. The message contains the procedure, its argument values,
-and the value returned by the procedure.
-@end deffn
+@item
+@var{null-option} is either @code{always}, @code{any}, @code{one},
+@code{single}, @code{none}, or @code{empty}.
-@deffn {procedure+} trace-both proc
-@deffnx {procedure+} trace proc
-@code{trace-both} is the same as calling both @code{trace-entry} and
-@code{trace-exit} on @var{proc}.
-@code{trace} is the same as @code{trace-both}.
-@end deffn
+@item
+@var{ordering} is either @code{left}, @code{right}, or
+@code{associative}.
+@end itemize
-@deffn {procedure+} untrace-entry [proc]
-@code{untrace-entry} stops tracing the entry of @var{proc}.
-If @var{proc} is not given, the
-default is to stop tracing the entry of all entry-traced procedures.
-@end deffn
+@noindent
+The meaning of these fields is:
-@deffn {procedure+} untrace-exit [proc]
-Stops tracing the exit of @var{proc}. If @var{proc} is not included,
-the default is all exit-traced procedures.
-@end deffn
+@itemize @bullet
+@item
+@var{name} is the name of the n-ary operation to be reduced.
-@deffn {procedure+} untrace [proc]
-Stops tracing both the entry to and the exit from @var{proc}. If
-@var{proc} is not given, the default is all traced procedures.
-@end deffn
+@item
+@var{binop} is the binary operation into which the n-ary operation is to
+be reduced.
-@deffn {procedure+} break-entry proc
-Like @code{trace-entry} with the additional effect that a breakpoint is
-entered when procedure @var{proc} is invoked. Both @var{proc} and its
-arguments can be accessed by calling the procedures @code{*proc*} and
-@code{*args*}, respectively.
-Use @code{restart} or @code{proceed} to continue from a breakpoint.
-@end deffn
+@item
+The @code{group} option specifies whether @var{name} associates to the
+right or left.
-@deffn {procedure+} break-exit proc
-Like @code{trace-exit}, except that a breakpoint is entered just prior
-to leaving the procedure @var{proc}. @var{Proc}, its arguments, and the
-result can be accessed by calling the procedures @code{*proc*},
-@code{*args*}, and @code{*result*}, respectively.
-Use @code{restart} or @code{proceed} to continue from a breakpoint.
-@end deffn
+@item
+The @code{null-value} option specifies a value to use in the following
+cases:
-@deffn {procedure+} break-both proc
-@deffnx {procedure+} break proc
-Sets a breakpoint at the beginning and end of @var{proc}. This is
-@code{break-entry} and @code{break-exit} combined.
-@end deffn
+@table @code
+@item none
+@itemx empty
+When no arguments are supplied to @var{name}, @var{value} is returned.
-@deffn {procedure+} unbreak [proc]
-Discontinues the entering of a breakpoint on the entry to and exit from
-the procedure @var{proc}. If @var{proc} is not given, the default is
-all breakpointed procedures.
-@end deffn
+@item one
+@itemx single
+When a single argument is provided to @var{name}, @var{value} becomes
+the second argument to @var{binop}.
-@deffn {procedure+} unbreak-entry [proc]
-Discontinues the entering of a breakpoint on the entry to the procedure
-@var{proc}. If @var{proc} is not given, the default is all
-entry-breakpointed procedures.
-@end deffn
+@item any
+@itemx always
+@var{binop} is used on the ``last'' argument, and @var{value} provides
+the remaining argument to @var{binop}.
+@end table
-@deffn {procedure+} unbreak-exit [proc]
-Discontinues the entering of a breakpoint on the exit from the procedure
-@var{proc}. If @var{proc} is not given, the default is all
-exit-breakpointed procedures.
-@end deffn
+In the above options, when @var{value} is supplied to @var{binop}, it is
+supplied on the left if grouping to the left, otherwise it is supplied
+on the right.
-@deffn {procedure+} advise-entry proc advice
-General entry-advising procedure. @code{trace-entry} and
-@code{break-entry} are examples of entry-advising procedures.
-@code{advise-entry} gives @var{advice} to @var{proc}. When @var{proc}
-is invoked, @var{advice} is passed three arguments: @var{proc}, a list
-of @var{proc}'s argument values, and the current environment.
-@end deffn
+@item
+The @code{singleton} option specifies a function, @var{unop}, to be
+invoked on the single argument left. This option supersedes the
+@code{null-value} option, which can only take the value @code{none}.
-@deffn {procedure+} advise-exit proc advice
-The general exit-advising procedure. @code{trace-exit} and
-@code{break-exit} are examples of exit-advising procedures.
-@var{Advice} is a procedure that should accept four arguments:
-@var{proc}, its argument values, the result computed by @var{proc}, and
-the current environment. @var{Advice} is responsible for returning a
-value on behalf of @var{proc}. That is, the value returned by
-@var{advice} is the value returned by the advised procedure.
-@end deffn
+@item
+The @code{wrapper} option specifies a function, @var{wrap}, to be
+invoked on the result of the outermost call to @var{binop} after the
+expansion.
+If @var{n} is provided it must be a non-negative integer indicating a number
+of arguments that are transferred verbatim from the original call to
+the wrapper. They are passed to the left of the reduction.
-@deffn {procedure+} advice proc
-Returned the advice, if any, given to @var{proc}.
+@item
+The maximum option specifies that calls with more than @var{m} arguments
+should not be reduced.
+@end itemize
@end deffn
-@deffn {procedure+} unadvise-entry [proc]
-Removes entry advice from @var{proc}. If @var{proc} is not given, the
-default is all entry-advised procedures.
-@end deffn
+@node Efficiency Tips, , Declarations, Compiling Programs
+@section Efficiency Tips
-@deffn {procedure+} unadvise-exit [proc]
-Removes exit advice from @var{proc}. If @var{proc} is not given, the
-default is all exit-advised procedures.
-@end deffn
+How you write your programs can have a large impact on how efficiently the
+compiled program runs. The most important thing to do, after choosing
+suitable data structures, is to put the following declaration near the
+beginning of the file.
-@deffn {procedure+} unadvise [proc]
-Removes all advice from @var{proc}. This is a combination of
-@code{unadvise-entry} and @code{unadvise-exit}. If @var{proc} is not
-given, the default is all advised procedures.
-@end deffn
+@example
+(declare (usual-integrations))
+@end example
-@deffn {procedure+} *proc*
-@code{*proc*} is a procedure which returns as its value the ``broken''
-procedure. It is used only at a breakpoint set by the procedures
-@code{break-exit} and @code{break-entry} or procedures defined in terms
-of these procedures (like @code{break-both} and @code{break}).
-@end deffn
+Without this declaration the compiler cannot recognize any of the common
+operators and compile them efficiently.
-@deffn {procedure+} *args*
-@code{*args*} is a procedure which returns as its value a list of the
-arguments supplied to the ``broken'' procedure. It is used only at a
-breakpoint set by the procedures @code{break-exit} and
-@code{break-entry} or procedures defined in terms of these procedures
-(like @code{break-both} and @code{break}).
-@end deffn
+The @code{usual-integrations} declaration is usually sufficient to get
+good quality compiled code.
-@deffn {procedure+} *result*
-@code{*result*} is a procedure which returns as its value the result that
-was about to be returned by the ``broken'' procedure. It is used only at
-a breakpoint set by the procedure @code{break-exit} or procedures
-defined in terms of this procedure (like @code{break-both} and
-@code{break}).
-@end deffn
+If you really need to squeeze more performance out of you code then we
+hope that you find the following grab-bag of tips, hints and
+explanations useful.
-@node Loading Files, World Images, Debugging, Top
-@chapter Loading Files
+@menu
+* Coding style::
+* Global variables::
+* Fixnum arithmetic::
+* Flonum arithmetic::
+@end menu
-To load files of Scheme code, use the procedure @code{load}:
+@node Coding style, Global variables, Efficiency Tips, Efficiency Tips
+@subsection Coding style
-@deffn {procedure} load filename [environment [syntax-table]]
-@var{Filename} may be a string naming a file, or a list of strings
-naming many files. @var{Environment}, if given, is the environment to
-evaluate the file in; if not given the current @sc{repl} environment is
-used. Likewise @var{syntax-table} is the syntax table to use.
+@subsubheading Better predicates
-@findex pathname-type
-@code{load} determines whether the file to be loaded is binary or source
-code, and performs the appropriate action. By convention, files of
-source code have a pathname type of @code{"scm"}, and files of binary
-SCode have pathname type @code{"bin"}. Native-code binaries have
-pathname type @code{"com"}. (See the description of
-@code{pathname-type} in the reference manual.)
-@end deffn
+Consider the following implementation of @code{map} as might be found in
+any introductory book on Scheme:
-@defvr {variable+} load-noisily?
-If @code{load-noisily?} is set to @code{#t}, @code{load} will print the
-value of each expression in the file as it is evaluated. Otherwise,
-nothing is printed except for the value of the last expression in the
-file. (Note: the noisy loading feature is implemented for source-code
-files only.)
-@end defvr
+@example
+@group
+(define (map f lst)
+ (if (null? lst)
+ '()
+ (cons (f (car lst)) (map f (cdr lst)))))
+@end group
+@end example
-@defvr {variable+} load/default-types
-When load is given a pathname without a type, it uses the value of this
-variable to determine what pathname types to look for and how to load
-the file. @code{load/default-types} is a list of associations that maps
-pathname types (strings) to loader procedures. @code{load} tries the
-pathname types in the order that they appear in the list. The initial
-value of this variable has pathname types in this order:
+The problem with this definition is that at the points where @code{car}
+and @code{cdr} are called we still do not know that @var{lst} is a pair.
+The compiler must insert a type check, or if type checks are disabled,
+the program might give wrong results. Since one of the fundamental
+properties of @code{map} is that it transforms lists, we should make the
+relationship between the input pairs and the result pairs more apparent
+in the code:
-@lisp
-"com" "so" "sl" "bin" "scm"
-@end lisp
+@example
+@group
+(define (map f lst)
+ (cond ((pair? lst)
+ (cons (f (car lst)) (map f (cdr lst))))
+ ((null? lst)
+ '())
+ (else
+ ...) ; You decide - '() or an error?
+@end group
+@end example
-This means that, for example, @code{(load "foo")} will try to load
-@file{foo.com} first, and @file{foo.scm} only after looking for and
-failing to find the other pathname types.
-@end defvr
+Note also that the @code{pair?} case comes first because we expect that
+@code{map} will be called on lists which have, on average, length
+greater that one.
-@cindex working directory
-@findex pwd
-@findex cd
-All pathnames are interpreted relative to a working directory, which is
-initialized when Scheme is started. The working directory can be
-obtained from the procedure @code{pwd} or modified by the procedure
-@code{cd}; see the reference manual for details. Files may be loaded
-when Scheme first starts; see the @code{-load} command line option for
-details.
+@page
+@subsubheading Internal procedures
-@node World Images, Garbage Collection, Loading Files, Top
-@chapter World Images
+Calls to internal procedures are faster than calls to global procedures.
+There are two things that make internal procedures faster: First, the
+procedure call is compiled to a direct jump to a known location, which
+is more efficient that jumping `via' a global binding.
+Second, there is a knock-on effect: since the compiler can see the
+internal procedure, the compiler can analyze it and possibly produce
+better code for other expressions in the body of the loop too:
-@cindex world image
-@cindex band
-A @dfn{world image} is a file that contains a complete Scheme system,
-perhaps additionally including user application code. Scheme provides
-two methods for saving and restoring world images. The first method
-writes a file containing all of the Scheme code in the world, which is
-called a @dfn{band}. The file @file{runtime.com} that is loaded by the
-microcode is just such a band.
-To make your own band, use the procedure
-@code{disk-save}.
+@example
+@group
+(define (map f original-lst)
+ (let walk ((lst original-lst))
+ (cond ((pair? lst)
+ (cons (f (car lst)) (walk (cdr lst))))
+ ((null? lst)
+ '())
+ (else
+ (error "Not a proper list:" original-lst)))))
+@end group
+@end example
-@deffn {procedure+} disk-save filename [identify]
-Causes a band to be written to the file specified by @var{filename}.
-The optional argument @var{identify} controls what happens when that
-band is restored, as follows:
+@subsubheading Internal defines
-@table @asis
-@item not specified
-Start up in the top-level @sc{repl}, identifying the world in the normal
-way.
+Internal definitions are a useful tool for structuring larger
+procedures. However, certain internal definitions can thwart compiler
+optimizations. Consider the following two procedures, where
+@code{compute-100} is some unknown procedure that we just know returns
+@samp{100}.
-@item a string
-Do the same thing except print that string instead of @samp{Scheme} when
-restarting.
+@example
+@group
+(define (f1)
+ (define v 100)
+ (lambda () v))
-@item the constant @code{#t}
-Restart exactly where you were when the call to @code{disk-save} was
-performed. This is especially useful for saving your state when an
-error has occurred and you are not in the top-level @sc{repl}.
+(define (f2)
+ (define v (compute-100))
+ (lambda () v))
+@end group
+@end example
-@item the constant @code{#f}
-Just like @code{#t}, except that the runtime system will not perform
-normal restart initializations; in particular, it will not load your
-init file.
-@end table
-@end deffn
+The procedure returned by @code{f1} will always give the same result and
+the compiler can prove this. The procedure returned by @code{f2} may
+return different results, even if @code{f2} is only called once.
+Because of this, the compiler has to allocate a memory cell to @code{v}.
+How can the procedure return different results?
-@findex disk-restore
-To restore a saved band, give the @code{-band} option when starting
-Scheme. Alternatively, evaluate @code{(disk-restore @var{filename})}
-from a running Scheme, which will destroy the current world, replacing
-it with the saved world. The argument to @code{disk-restore} may be
-omitted, in which case it defaults to the filename from which the
-current world was last restored.
-
-Note: with the C back-end, @code{disk-save} is not very useful. The
-reason is that compiled procedures are compiled C code that has been
-dynamically linked in, and @code{disk-save} does not save any C
-procedures. If you need to build a band for a C back-end system, please
-contact us. Your system is a C back-end system if the following
-expression does not evaluate to @code{#f}:
+The fundamental reason is that the continuation may escape during the
+evaluation of @code{(compute-100)}, allowing the rest of the body of
+@code{f2} to be executed @emph{again}:
@example
-(system-library-directory-pathname "shared")
-@end example
+@group
+(define keep)
-Note: when restoring a saved band, the Scheme executable must be
-configured with a large enough constant space and heap to hold the
-band's contents. If you attempt to restore a band using the
-@code{-band} option, and the band is too large, Scheme will write an
-error message that tells you the appropriate command-line options needed
-to load that band. If you attempt restore a too-large band using
-@code{disk-restore}, Scheme will signal an error, but will not provide
-the configuration information. In general, the configuration that was
-used to save a band is sufficiently large to restore it.
+(define (compute-100)
+ (call-with-current-continuation
+ (lambda (k)
+ (set! keep k)
+ 100)))
-@findex dump-world
-Another method for saving the world is the @code{dump-world} procedure,
-which accepts the same arguments as @code{disk-save} and works in much
-the same way. However, rather than dumping a band, @code{dump-world}
-saves an executable image, which is started just like any other program.
-This has the advantage of being considerably faster to start on some
-systems, but the image file is typically much larger than the
-corresponding band. However, @code{dump-world} is only supported for a
-few operating systems, and is not built into the distributed executable
-files --- if you wish to use @code{dump-world}, you must build your own
-executable file from the source code.
-Note that @code{dump-world} is unlikely to work with this release as MIT
-Scheme now uses shared libraries.
-
-@node Garbage Collection, Compiling Files, World Images, Top
-@chapter Garbage Collection
-
-This section describes procedures that control garbage collection. See
-@pxref{Customizing Scheme} for a discussion of how MIT Scheme uses
-memory.
+(define p (f2))
-@deffn {procedure+} gc-flip [safety-margin]
-Forces a garbage collection to occur. Returns the number of words of
-available storage after collection.
+(p) @result{} 100
+(keep -999) @result{} p @emph{re-define v and p}
+(p) @result{} -999
+@end group
+@end example
-@var{Safety-margin} determines the number of words of storage available
-for system tasks in-between detecting the need for a garbage collection
-and entering the garbage collector proper. An example of such a system
-task is changing the run-light to show `gc' when scheme is running under
-Emacs.
-@end deffn
+To avoid the inefficiency introduced to handle the general case, the
+compiler must prove that the continuation cannot possibly escape. The
+compiler knows that lambda expressions and constants do not let their
+continuations escape, so order the internal definitions so that
+definitions of the following forms come first:
-@deffn {procedure+} set-gc-notification! on?
-Controls whether the user is notified of garbage collections. If
-@var{on?} is @code{#F}, the user is not notified, otherwise the user is
-notified. The default is no notification.
+@example
+@group
+(define x '@emph{something})
+(define x (lambda (...) ...))
+(define (f u v) ...)
+@end group
+@end example
-The notification appears as a single line like the following, showing
-how many garbage collections have occurred, the time taken to perform the
-garbage collection and the free storage remaining (in words) after
-collection.
+@node Global variables, Fixnum arithmetic, Coding style, Efficiency Tips
+@subsection Global variables
+
+@cindex variable caches
+@cindex reference traps
+Compiled code usually accesses variables in top-level first-class
+environments via @emph{variable caches}. Each compiled procedure has a
+set of variable caches for the global variables that it uses. There are
+three kinds of variable cache - read caches for getting the value of a
+variable (referencing the variable), write caches for changing the
+value, and execute caches for calling the procedure assigned to that
+variable.
+
+Sometimes the variable caches contain special objects, called reference
+traps, that indicate that the operation cannot proceed normally and
+must either be completed by the system (in order to keep the caches
+coherent) or must signal an error. For example, the assignment
@example
-GC 5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346
+(set! newline my-better-newline)
@end example
-To operate comfortably, the amount of free storage after garbage
-collection should be a substantial proportion of the heap size. If the
-percentage CPU time is consistently high (over 20%), you should consider
-running with a larger heap. A rough rule of thumb to halve the GC
-overhead is to take the amount of free storage, divide by 1000, and add
-this figure to the current value used for the @samp{-heap} command line
-option. Unfortunately there is no way to adjust the heap size without
-restarting Scheme.
-@end deffn
+will cause the system to go to each compiled procedure that calls
+@code{newline} and update its execute cache to call the new procedure.
+Obviously you want to avoid updating hundreds of of execute caches in a
+critical loop. Using @code{fluid-let} to temporarily redefine a
+procedure has the same inefficiency (but twice!).
+
+To behave correctly in all situations, each variable reference or
+assignment must check for the reference traps.
+
+Sometimes you can prove that the variable (a) will always be bound, (b)
+will always be assigned and (c) there will never be any compiled calls
+to that variable. The compiler can't prove this because it assumes that
+other, independently compiled, files might be loaded that invalidate
+these assumptions.
+If you know that these conditions hold, the following declarations can
+speed up and reduce the size of a program that uses global variables.
-@deffn purify item [pure-space? [queue?]]
-@deffnx flush-purification-queue!
-** We should say something about these **
+@deffn {declaration+} ignore-reference-traps variables
+This declaration tells the compiler that it need not check for
+reference-trap objects when referring to the given @var{variables}.
+If any of the @var{variables} is unbound or unassigned then a variable
+reference will yield a reference-trap object rather than signaling an
+error. This declaration is relatively safe: the worst that can happen
+is that a reference-trap object finds its way into a data structure
+(e.g. a list) or into interpreted code, in which case it will probably
+cause some `unrelated' variable to mysteriously become unbound or
+unassigned.
@end deffn
+@deffn {declaration+} ignore-assignment-traps variables
+This declaration tells the compiler that it need not check for
+reference-trap objects when assigning to the given @var{variables}. An
+assignment to a variable that ignores assignment traps can cause a great
+deal of trouble. If there is a compiled procedure call anywhere in the
+system to this variable, the execute caches will not be updated, causing
+an inconsistency between the value used for the procedure call and the
+value seen by reading the variable. This mischief is compounded by the
+fact that the assignment can cause other assignments that were compiled
+with checks to behave this way too.
+@end deffn
-@node Compiling Files, GNU Emacs Interface, Garbage Collection, Top
-@chapter Compiling Files
+The @var{variables} are specified with expressions from the following
+set language:
-Note: the procedures described in this section are only available in the
-@file{compiler.com} world image. Furthermore, @code{cf} is only
-available on machines that support native-code compilation.
+@deffn {variable-specification} set name ...
+All of the explicitly listed names.
+@end deffn
-@menu
-* Compilation Procedures::
-* Declarations::
-* Efficiency Tips::
-@end menu
+@deffn {variable-specification} all
+@deffnx {variable-specification} none
+@deffnx {variable-specification} free
+@deffnx {variable-specification} bound
+@deffnx {variable-specification} assigned
+These expressions name sets of variables. @code{all} is the set of all
+variables, @code{none} is the empty set, @code{free} is all of the
+variables bound outside the current block, @code{bound} is all of the
+variables bound in the current block and @code{assigned} is all of the
+variables for which there exists an assignment (i.e.@ @code{set!}).
+@end deffn
-@node Compilation Procedures, Declarations, Compiling Files, Compiling Files
-@section Compilation Procedures
+@deffn {variable-specification} union set1 set2
+@deffnx {variable-specification} intersection set1 set2
+@deffnx {variable-specification} difference set1 set2
-@deffn {procedure+} cf filename [destination]
-This is the program that transforms a source-code file into native-code
-binary form. If @var{destination} is not given, as in
+For example, to ignore reference traps on all the variables except
+@var{x}, @var{y} and any variable that is assigned to
-@lisp
-(cf "foo")
-@end lisp
+@example
+@group
+(declare (ignore-reference-traps
+ (difference all (union assigned (set x y)))))
+@end group
+@end example
+@end deffn
+@c
+@c Note: The scoping of @code{ignore-reference-traps} and
+@c @code{ignore-assignment-traps} differs between version of the compiler.
+@c MIT Scheme version 8.0 (Liar
+@c version 5.0) has true block scoping, thus the declaration takes effect
+@c only within the procedure or @code{let} in which the declaration
+@c occurs. This makes it possible to control individual variable
+@c references, for example:
+@c
+@c @example
+@c @group
+@c (let ()
+@c (declare (ignore-reference-traps x))
+@c x)
+@c @end group
+@c @end example
+@c
+@c In earlier versions, a declaration affects all uses of the variable.
+@c
+@c In all versions, top level declarations affect the whole source file.
-@noindent
-@code{cf} compiles the file @file{foo.scm}, producing the file
-@file{foo.com} (incidentally it will also produce @file{foo.bin},
-@file{foo.bci}, and possibly @file{foo.ext}). If you later evaluate
+@node Fixnum arithmetic, Flonum arithmetic, Global variables, Efficiency Tips
+@subsection Fixnum arithmetic
-@lisp
-(load "foo")
-@end lisp
+The usual arithmetic operations like @code{+} and @code{<} are called
+generic arithmetic operations because they work for all (appropriate)
+kinds of number.
-@noindent
-@file{foo.com} will be loaded rather than @file{foo.scm}.
+@cindex fixnum (defn)
+A @dfn{fixnum} is an exact integer that is small enough to fit in a
+machine word. In MIT Scheme, fixnums are typically 24 or 26 bits,
+depending on the machine; it is reasonable to assume that fixnums are at
+least 24 bits. Fixnums are signed; they are encoded using 2's
+complement.
-If @var{destination} is given, it says where the output files should go.
-If this argument is a directory, they go in that directory, e.g.:
+All exact integers that are small enough to be encoded as fixnums are
+always encoded as fixnums --- in other words, any exact integer that is
+not a fixnum is too big to be encoded as such. For this reason, small
+constants such as @code{0} or @code{1} are guaranteed to be fixnums. In
+addition, the lengths of and valid indexes into strings and vectors are
+also always fixnums.
-@lisp
-(cf "foo" "../bar/")
-@end lisp
+If you know that a value is always a small fixnum, you can substitute
+the equivalent fixnum operation for the generic operation. However,
+care should be exercised: if used improperly, these operations can
+return incorrect answers, or even malformed objects that confuse the
+garbage collector. The Scheme Reference Manual lists all the fixnum
+operations.
-@noindent
-will take @file{foo.scm} and generate the file @file{../bar/foo.com}.
-If @var{destination} is not a directory, it is the root name of the
-output:
+A fruitful area for inserting fixnum operations is in the index
+operations in tight loops.
+@c
+@c With the new compiler (MIT Scheme version 8.0), adding fixnum operations
+@c yourself is not always effective because the compiler sometimes can
+@c figure out that a value just has to be a fixnum and replaces the generic
+@c operation with the fixnum one. For example, in the following code, the
+@c compiler knows that the result of @code{vector-length} is always a
+@c fixnum, and so replaces @code{-} with @code{fix:-}.
+@c
+@c @example
+@c (define (last-index v) (- (vector-length v) 1))
+@c @end example
+@c
+@c In the following example the compiler replaces @code{+} with
+@c @code{fix:+} because it knows that if @var{k} was not a fixnum then the
+@c @code{vector-ref} was an error:
+@c
+@c @example
+@c @group
+@c (define (ref-inc v k)
+@c (display (vector-ref v k))
+@c (+ k 1))
+@c @end group
+@c @end example
+@c
+@c Unfortunately there is no reasonable way to tell which
+@c operations the compiler replaces.
-@lisp
-(cf "foo" "bar")
-@end lisp
+@node Flonum arithmetic, , Fixnum arithmetic, Efficiency Tips
+@subsection Flonum arithmetic
+@c
+@c !INCOMPLETE
-@noindent
-takes @file{foo.scm} and generates @file{bar.com}.
-@end deffn
+Getting efficient flonum arithmetic is much more complicated and harder
+than getting efficient fixnum arithmetic.
-About the @file{.bci} files: these files contain the debugging
-information that Scheme uses when you call @code{debug} to examine
-compiled code. When you load a @file{.com} file, Scheme remembers where
-it was loaded from, and when the debugger (or @code{pp}) looks at the
-compiled code from that file, it attempts to find the @file{.bci} file
-in the same directory from which the @file{.com} file was loaded. Thus
-it is a good idea to leave these files together.
+@subsubheading Flonum consing
-@file{.bci} files are stored in a compressed format.
-The debugger has to uncompress the files when it looks at them,
-and on a slow machine this can take a noticeable time.
-The system takes steps to reduce the impact of this behaviour:
-debugging information is cached in memory,
-and uncompressed versions of @file{.bci} files are kept around.
-The default behavior is that a temporary file is created and the
-@file{.bci} file is uncompressed into it. The temporary file is kept
-around for a while afterwards, and during that time if the uncompressed
-@file{.bci} file is needed the temporary file is used. Each such
-reference updates an `access time' that is associated with the temporary
-file. The garbage collector checks the access times of all such
-temporary files, and deletes any that have not been accessed in five
-minutes or more. All of the temporaries are deleted automatically when
-the Scheme process is killed.
-
-Two other behaviors are available. One of them uncompresses the @file{.bci}
-file each time it is referenced, and the other uncompresses the @file{.bci}
-file and writes it back out as a @file{.bif} file (the old default).
-The @file{.bif} file remains after Scheme exits.
-The time interval and the behavior are controlled by variables. (These
-variables are not in the global environment; perhaps they should be.
-They are in the @code{(runtime compiler-info)} package environment.)
+@cindex flonum consing
+One of the main disadvantages of generic arithmetic is that not all
+kinds of number fit in a machine register.
+Flonums have to be @dfn{boxed} because a 64 bit @sc{ieee} floating-point
+number (the representation that MIT Scheme uses) does not fit in a
+regular machine word.
+This is true even on 64 bit architectures because some extra bits are
+needed to distinguish floating-point numbers from other objects like
+pairs and strings.
+Values are boxed by storing them in a small record in the heap.
+Every floating-point value that you see at the @sc{repl} is boxed.
+Floating-point values are unboxed only for short periods of time when
+they are in the machine's floating-point unit and actual floating-point
+operations are being performed.
+
+Numerical calculations that happen to be using floating-point numbers
+cause many temporary floating-point numbers to be allocated. It is not
+uncommon for numerical programs to spend over half of their time creating
+and garbage collecting the boxed flonums.
-@defvr {variable+} *save-uncompressed-files?*
-This variable affects what happens when @file{.bci} files are
-uncompressed. It allows a trade-off between performance and disk space.
-There are three possible values:
+Consider the following procedure for computing the distance of a point
+@var{(x,y)} from the origin.
-@table @code
-@item #f
-The uncompressed versions of @file{.bci} files are never saved. Each
-time the information is needed the @file{.bci} file is uncompressed.
-This option requires the minimum amount of disk space and is the
-slowest.
+@example
+@group
+(define (distance x y)
+ (sqrt (+ (* x x) (* y y))))
+@end group
+@end example
-@item automatic
-Uncompressed versions of @file{.bci} files are kept as temporary files.
-The temporary files are deleted when Scheme exits, and if they have not
-been used for a while. This is the default.
+The call @code{(distance 0.3 0.4)} returns a new, boxed flonum, 0.5.
+The calculation also generates three intermediate boxed flonums. This
+next version works only for flonum inputs, generates only one boxed
+flonum (the result) and runs eight times faster:
-@item #t
-The @file{.bci} files are uncompressed to permanent @file{.bif} files.
-These files remain on disk after Scheme exits, and are rather large -
-about twice the size of the corresponding @file{.bci} files. If you
-choose this option and you are running out of disk space you may delete
-the @file{.bif} files. They will be regenerated as needed.
-@end table
-@end defvr
+@example
+@group
+(define (flo:distance x y)
+ (flo:sqrt (flo:+ (flo:* x x) (flo:* y y))))
+@end group
+@end example
-@defvr {variable+} *uncompressed-file-lifetime*
-The minimum length of time that a temporary uncompressed version of
-a @file{.bci} file will stay on disk after it is last used.
-The time is in milliseconds; the default is @samp{300000} (five
-minutes).
-@end defvr
+Note that @code{flo:} operations are usually effective only within a
+single arithmetic expression. If the expression contains conditionals
+or calls to procedures then the values tend to get boxed anyway.
+@c
+@c @subsubheading A safer alternative
+@c
+@c An alternative to putting in @code{flo:} operations yourself is to let
+@c the compiler try.
+@c In the next definition of @code{distance}, the programmer explicitly
+@c tests for flonum arguments and duplicates the expression.
+@c
+@c The compiler compiles the expressions differently: for the first
+@c expression it knows from the conditional that @var{x} and @var{y} are
+@c flonums and will replace both @code{*} and the @code{+} operators with
+@c flonum operators.
+@c It doesn't replace the @code{sqrt} operator, though, as it doesn't know
+@c that sums of squares of reals are non-negative.
+@c
+@c This approach has the advantage of being completely safe, and
+@c @code{distance} will still work for other kinds of number.
+@c
+@c @example
+@c @group
+@c (define (distance x y)
+@c (if (and (flo:flonum? x) (flo:flonum? y))
+@c (sqrt (+ (* x x) (* y y)))
+@c (sqrt (+ (* x x) (* y y)))))
+@c @end group
+@c @end example
+@c
+@c This approach is effective only for MIT Scheme version 8.0 and later.
+@c Earlier versions do not do this kind of type analysis.
-@defvr {variable+} load-debugging-info-on-demand?
-If this variable is @file{#f}, then printing a compiled procedure
-will print the procedure's name only if the debugging information for
-that procedure is already loaded. Otherwise, it will force the
-loading of the debugging information.
-The default value is @code{#f}.
-@end defvr
+@subsubheading Flonum vectors
-@deffn {procedure+} sf filename [destination]
-@code{sf} is the program that transforms a source-code file into binary
-SCode form; it is used on machines that do not support native-code
-compilation. It performs numerous optimizations that can make your
-programs run considerably faster than unoptimized interpreted code.
-Also, the binary files that it generates load very quickly compared to
-source-code files.
+Flonum vectors are vectors that contain only floating-point values, in
+much the same way as a string is a `vector' containing only character
+values.
-The simplest way to use @code{sf} is just to say:
+Flonum vectors have the advantages of compact storage (about half
+that of a conventional vector of flonums) and judicious use of flonum
+vectors can decrease flonum consing.
-@lisp
-(sf @var{filename})
-@end lisp
+The disadvantages are that flonum vectors are incompatible with ordinary
+vectors, and if not used carefully, can increase flonum consing. Flonum
+vectors are a pain to use because they require you to make a decision
+about the representation and stick with it, and it might not be easy to
+ascertain whether the advantages in one part of the program outweigh the
+disadvantages in another.
-@noindent
-This will cause your file to be transformed, and the resulting binary
-file to be written out with the same name, but with pathname type
-@code{"bin"}. If you do not specify a pathname type on the input file,
-@code{"scm"} is assumed.
+The flonum vector operations are:
-Like @code{load}, the first argument to @code{sf} may be a list of
-filenames rather than a single filename.
+@deffn {procedure+} flo:vector-cons n
+Create a flonum vector of length @var{N}.
+The contents of the vector are arbitrary and might not be valid
+floating-point numbers.
+The contents should not be used until initialized.
+@end deffn
-@code{sf} takes an optional second argument, which is the filename of
-the output file. If this argument is a directory, then the output file
-has its normal name but is put in that directory instead.
+@deffn {procedure+} flo:vector-ref flonum-vector index
+@deffnx {procedure+} flo:vector-set! flonum-vector index value
+@deffnx {procedure+} flo:vector-length flonum-vector
+These operations are analogous to the ordinary vector operations.
@end deffn
-@node Declarations, Efficiency Tips, Compilation Procedures, Compiling Files
-@section Declarations
-@cindex declarations
+@subsubheading Examples
-Several declarations can be added to your programs to help @code{cf} and
-@code{sf} make them more efficient.
+The following operation causes no flonum consing because the flonum is
+loaded directly from the flonum vector into a floating-point machine
+register, added, and stored again. There is no need for a temporary
+boxed flonum.
-@menu
-* Standard Names::
-* In-line Coding::
-* Replacement of Operators::
-* Reduction of Operators::
-@end menu
+@example
+(flo:vector-set v 0 (flo:+ (flo:vector-ref v 0) 1.2))
+@end example
-@node Standard Names, In-line Coding, Declarations, Declarations
-@subsection Standard Names
+In this next example, every time @code{g} is called, a new boxed flonum
+has to be created so that a valid Scheme object can be returned. If
+@code{g} is called more often than the elements of @var{v} are changed
+then an ordinary vector might be more efficient.
-Normally, all files have a line
+@example
+@group
+(define (g i)
+ (flo:vector-ref v i))
+@end group
+@end example
-@findex usual-integrations
-@lisp
-(declare (usual-integrations))
-@end lisp
+@subsubheading Common pitfalls
-@noindent
-near their beginning, which tells the compiler that free variables whose
-names are defined in @code{system-global-environment} will not be
-shadowed by other definitions when the program is loaded. If you
-redefine some global name in your code, for example @code{car},
-@code{cdr}, and @code{cons}, you should indicate it in the declaration:
+Pitfall 1:
+Make sure that your literals are floating-point constants:
-@lisp
-(declare (usual-integrations car cdr cons))
-@end lisp
+@example
+@group
+(define (f1 a) (flo:+ a 1))
+(define (f2 a) (flo:+ a 1.))
+@end group
+@end example
-You can obtain an alphabetically-sorted list of the names that the
-@code{usual-integrations} declaration affects by evaluating the
-following expression:
+@code{f1} will most likely cause a hardware error, and certainly give
+the wrong answer. @code{f2} is correct.
-@lisp
-(eval '(sort (append usual-integrations/constant-names
- usual-integrations/expansion-names)
- (lambda (x y)
- (string<=? (symbol->string x)
- (symbol->string y))))
- (->environment '(scode-optimizer)))
-@end lisp
+Pitfall 2:
+It is tempting to insert calls to @code{exact->inexact} to coerce values
+into flonums. This does not always work because complex numbers may be
+exact or inexact too. Also, the current implementation of
+@code{exact->inexact} is slow.
-@node In-line Coding, Replacement of Operators, Standard Names, Declarations
-@subsection In-line Coding
+Pitfall 3:
+A great deal of care has to be taken with the standard math procedures.
+For example, when called with a flonum, both @code{sqrt} and @code{asin}
+can return a complex number (e.g -1.5).
+@c
+@c @node Miscellaneous, , Flonum arithmetic, Efficiency Tips
+@c @subsection Miscellaneous
+@c
+@c @subsubheading @code{in-package} and declarations
+@c
+@c Declarations from outside of an @code{in-package} form do not apply to
+@c the body of the form.
+@c This is because, in general, the new package (environment) could be any
+@c package, including one that contains alternative definitions for the
+@c standard procedures.
+@c The declarations in the enclosing text might be meaningless in the
+@c @code{in-package} body.
+@c As the @code{usual-integrations} declaration is included in this rule,
+@c it is usually a good idea to repeat the declaration e.g@:.
+@c
+@c @example
+@c @group
+@c ...
+@c (in-package some-environment
+@c (declare (usual-integrations))
+@c ...)
+@c ...
+@c @end group
+@c @end example
-Another useful facility is the ability to in-line code procedure
-definitions. In fact, the compiler will perform full beta conversion,
-with automatic renaming, if you request it. Here are the relevant
-declarations:
+@node Debugging, GNU Emacs Interface, Compiling Programs, Top
+@chapter Debugging
-@deffn {declaration+} integrate name @dots{}
-The variables @var{name}s must be defined in the same file as this
-declaration. Any reference to one of the named variables that appears
-in the same block as the declaration, or one of its descendant blocks,
-will be replaced by the corresponding definition's value expression.
-@end deffn
+@strong{This chapter is out of date and will be revised}.
-@deffn {declaration+} integrate-operator name @dots{}
-Similar to the @code{integrate} declaration, except that it only
-substitutes for references that appear in the operator position of a
-combination. All other references are ignored.
-@end deffn
+This chapter is adapted from @cite{Don't Panic: A 6.001 User's Guide to
+the Chipmunk System}, by Arthur A. Gleckler.
-@deffn {declaration+} integrate-external filename
-Causes the compiler to use the top-level integrations provided by
-@var{filename}. @var{filename} should not specify a file type, and the
-source-code file that it names must have been previously processed by
-the compiler.
+@cindex bugs
+@cindex debugging
+Even computer software that has been planned carefully and written well
+may not always work correctly. Mysterious creatures called @dfn{bugs}
+may creep in and wreak havoc, leaving the programmer to clean up the
+mess. Some have theorized that a program fails only because its author
+made a mistake, but experienced computer programmers know that bugs are
+always to blame. This is why the task of fixing broken computer
+software is called @dfn{debugging}.
-If @var{filename} is a relative filename (the normal case), it is
-interpreted as being relative to the file in which the declaration
-appears. Thus if the declaration appears in file @file{/usr/cph/foo.scm},
-then the compiler looks for a file called @file{/usr/cph/@var{filename}.ext}.
+It is impossible to prove the correctness of any non-trivial program;
+hence the Cynic's First Law of Debugging:
-Note: When the compiler finds top-level integrations, it collects them
-and outputs them into an auxiliary file with extension @file{.ext}.
-This @file{.ext} file is what the @code{integrate-external} declaration
-refers to.
-@end deffn
+@quotation
+Programs don't become more reliable as they are debugged; the bugs just
+get harder to find.
+@end quotation
-@findex define-integrable
-@findex define
-Note that the most common use of this facility, in-line coding of
-procedure definitions, requires a somewhat complicated use of these
-declarations. Because this is so common, there is a special form,
-@code{define-integrable}, which is like @code{define} but performs the
-appropriate declarations. For example:
+@cindex breakpoints
+Scheme is equipped with a variety of special software for finding and
+removing bugs. The debugging tools include facilities for tracing a
+program's use of specified procedures, for examining Scheme
+environments, and for setting @dfn{breakpoints}, places where the
+program will pause for inspection.
-@lisp
-(define-integrable (foo-bar foo bar)
- (vector-ref (vector-ref foo bar) 3))
-@end lisp
+@cindex error
+Many bugs are detected when programs try to do something that is
+impossible, like adding a number to a symbol, or using a variable that
+does not exist; this type of mistake is called an @dfn{error}.
+Whenever an error occurs, Scheme prints an error message and starts a
+new @sc{repl}. For example, using a nonexistent variable @code{foo} will
+cause Scheme to respond
-Here is how you do the same thing without this special form: there
-should be an @code{integrate-operator} declaration for the procedure's
-name, and (internal to the procedure's definition) an @code{integrate}
-declaration for each of the procedure's parameters, like this:
+@example
+@group
+1 ]=> foo
-@lisp
-(declare (integrate-operator foo-bar))
+;Unbound variable: foo
+;To continue, call RESTART with an option number:
+; (RESTART 3) => Specify a value to use instead of foo.
+; (RESTART 2) => Define foo to a given value.
+; (RESTART 1) => Return to read-eval-print level 1.
-(define foo-bar
- (lambda (foo bar)
- (declare (integrate foo bar))
- (vector-ref (vector-ref foo bar) 3)))
-@end lisp
+2 error>
+@end group
+@end example
-The reason for this complication is as follows: the
-@code{integrate-operator} declaration finds all the references to
-@code{foo-bar} and replaces them with the lambda expression from the
-definition. Then, the @code{integrate} declarations take effect because
-the combination in which the reference to @code{foo-bar} occurred
-supplies code which is substituted throughout the body of the procedure
-definition. For example:
+Sometimes, a bug will never cause an error, but will still cause the
+program to operate incorrectly. For instance,
-@lisp
-(foo-bar (car baz) (cdr baz))
-@end lisp
+@example
+(prime? 7) @result{} #f
+@end example
-@noindent
-First use the @code{integrate-operator} declaration:
+In this situation, Scheme does not know that the program is misbehaving.
+The programmer must notice the problem and, if necessary, start the
+debugging tools manually.
-@lisp
-((lambda (foo bar)
- (declare (integrate foo bar))
- (vector-ref (vector-ref foo bar) 3))
- (car baz)
- (cdr baz))
-@end lisp
+There are several approaches to finding bugs in a Scheme program:
+
+@itemize @bullet
+@item
+Inspect the original Scheme program.
-@noindent
-Next use the internal @code{integrate} declaration:
+@item
+Use the debugging tools to follow your program's progress.
-@lisp
-((lambda (foo bar)
- (vector-ref (vector-ref (car baz) (cdr baz)) 3))
- (car baz)
- (cdr baz))
-@end lisp
+@item
+Edit the program to insert checks and breakpoints.
+@end itemize
@noindent
-Next notice that the variables @code{foo} and @code{bar} are not used,
-and eliminate them:
+Only experience can teach how to debug programs, so be sure to
+experiment with all these approaches while doing your own debugging.
+Planning ahead is the best way to ward off bugs, but when bugs do
+appear, be prepared to attack them with all the tools available.
-@lisp
-((lambda ()
- (vector-ref (vector-ref (car baz) (cdr baz)) 3)))
-@end lisp
+@menu
+* Subproblems and Reductions::
+* Debugger::
+* Debugging Aids::
+* Advising Procedures::
+@end menu
-@noindent
-Finally, remove the @code{((lambda () @dots{}))} to produce
+@node Subproblems and Reductions, Debugger, Debugging, Debugging
+@section Subproblems and Reductions
-@lisp
-(vector-ref (vector-ref (car baz) (cdr baz)) 3)
-@end lisp
+@cindex subproblem
+@cindex reduction
+@cindex subexpression
+Understanding the concepts of @dfn{reduction} and @dfn{subproblem} is
+essential to good use of the debugging tools. The Scheme interpreter
+evaluates an expression by @dfn{reducing} it to a simpler expression.
+In general, Scheme's evaluation rules designate that evaluation proceeds
+from one expression to the next by either starting to work on a
+@dfn{subexpression} of the given expression, or by reducing the entire
+expression to a new (simpler, or reduced) form. Thus, a history of the
+successive forms processed during the evaluation of an expression will
+show a sequence of subproblems, where each subproblem may consist of a
+sequence of reductions.
+For example, both @code{(+ 5 6)} and @code{(+ 7 9)} are subproblems of
+the following combination:
-@subsubheading Useful tip
-@cindex integrations, seeing effects of
-To see the effect of integration declarations (and of macros) on a
-source file, pretty-print the @file{.bin} file like this (be prepared
-for a lot of output).
+@example
+(* (+ 5 6) (+ 7 9))
+@end example
-@lisp
-(sf "foo.scm")
-(pp (fasload "foo.bin"))
-@end lisp
+If @code{(prime? n)} is true, then @code{(cons 'prime n)} is a reduction
+for the following expression:
-@node Replacement of Operators, Reduction of Operators, In-line Coding, Declarations
-@subsection Operator Replacement
+@example
+@group
+(if (prime? n)
+ (cons 'prime n)
+ (cons 'not-prime n))
+@end group
+@end example
-The @code{replace-operator} declaration is provided to inform the
-compiler that certain operators may be replaced by other operators
-depending on the number of arguments.
-For example:
+This is because the entire subproblem of the @code{if} expression can
+be reduced to the problem @code{(cons 'prime n)}, once we know that
+@code{(prime? n)} is true; the @code{(cons 'not-prime n)} can be
+ignored, because it will never be needed. On the other hand, if
+@code{(prime? n)} were false, then @code{(cons 'not-prime n)} would be
+the reduction for the @code{if} expression.
-@noindent
-Declaration:
+The @emph{subproblem level} is a number representing how far back in the
+history of the current computation a particular evaluation is. Consider
+@code{factorial}:
-@lisp
-(declare (replace-operator (map (2 map-2) (3 map-3))))
-@end lisp
+@example
+@group
+(define (factorial n)
+ (if (< n 2)
+ 1
+ (* n (factorial (- n 1)))))
+@end group
+@end example
@noindent
-Replacements:
+If we stop @code{factorial} in the middle of evaluating @code{(- n 1)},
+the @code{(- n 1)} is at subproblem level 0. Following the history of
+the computation ``upwards,'' @code{(factorial (- n 1))} is at subproblem
+level 1, and @code{(* n (factorial (- n 1)))} is at subproblem level 2.
+These expressions all have @emph{reduction number} 0. Continuing
+upwards, the @code{if} expression has reduction number 1.
-@lisp
-(map @var{f} @var{x} @var{y} @var{z}) @expansion{} (map @var{f} @var{x} @var{y} @var{z})
-(map @var{f} @var{x} @var{y}) @expansion{} (map-3 @var{f} @var{x} @var{y})
-(map @var{f} @var{x}) @expansion{} (map-2 @var{f} @var{x})
-(map @var{f}) @expansion{} (map @var{f})
-(map) @expansion{} (map)
-@end lisp
+Moving backwards in the history of a computation, subproblem levels and
+reduction numbers increase, starting from zero at the expression
+currently being evaluated. Reduction numbers increase until the next
+subproblem, where they start over at zero. The best way to get a feel
+for subproblem levels and reduction numbers is to experiment with the
+debugging tools, especially @code{debug}.
-@noindent
-Presumably @code{map-2} and @code{map-3} are efficient versions of
-@code{map} that are written for exactly two and three arguments
-respectively. All the other cases are not expanded but are handled by the
-original, general @code{map} procedure, which is less efficient because
-it must handle a variable number of arguments.
+@node Debugger, Debugging Aids, Subproblems and Reductions, Debugging
+@section The Debugger
-@deffn {declaration+} replace-operator name ...
+@cindex debugger
+@cindex continuation Browser
+@cindex browser, Continuation
+@findex debug
+There are three debuggers available with MIT Scheme. Two of them
+require and run under Edwin, and are described in that section of this
+document (@pxref{Edwin}). The third is command oriented, does not
+require Edwin, and is described here.
-The syntax of this declaration is
+The @dfn{debugger}, called @code{debug}, is the tool you should use when
+Scheme signals an error and you want to find out what caused the error.
+When Scheme signals an error, it records all the information necessary
+to continue running the Scheme program that caused the error; the
+debugger provides you with the means to inspect this information. For
+this reason, the debugger is sometimes called a @dfn{continuation
+browser}.
-@lisp
-(replace-operator
- (@var{name}
- (@var{nargs1} @var{value1})
- (@var{nargs2} @var{value2})
- ...))
-@end lisp
+Here is the transcript of a typical Scheme session, showing a user
+evaluating the expression @code{(fib 10)}, Scheme responding with an
+unbound variable error for the variable @code{fob}, and the user
+starting the debugger:
-where
+@example
+@group
+1 ]=> (fib 10)
-@itemize @bullet
-@item
-@var{name} is a symbol.
+;Unbound variable: fob
+;To continue, call RESTART with an option number:
+; (RESTART 3) => Specify a value to use instead of fob.
+; (RESTART 2) => Define fob to a given value.
+; (RESTART 1) => Return to read-eval-print level 1.
-@item
-@var{nargs1}, @var{nargs2} etc.@: are non-negative integers, or one of the
-following symbols: @code{any}, @code{else} or @code{otherwise}.
+2 error> (debug)
-@item
-@var{value1}, @var{value2} etc.@: are simple
-expressions in one of these forms:
+There are 6 subproblems on the stack.
-@table @code
-@item '@var{constant}
-A constant.
+Subproblem level: 0 (this is the lowest subproblem level)
+Expression (from stack):
+ fob
+Environment created by the procedure: FIB
+ applied to: (10)
+The execution history for this subproblem contains 1 reduction.
+You are now in the debugger. Type q to quit, ? for commands.
-@item @var{variable}
-A variable.
+3 debug>
+@end group
+@end example
-@item (primitive @var{primitive-name} @r{[}@var{arity}@r{]})
-The primitive procedure named @var{primitive-name}. The optional
-element @var{arity}, a non-negative integer, specifies the number of
-arguments that the primitive accepts.
+@noindent
+@cindex execution history
+This tells us that the error occurred while trying to evaluate the
+expression @code{fob} while running @code{(fib 10)}. It also tells us
+this is subproblem level 0, the first of 8 subproblems that are
+available for us to examine. The expression shown is marked ``(from
+stack)'', which tells us that this expression was reconstructed from the
+interpreter's internal data structures. Another source of information
+is the @dfn{execution history}, which keeps a record of expressions
+evaluated by the interpreter. The debugger informs us that the
+execution history has recorded some information for this subproblem,
+specifically a description of one reduction.
-@item (global @var{var})
-A global variable.
-@end table
-@end itemize
+@node Debugging Aids, Advising Procedures, Debugger, Debugging
+@section Debugging Aids
-The meanings of these fields are:
+An important step in debugging is to locate the piece of code from which
+the error is signalled. The Scheme debugger contains a history examiner
+and an environment examiner to aid the user in locating a bug.
-@itemize @bullet
-@item
-@var{name} is the name of the operator to be reduced. If is is not
-shadowed (for example, by a let) then it may be replaced according to
-the following rules.
+@deffn {special form+} bkpt message irritant
+Sets a breakpoint. When the breakpoint is encountered, @var{message}
+and @var{irritant} are typed and a read-eval-print loop is entered in
+the current environment. To exit from the breakpoint and proceed with
+the interrupted process, call the procedure @code{continue}. Sample
+usage:
-@item
-If the operator has @var{nargsN} arguments then it is replaced with a
-call to @var{valueN} with the same arguments.
+@example
+@group
+1 ]=> (begin (write-line 'foo)
+ (bkpt 'test-2 'test-3)
+ (write-line 'bar)
+ 'done)
-@item
-If the number of arguments is not listed, and one of the @var{nargsN} is
-@code{any}, @code{else} or @code{otherwise}, then the operation is
-replaced with a call to the corresponding @var{valueN}.
-Only one of the @var{nargsN} may be of this form.
+foo
+ test-2 test-3
+;To continue, call RESTART with an option number:
+; (RESTART 2) => Return from BKPT.
+; (RESTART 1) => Return to read-eval-print level 1.
-@item
-If the number of arguments is not listed and none of the @var{nargsN} is
-@code{any}, @code{else} or @code{otherwise}, then the operation is not
-replaced.
-@end itemize
-@end deffn
+2 bkpt> (+ 3 3)
-@node Reduction of Operators, , Replacement of Operators, Declarations
-@subsection Operator Reduction
+;Value: 6
-@findex reduce-operator
-The @code{reduce-operator} declaration is provided to inform the
-compiler that certain names are n-ary versions of binary operators.
-Here are some examples:
+2 bkpt> (proceed)
-@noindent
-Declaration:
+bar
+;Value: done
+@end group
+@end example
+@end deffn
-@lisp
-(declare (reduce-operator (cons* cons)))
-@end lisp
+@deffn {procedure+} pp object [output-port [as-code?]]
+@deffnx {procedure+} pa procedure
+@cindex inspecting procedures
+The @code{pp} procedure is described in the MIT Scheme Reference Manual.
+We just note here that, by default, MIT Scheme keeps debugging
+information, so @code{pp} is useful for looking at the source code of a
+procedure (compiled or interpreted).
-@noindent
-Replacements:
+@code{pa} prints the arguments of @var{procedure}. This can be used to
+remind yourself, for example, of the correct order of the arguments to a
+procedure.
-@lisp
-(cons* @var{x} @var{y} @var{z} @var{w}) @expansion{} (cons @var{x} (cons @var{y} (cons @var{z} @var{w}))),
-(cons* @var{x} @var{y}) @expansion{} (cons @var{x} @var{y})
-(cons* @var{x}) @expansion{} @var{x}
-(cons*) @error{} too few arguments
-@end lisp
+@example
+@group
+1 ]=> for-all?
+;Value 40: #[compiled-procedure 40 ("boole" #x6) #xC #x20ECB0]
-@noindent
-Declaration:
+1 ]=> (pa for-all?)
+(items predicate)
+;No value
-@lisp
-(declare (reduce-operator (list cons (null-value '() any))))
-@end lisp
+1 ]=> (pp for-all?)
+(named-lambda (for-all? items predicate)
+ (let loop ((items items))
+ (or (null? items)
+ (and (predicate (car items))
+ (loop (cdr items))))))
+@end group
+@end example
+@end deffn
-@noindent
-Replacements:
+@deffn {procedure+} where [obj]
+@cindex environments, examining
+@cindex inspecting environments
+@cindex examining environments
+The procedure @code{where} enters the environment examination system.
+This allows environments and variable bindings to be examined and
+modified. @code{where} accepts one-letter commands. The commands can
+be found by typing @kbd{?} to the @samp{where>} prompt. The optional
+argument, @var{obj}, is an object with an associated environment: an
+environment, a procedure, or a promise. If @var{obj} is omitted, the
+environment examined is the read-eval-print environment from which
+@code{where} was called (or an error or breakpoint environment if called
+from the debugger). If a procedure is supplied, @code{where} lets the
+user examine the closing environment of the procedure. This is useful
+for debugging procedure arguments and values.
+@end deffn
-@lisp
-(list @var{x} @var{y} @var{z} @var{w}) @expansion{} (cons @var{x} (cons @var{y} (cons @var{z} (cons @var{w} '()))))
-(list @var{x} @var{y}) @expansion{} (cons @var{x} (cons @var{y} '()))
-(list @var{x}) @expansion{} (cons @var{x} '())
-(list) @expansion{} '()
-@end lisp
+@deffn {procedure+} apropos string [package/env [search-parents?]]
+@cindex finding procedures
+@cindex procedures, finding
+@cindex help
+Search an environment for bound names containing @var{string} and print
+out the matching bound names. If @var{package/env} is specified, it
+must be an environment or package name, and it defaults to the current
+@sc{repl} environment. The flag @var{search-parents?} specifies whether
+the environment's parents should be included in the search. The default
+is @code{#f} if @var{package/env} is specified, and @code{#t} if
+@var{package/env} is not specified.
-@noindent
-Declaration:
+@example
+@group
+1 ]=> (apropos "search")
+#[package 41 (user)]
+#[package 33 ()]
+list-search-negative
+list-search-positive
+search-ordered-subvector
+search-ordered-vector
+vector-binary-search
+;No value
+@end group
+@end example
+@end deffn
-@lisp
-(declare (reduce-operator (- %- (null-value 0 single) (group left))))
-@end lisp
+@node Advising Procedures, , Debugging Aids, Debugging
+@section Advising Procedures
-@noindent
-Replacements:
+Giving advice to procedures is a powerful debugging technique.
+@code{trace} and @code{break} are useful examples of advice-giving
+procedures.
+Note that the advice system only works for interpreted procedures.
-@lisp
-(- @var{x} @var{y} @var{z} @var{w}) @expansion{} (%- (%- (%- @var{x} @var{y}) @var{z}) @var{w})
-(- @var{x} @var{y}) @expansion{} (%- @var{x} @var{y})
-(- @var{x}) @expansion{} (%- 0 @var{x})
-(-) @expansion{} 0
-@end lisp
+@deffn {procedure+} trace-entry procedure
+Causes an informative message to be printed whenever
+@var{procedure} is entered. The message is of the form
-@noindent
-Declaration:
+@example
+@group
+[Entering #[compound-procedure 1 foo]
+ Args: @var{val1}
+ @var{val2}
+ ...]
+@end group
+@end example
-@lisp
-(declare (reduce-operator (+ %+ (null-value 0 none) (group right))))
-@end lisp
+where @var{val1}, @var{val2} etc.@: are the evaluated arguments supplied
+to the procedure.
+@end deffn
-@noindent
-Replacements:
+@deffn {procedure+} trace-exit procedure
+Causes an informative message to be printed when @var{procedure}
+terminates. The message contains the procedure, its argument values,
+and the value returned by the procedure.
+@end deffn
-@lisp
-(+ @var{x} @var{y} @var{z} @var{w}) @expansion{} (%+ @var{x} (%+ @var{y} (%+ @var{z} @var{w})))
-(+ @var{x} @var{y}) @expansion{} (%+ @var{x} @var{y})
-(+ @var{x}) @expansion{} @var{x}
-(+) @expansion{} 0
-@end lisp
+@deffn {procedure+} trace-both procedure
+@deffnx {procedure+} trace procedure
+Equivalent to calling both @code{trace-entry} and @code{trace-exit} on
+@var{procedure}. @code{trace} is the same as @code{trace-both}.
+@end deffn
-Note: This declaration does not cause an appropriate definition of
-@code{%+} (in the last example) to appear in your code. It merely
-informs the compiler that certain optimizations can be performed on
-calls to @code{+} by replacing them with calls to @code{%+}. You should
-provide a definition of @code{%+} as well, although it is not required.
+@deffn {procedure+} untrace-entry [procedure]
+Stops tracing the entry of @var{procedure}. If @var{procedure} is not
+given, the default is to stop tracing the entry of all entry-traced
+procedures.
+@end deffn
-@noindent
-Declaration:
+@deffn {procedure+} untrace-exit [procedure]
+Stops tracing the exit of @var{procedure}. If @var{procedure} is not
+given, the default is all exit-traced procedures.
+@end deffn
-@lisp
-(declare (reduce-operator (apply (primitive cons)
- (group right)
- (wrapper (global apply) 1))))
-@end lisp
+@deffn {procedure+} untrace [procedure]
+Stops tracing both the entry to and the exit from @var{procedure}. If
+@var{procedure} is not given, the default is all traced procedures.
+@end deffn
-@noindent
-Replacements:
+@deffn {procedure+} break-entry procedure
+Like @code{trace-entry} with the additional effect that a breakpoint is
+entered when @var{procedure} is invoked. Both @var{procedure}
+and its arguments can be accessed by calling the procedures
+@code{*proc*} and @code{*args*}, respectively. Use @code{restart} or
+@code{continue} to continue from a breakpoint.
+@end deffn
-@lisp
-(apply @var{f} @var{x} @var{y} @var{z} @var{w}) @expansion{} ((access apply ()) @var{f} (cons @var{x} (cons @var{y} (cons @var{z} @var{w}))))
-(apply @var{f} @var{x} @var{y}) @expansion{} ((access apply ()) @var{f} (cons @var{x} @var{y}))
-(apply @var{f} @var{x}) @expansion{} (apply @var{f} @var{x})
-(apply @var{f}) @expansion{} (apply @var{f})
-(apply) @expansion{} (apply)
-@end lisp
+@deffn {procedure+} break-exit procedure
+Like @code{trace-exit}, except that a breakpoint is entered just prior
+to leaving @var{procedure}. @var{Procedure}, its
+arguments, and the result can be accessed by calling the procedures
+@code{*proc*}, @code{*args*}, and @code{*result*}, respectively. Use
+@code{restart} or @code{continue} to continue from a breakpoint.
+@end deffn
-@deffn {declaration+} reduce-operator name ...
-The general format of the declaration is (brackets denote optional
-elements):
+@deffn {procedure+} break-both procedure
+@deffnx {procedure+} break procedure
+Sets a breakpoint at the beginning and end of @var{procedure}. This is
+@code{break-entry} and @code{break-exit} combined.
+@end deffn
-@lisp
-(reduce-operator
- (@var{name}
- @var{binop}
- @r{[}(group @var{ordering})@r{]}
- @r{[}(null-value @var{value} @var{null-option})@r{]}
- @r{[}(singleton @var{unop})@r{]}
- @r{[}(wrapper @var{wrap} @r{[}n@r{]})@r{]}
- @r{[}(maximum @var{m})@r{]}
- ))
-@end lisp
+@deffn {procedure+} unbreak [procedure]
+Discontinues the entering of a breakpoint on the entry to and exit from
+@var{procedure}. If @var{procedure} is not given, the default is
+all breakpointed procedures.
+@end deffn
-@noindent
-where
+@deffn {procedure+} unbreak-entry [procedure]
+Discontinues the entering of a breakpoint on the entry to
+@var{procedure}. If @var{procedure} is not given, the default is all
+entry-breakpointed procedures.
+@end deffn
-@itemize @bullet
-@item
-@var{n} and @var{m} are non-negative integers.
+@deffn {procedure+} unbreak-exit [procedure]
+Discontinues the entering of a breakpoint on the exit from
+@var{procedure}. If @var{procedure} is not given, the default is all
+exit-breakpointed procedures.
+@end deffn
-@item
-@var{name} is a symbol.
+The following three procedures are valid only within the dynamic extent
+of a breakpoint. In other words, don't call them unless you are stopped
+inside a breakpoint.
-@item
-@var{binop}, @var{value}, @var{unop}, and @var{wrap} are simple
-expressions in one of these forms:
+@deffn {procedure+} *proc*
+Returns the procedure in which the breakpoint has stopped.
+@end deffn
-@table @code
-@item '@var{constant}
-A constant.
+@deffn {procedure+} *args*
+Returns the arguments to the procedure in which the breakpoint has
+stopped. The arguments are returned as a list.
+@end deffn
-@item @var{variable}
-A variable.
+@deffn {procedure+} *result*
+Returns the result yielded by the procedure in which the breakpoint has
+stopped. This is valid only when in an exit breakpoint.
+@end deffn
-@item (primitive @var{primitive-name} @r{[}@var{arity}@r{]})
-The primitive procedure named @var{primitive-name}. The optional
-element @var{arity} specifies the number of arguments that the primitive
-accepts.
+The following procedures install @dfn{advice} procedures that are called
+when the advised procedure is entered or exited. An entry-advice
+procedure must accept three arguments: the advised procedure, a list of
+the advised procedure's arguments, and the advised procedure's
+application environment (that is, the environment in which the
+procedure's formal parameters are bound). An exit-advice procedure must
+accept four arguments: the advised procedure, a list of the advised
+procedure's arguments, the result yielded by the advised procedure, and
+the advised procedure's application environment.
+
+Note that the trace and breakpoint procedures described above are all
+implemented by means of the more general advice procedures, so removing
+advice from an advised procedure will also remove traces and
+breakpoints.
+
+@deffn {procedure+} advise-entry procedure advice
+@var{Advice} must be an entry-advice procedure. @var{Advice} is
+attached to @var{procedure}, so that whenever @var{procedure} is
+entered, @var{advice} is called.
+@end deffn
-@item (global @var{var})
-A global variable.
-@end table
+@deffn {procedure+} advise-exit procedure advice
+@var{Advice} must be an exit-advice procedure. @var{Advice} is attached
+to @var{procedure}, so that whenever @var{procedure} returns,
+@var{advice} is called.
+@end deffn
-@item
-@var{null-option} is either @code{always}, @code{any}, @code{one},
-@code{single}, @code{none}, or @code{empty}.
+@deffn {procedure+} advice procedure
+Returns the advice procedures, if any, that are attached to
+@var{procedure}. This is returned as a list of two lists: the first
+list is all of the entry-advice procedures attached to @var{procedure},
+and the second is all of the exit-advice procedures.
+@end deffn
-@item
-@var{ordering} is either @code{left}, @code{right}, or
-@code{associative}.
-@end itemize
+@deffn {procedure+} unadvise-entry [procedure]
+Removes all entry-advice procedures from @var{procedure}. If
+@var{procedure} is not given, the default is all entry-advised
+procedures.
+@end deffn
-@noindent
-The meaning of these fields is:
+@deffn {procedure+} unadvise-exit [procedure]
+Removes exit-advice procedures from @var{procedure}. If @var{procedure}
+is not given, the default is all exit-advised procedures.
+@end deffn
-@itemize @bullet
-@item
-@var{name} is the name of the n-ary operation to be reduced.
+@deffn {procedure+} unadvise [procedure]
+Removes all advice procedures from @var{procedure}. This is a
+combination of @code{unadvise-entry} and @code{unadvise-exit}. If
+@var{procedure} is not given, the default is all advised procedures.
+@end deffn
-@item
-@var{binop} is the binary operation into which the n-ary operation is to
-be reduced.
+@node GNU Emacs Interface, Edwin, Debugging, Top
+@chapter GNU Emacs Interface
-@item
-The @code{group} option specifies whether @var{name} associates to the
-right or left.
+There is an interface library, called @file{xscheme}, distributed with
+MIT Scheme and GNU Emacs, which facilitates running Scheme as a
+subprocess of Emacs. If you wish to use this interface, please install
+the version of @file{xscheme.el} that comes with MIT Scheme, as it is
+guaranteed to be correct for your version of Scheme.
-@item
-The @code{null-value} option specifies a value to use in the following
-cases:
+Note that this interface is supported under Unix only. We have explored
+the possibility of making it work under OS/2 and concluded that it is
+impossible.
-@table @code
-@item none
-@itemx empty
-When no arguments are supplied to @var{name}, @var{value} is returned.
+@findex run-scheme
+@findex -emacs
+To invoke Scheme from Emacs, use @kbd{M-x run-scheme}, which is defined
+when either of the libraries @file{scheme} or @file{xscheme} is loaded.
+You may give @code{run-scheme} a prefix argument, in which case it will
+allow you to edit the command line that is used to invoke Scheme.
+@emph{Do not} remove the @samp{-emacs} option!
-@item one
-@itemx single
-When a single argument is provided to @var{name}, @var{value} becomes
-the second argument to @var{binop}.
+@emph{Note carefully:} In Emacs 19, the @code{run-scheme} command
+exists, but is different from the one described here! In order to get
+this interface, you must load the @file{xscheme} library before
+executing @code{run-scheme}.
-@item any
-@itemx always
-@var{binop} is used on the ``last'' argument, and @var{value} provides
-the remaining argument to @var{binop}.
-@end table
+@findex scheme-interaction-mode
+Scheme will be started up as a subprocess in a buffer called
+@samp{*scheme*}. This buffer will be in @code{scheme-interaction-mode}
+and all output from the Scheme process will go there. The mode line for
+the @samp{*scheme*} buffer will have this form:
-In the above options, when @var{value} is supplied to @var{binop}, it is
-supplied on the left if grouping to the left, otherwise it is supplied
-on the right.
+@example
+--**-*scheme*: 1 [Evaluator] (Scheme Interaction: input)------
+@end example
-@item
-The @code{singleton} option specifies a function, @var{unop}, to be
-invoked on the single argument left. This option supersedes the
-@code{null-value} option, which can only take the value @code{none}.
+@noindent
+@cindex level number, REPL
+The first field, showing @samp{1} in this example, is the level number.
-@item
-The @code{wrapper} option specifies a function, @var{wrap}, to be
-invoked on the result of the outermost call to @var{binop} after the
-expansion.
-If @var{n} is provided it must be a non-negative integer indicating a number
-of arguments that are transferred verbatim from the original call to
-the wrapper. They are passed to the left of the reduction.
+@noindent
+The second field, showing @samp{[Evaluator]} in this example, describes
+the type of @sc{repl} that is running. Other values include:
-@item
-The maximum option specifies that calls with more than @var{m} arguments
-should not be reduced.
-@end itemize
-@end deffn
+@example
+@group
+[Debugger]
+[Where]
+@end group
+@end example
-@node Efficiency Tips, , Declarations, Compiling Files
-@section Efficiency Tips
+@noindent
+The @dfn{mode} after @samp{Scheme Interaction} is one of:
-How you write your programs can have a large impact on how efficiently the
-compiled program runs. The most important thing to do, after choosing
-suitable data structures, is to put the following declaration near the
-beginning of the file.
+@table @samp
+@item input
+Scheme is waiting for input.
-@lisp
-(declare (usual-integrations))
-@end lisp
+@item run
+Scheme is running an evaluation.
-Without this declaration the compiler cannot recognize any of the common
-operators and compile them efficiently.
+@item gc
+Scheme is garbage collecting.
+@end table
-The @code{usual-integrations} declaration is usually sufficient to get
-good quality compiled code.
+@findex scheme-mode
+When @file{xscheme} is loaded, @code{scheme-mode} is extended to include
+commands for evaluating expressions (do @kbd{C-h m} in any
+@code{scheme-mode} buffer for the most up-to-date information):
-If you really need to squeeze more performance out of you code then we
-hope that you find the following grab-bag of tips, hints and
-explanations useful.
+@table @kbd
+@item @key{ESC} o
+@kindex @key{ESC} o
+@findex xscheme-send-buffer
+Evaluates the current buffer (@code{xscheme-send-buffer}).
+@item @key{ESC} z
+@kindex @key{ESC} z
+@findex xscheme-send-definition
+Evaluates the current definition (@code{xscheme-send-definition}). This
+is also bound to @kbd{@key{ESC} C-x}.
-@menu
-* Coding style::
-* Global variables::
-* Fixnum arithmetic::
-* Flonum arithmetic::
-* Miscellaneous::
-@end menu
+@item @key{ESC} C-z
+@kindex @key{ESC} C-z
+@findex xscheme-send-region
+Evaluates the current region (@code{xscheme-send-region}).
-@node Coding style, Global variables, Efficiency Tips, Efficiency Tips
-@subsection Coding style
+@item C-x C-e
+@kindex C-x C-e
+@findex xscheme-send-previous-expression
+Evaluates the expression to the left of point
+(@code{xscheme-send-previous-expression}). This is also bound to
+@kbd{@key{ESC} @key{RET}}.
-@subsubheading Better predicates
+@item C-c C-s
+@kindex C-c C-s
+@findex xscheme-select-process-buffer
+Selects the @samp{*scheme*} buffer and places you at its end
+(@code{xscheme-select-process-buffer}).
-Consider the following implementation of @code{map} as might be found in
-any introductory book on Scheme:
+@item C-c C-y
+@kindex C-c C-y
+@findex xscheme-yank-previous-send
+Yanks the most recently evaluated expression, placing it at point
+(@code{xscheme-yank-previous-send}). This works only in the
+@samp{*scheme*} buffer.
+@end table
-@lisp
-(define (map f lst)
- (if (null? lst)
- '()
- (cons (f (car lst)) (map f (cdr lst)))))
-@end lisp
+The following commands provide interrupt capability:
-The problem with this definition is that at the points where @code{car}
-and @code{cdr} are called we still do not know that @var{lst} is a pair.
-The compiler must insert a type check, or if type checks are disabled,
-the program might give wrong results. Since one of the fundamental
-properties of @code{map} is that it transforms lists, we should make the
-relationship between the input pairs and the result pairs more apparent
-in the code:
+@table @kbd
+@item C-c C-c
+@kindex C-c C-c
+@findex xscheme-send-control-g-interrupt
+Like typing @kbd{C-g} when running Scheme without Emacs.@*
+(@code{xscheme-send-control-g-interrupt})
-@lisp
-(define (map f lst)
- (cond ((pair? lst)
- (cons (f (car lst)) (map f (cdr lst))))
- ((null? lst)
- '())
- (else
- ...) ; You decide - '() or an error?
-@end lisp
+@item C-c C-x
+@kindex C-c C-x
+@findex xscheme-send-control-x-interrupt
+Like typing @kbd{C-c C-x} when running Scheme without Emacs.@*
+(@code{xscheme-send-control-x-interrupt})
-Note also that the @code{pair?} case comes first because we expect that
-@code{map} will be called on lists which have, on average, length
-greater that one.
+@item C-c C-u
+@kindex C-c C-u
+@findex xscheme-send-control-u-interrupt
+Like typing @kbd{C-c C-u} when running Scheme without Emacs.@*
+(@code{xscheme-send-control-u-interrupt})
+@item C-c C-b
+@kindex C-c C-b
+@findex xscheme-send-breakpoint-interrupt
+Like typing @kbd{C-c C-b} when running Scheme without Emacs.@*
+(@code{xscheme-send-breakpoint-interrupt})
-@subsubheading Internal procedures
+@item C-c C-p
+@kindex C-c C-p
+@findex xscheme-send-proceed
+Like evaluating @code{(proceed)} or @code{(continue)}.@*
+(@code{xscheme-send-proceed})
+@end table
-Calls to internal procedures are faster than calls to global procedures.
-There are two things that make internal procedures faster: First, the
-procedure call is compiled to a direct jump to a known location, which
-is more efficient that jumping `via' a global binding.
-Second, there is a knock-on effect: since the compiler can see the
-internal procedure, the compiler can analyze it and possibly produce
-better code for other expressions in the body of the loop too:
+@node Edwin, Release Notes, GNU Emacs Interface, Top
+@chapter Edwin
-@lisp
-(define (map f original-lst)
- (let walk ((lst original-lst))
- (cond ((pair? lst)
- (cons (f (car lst)) (walk (cdr lst))))
- ((null? lst)
- '())
- (else
- (error "Not a proper list:" original-lst)))))
-@end lisp
+This chapter describes how to start Edwin, the MIT Scheme text editor.
+Edwin is very similar to GNU Emacs --- you should refer to the GNU Emacs
+manual for information about Edwin's commands and key bindings ---
+except that Edwin's extension language is MIT Scheme, while GNU Emacs
+extensions are written in Emacs Lisp. This manual does not discuss
+customization of Edwin.
+@menu
+* Starting Edwin::
+* Leaving Edwin::
+* Last Resorts::
+@end menu
-@subsubheading Internal defines
+@node Starting Edwin, Leaving Edwin, Edwin, Edwin
+@section Starting Edwin
-Internal definitions are a useful tool for structuring larger
-procedures. However, certain internal definitions can thwart compiler
-optimizations. Consider the following two procedures, where
-@code{compute-100} is some unknown procedure that we just know returns
-@samp{100}.
+To use Edwin, start Scheme with a world image containing Edwin (for
+example by giving the @samp{-edwin} command-line option), then call the
+procedure @code{edit}:
-@lisp
-(define (f1)
- (define v 100)
- (lambda () v))
+@deffn {procedure+} edit
+@deffnx {procedure+} edwin
+Enter the Edwin text editor. If entering for the first time, the editor
+is initialized (by calling @code{create-editor} with no arguments).
+Otherwise, the previously-initialized editor is reentered.
-(define (f2)
- (define v (compute-100))
- (lambda () v))
-@end lisp
+This procedure is sometimes evaluated from the command line to start
+Scheme with Edwin running:
-The procedure returned by @code{f1} will always give the same result and
-the compiler can prove this. The procedure returned by @code{f2} may
-return different results, even if @code{f2} is only called once.
-Because of this, the compiler has to allocate a memory cell to @code{v}.
-How can the procedure return different results?
+@example
+scheme -edwin -eval (edit)
+@end example
-The fundamental reason is that the continuation may escape during the
-evaluation of @code{(compute-100)}, allowing the rest of the body of
-@code{f2} to be executed @emph{again}:
+@findex edwin
+The procedure @code{edwin} is an alias for @code{edit}.
+@end deffn
-@lisp
-(define keep)
+@defvr {variable+} inhibit-editor-init-file?
+When Edwin is first initialized, it loads your init file (called
+@file{~/.edwin} under Unix, @file{edwin.ini} on PCs) if you have one. If
+the Scheme variable @code{inhibit-editor-init-file?} is true, however,
+your init file will not be loaded even if it exists. By default, this
+variable is false.
+@end defvr
-(define (compute-100)
- (call-with-current-continuation
- (lambda (k)
- (set! keep k)
- 100)))
+@deffn {procedure+} create-editor arg @dots{}
+Initializes Edwin, or reinitializes it if already initialized.
+@code{create-editor} is normally invoked automatically by @code{edit}.
-(define p (f2))
+If no @var{arg}s are given, the value of @code{create-editor-args} is
+used instead. In other words, the following are equivalent:
-(p) @result{} 100
-(keep -999) @result{} p @emph{re-define v and p}
-(p) @result{} -999
-@end lisp
+@example
+@group
+(create-editor)
+(apply create-editor create-editor-args)
+@end group
+@end example
-To avoid the inefficiency introduced to handle the general case, the
-compiler must prove that the continuation cannot possibly escape. The
-compiler knows that lambda expressions and constants do not let their
-continuations escape, so order the internal definitions so that
-definitions of the following forms come first:
+@noindent
+On the other hand, if @var{arg}s are given, they are used to update
+code@code{create-editor-args}, making the following equivalent:
-@lisp
-(define x '@emph{something})
-(define x (lambda (...) ...))
-(define (f u v) ...)
-@end lisp
+@example
+@group
+(apply create-editor @var{args})
+(begin (set! create-editor-args @var{args}) (create-editor))
+@end group
+@end example
+@end deffn
-@node Global variables, Fixnum arithmetic, Coding style, Efficiency Tips
-@subsection Global variables
+@defvr {variable+} create-editor-args
+This variable controls the initialization of Edwin. The following
+values are defined:
-@cindex variable caches
-@cindex reference traps
-Compiled code usually accesses variables in top level first-class
-environments via @emph{variable caches}. Each compiled procedure has a
-set of variable caches for the global variables that it uses. There are
-three kinds of variable cache - read caches for getting the value of a
-variable (referencing the variable), write caches for changing the
-value, and execute caches for calling the procedure assigned to that
-variable.
+@table @code
+@item (#f)
+This is the default. Creates a window of some default size, and uses
+that window as Edwin's main window. Under Unix, if X11 is not available
+or if the @samp{DISPLAY} environment variable is undefined, Edwin will
+run on Scheme's console.
-Sometimes the variable caches contain special objects, called reference
-traps, which indicate that the operation cannot proceed normally and
-must either be completed by the system (in order to keep the caches
-coherent) or must signal an error. For example, the assignment
+@item (x)
+Unix only. Creates an X window and uses it as Edwin's main window.
+This requires the @samp{DISPLAY} environment variable to have been set
+to the appropriate value before Scheme was started.
-@lisp
-(set! newline my-better-newline)
-@end lisp
+@item (x @var{geometry})
+Unix only. Like @code{(x)} except that @var{geometry} specifies the
+window's geometry in the usual way. @var{Geometry} must be a character
+string whose contents is an X geometry specification.
-will cause the system to go to each compiled procedure that calls
-@code{newline} and update its execute cache to call the new procedure.
-Obviously you want to avoid updating hundreds of of execute caches in a
-critical loop. Using @code{fluid-let} to temporarily redefine a
-procedure has the same inefficiency (but twice!).
+@item (console)
+Unix only. Causes Edwin to run on Scheme's console, or in Unix
+terminology, the standard input and output. If the console is not a
+terminal device, or is not powerful enough to run Edwin, an error will
+be signalled at initialization time.
+
+@item (pm)
+OS/2 only. Creates a Presentation Manager window and uses it as Edwin's
+main window.
-To behave correctly in all situations, each variable reference or
-assignment must check for the reference traps.
+@item (win32)
+Windows only. Creates a window and uses it as Edwin's main window.
+@end table
+@end defvr
-Sometimes you can prove that the variable (a) will always be bound, (b)
-will always be assigned and (c) there will never be any compiled calls
-to that variable. The compiler can't prove this because it assumes that
-other, independently compiled, files might be loaded which invalidate
-these assumptions.
-If you know that these conditions hold, the following declarations can
-speed up and reduce the size of a program that uses global variables.
+@node Leaving Edwin, Last Resorts, Starting Edwin, Edwin
+@section Leaving Edwin
-@deffn {declaration+} ignore-reference-traps variables
-If the variable is unbound or unassigned then a variable reference will
-yield a reference trap object instead of signaling an error. This
-declaration is relatively safe: The worst that can happen is that a
-reference trap object finds its way into a data structure (e.g. a list)
-or into interpreted code, in which case it will probably cause some
-`unrelated' variable to mysteriously become unbound or unassigned.
-@end deffn
+Once Edwin has been entered, it can be exited in the following ways:
-@deffn {declaration+} ignore-assignment-traps variables
-An assignment to a variable that ignores assignment traps can cause a
-great deal of trouble. If there is a compiled procedure call anywhere
-in the system to this variable, the execute caches will not be updated,
-causing an inconsistency between the value used for the procedure call
-and the value seen by reading the variable. This mischief is compounded
-by the fact that the assignment can cause other assignments that were
-compiled with checks to behave this way too.
-@end deffn
+@table @kbd
+@item C-x z
+@kindex C-x z
+@findex suspend-edwin
+Stop Edwin and return to Scheme (@code{suspend-edwin}). The call to the
+procedure @code{edit} that entered Edwin returns normally. A subsequent
+call to @code{edit} will resume Edwin where it was stopped.
-The @var{variables} are specified with expressions from the following
-set language:
+@item C-x c
+@kindex C-x c
+@findex save-buffers-kill-edwin
+Offer to save any modified buffers, then kill Edwin, returning to Scheme
+(@code{save-buffers-kill-edwin}). This is like the @code{suspend-edwin}
+command, except that a subsequent call to @code{edit} will reinitialize
+the editor.
-@deffn {variable-specification} set name ...
-All of the explicitly listed names.
-@end deffn
+@item C-x C-z
+@kindex C-x C-z
+@findex suspend-scheme
+Stop Edwin and suspend Scheme, returning control to the operating
+system's command interpreter (@code{suspend-scheme}). When Scheme is
+resumed (using the command interpreter's job-control commands), Edwin is
+automatically restarted where it was stopped. This command is identical
+to the @kbd{C-x C-z} command of GNU Emacs.
-@deffn {variable-specification} all
-@deffnx {variable-specification} none
-@deffnx {variable-specification} free
-@deffnx {variable-specification} bound
-@deffnx {variable-specification} assigned
-These expressions name sets of variables. @code{all} is the set of all
-variables, @code{none} is the empty set, @code{free} is all of the
-variables bound outside the current block, @code{bound} is all of the
-variables bound in the current block and @code{assigned} is all of the
-variables for which there exists an assignment (i.e.@ @code{set!}).
-@end deffn
+@item C-x C-c
+@kindex C-x C-c
+@findex save-buffers-kill-scheme
+Offer to save any modified buffers, then kill both Edwin and Scheme
+(@code{save-buffers-kill-scheme}). Control is returned to the operating
+system's command interpreter, and the Scheme process is terminated.
+This command is identical to the @kbd{C-x C-c} command of GNU Emacs.
+@end table
-@deffn {variable-specification} union set1 set2
-@deffnx {variable-specification} intersection set1 set2
-@deffnx {variable-specification} difference set1 set2
+@node Last Resorts, , Leaving Edwin, Edwin
+@section Last Resorts
-For example, to ignore reference traps on all the variables except
-@var{x}, @var{y} and any variable that is assigned to
+When Scheme exits abnormally it tries to save any unsaved Edwin buffers.
+The buffers are saved in an auto-save file in case the original is more
+valuable than the unsaved version. You can use the editor command
+@kbd{M-x recover-file} to recover the auto-saved version. The name
+used to specify an auto-save file is operating-system dependent: under
+Unix, and on PC file systems with long file names, @file{foo.scm} will
+be saved as @file{#foo.scm#}; on PC file systems with short file names,
+it will be saved as @file{foo.sav}.
-@example
-(declare (ignore-reference-traps
- (difference all (union assigned (set x y)))))
-@end example
+The following Scheme procedures are useful for recovering from bugs in
+Edwin's implementation. All of them are designed for use when Edwin is
+@emph{not} running --- they should not be used when Edwin is running.
+These procedures are designed to help Edwin's implementors deal with
+bugs during the implementation of the editor; they are not intended for
+casual use, but as a means of recovering from bugs that would otherwise
+require reloading the editor's world image from the disk.
+@deffn {procedure+} save-editor-files
+Examines Edwin, offering to save any unsaved buffers. This is useful if
+some bug caused Edwin to die while there were unsaved buffers, and you
+want to save the information without restarting the editor.
@end deffn
-Note: The scoping of @code{ignore-reference-traps} and
-@code{ignore-assignment-traps} differs between version of the compiler.
-MIT Scheme version 8.0 (Liar
-version 5.0) has true block scoping, thus the declaration takes effect
-only within the procedure or @code{let} in which the declaration
-occurs. This makes it possible to control individual variable
-references, for example:
+@deffn {procedure+} reset-editor
+Resets Edwin, causing it to be reinitialized the next time that
+@code{edit} is called. If you encounter a fatal bug in Edwin, a good
+way to recover is to first call @code{save-editor-files}, and then to
+call @code{reset-editor}. That should completely reset the editor to
+its initial state.
+@end deffn
-@example
-(let ()
- (declare (ignore-reference-traps x))
- x)
-@end example
+@deffn {procedure+} reset-editor-windows
+Resets Edwin's display structures, without affecting any of the buffers
+or their contents. This is useful if a bug in the display code causes
+Edwin's internal display data structures to get into an inconsistent
+state that prevents Edwin from running.
+@end deffn
-In earlier versions, a declaration affects all uses of the variable.
+@node Release Notes, Known Problems, Edwin, Top
+@appendix Release Notes
-In all versions, top level declarations affect the whole source file.
+The last full release of MIT Scheme was version 7.3.1 in 1994. The
+first section summarizes the changes that have occurred since version
+7.3.1. Following that are changes from previous versions.
-@node Fixnum arithmetic, Flonum arithmetic, Global variables, Efficiency Tips
-@subsection Fixnum arithmetic
+@menu
+* 7.4 News::
+* 7.3 News:: Changes from Release 7.2 to 7.3
+* 7.2 News:: Changes from Release 7.1 to 7.2
+@end menu
-The usual arithmetic operations like @code{+} and @code{<} are called
-generic arithmetic operations because they work for all (appropriate)
-kinds of number.
+@node 7.4 News, 7.3 News, Release Notes, Release Notes
+@section Changes from Release 7.3 to 7.4
-@cindex fixnum (defn)
-A @dfn{fixnum} is an exact integer that is small enough to fit in a
-machine word. In MIT Scheme, fixnums are typically 24 or 26 bits,
-depending on the machine; it is reasonable to assume that fixnums are at
-least 24 bits. Fixnums are signed; they are encoded using 2's
-complement.
+This highlights some of the more important changes to Scheme since the
+7.3.1 release. For complete details, see the @file{RCS.log} files in
+the source code.
-All exact integers that are small enough to be encoded as fixnums are
-always encoded as fixnums --- in other words, any exact integer that is
-not a fixnum is too big to be encoded as such. For this reason, small
-constants such as @code{0} or @code{1} are guaranteed to be fixnums. In
-addition, the lengths of and valid indexes into strings and vectors are
-also always fixnums.
+@noindent
+Changes to Scheme:
-If you know that a value is always a small fixnum, you can substitute
-the equivalent fixnum operation for the generic operation. However,
-care should be exercised: if used improperly, these operations can
-return incorrect answers, or even malformed objects that confuse the
-garbage collector. The Scheme Reference Manual lists all the fixnum
-operations.
+@itemize @bullet
+@item
+MIT Scheme is now supported under OS/2.
-A fruitful area for inserting fixnum operations is in the index
-operations in tight loops.
+@item
+Illegally-placed internal definitions now signal an error.
-With the new compiler (MIT Scheme version 8.0), adding fixnum operations
-yourself is not always effective because the compiler sometimes can
-figure out that a value just has to be a fixnum and replaces the generic
-operation with the fixnum one. For example, in the following code, the
-compiler knows that the result of @code{vector-length} is always a
-fixnum, and so replaces @code{-} with @code{fix:-}.
+@item
+Stream operations from the upcoming new edition of @sc{sicp} are
+implemented.
-@example
-(define (last-index v) (- (vector-length v) 1))
-@end example
+@item
+The @code{load-option} procedure is now extensible, allowing users to
+add their own options to the database.
-In the following example the compiler replaces @code{+} with
-@code{fix:+} because it knows that if @var{k} was not a fixnum then the
-@code{vector-ref} was an error:
+@item
+Daylight-savings-time information is now included in the decoded time
+data structure.
+@end itemize
-@example
-(define (ref-inc v k)
- (display (vector-ref v k))
- (+ k 1))
-@end example
+@noindent
+Changes to Edwin:
-Unfortunately there is no reasonable way to tell which
-operations the compiler replaces.
+@itemize @bullet
+@item
+Cut and paste between Edwin and the system's clipboard (in X11, the
+``selection'' mechanism) is now supported. This support is directly
+integrated into the kill and yank commands: killing some text (e.g.
+@kbd{C-w}, @kbd{C-k}, @kbd{C-M-k}) stores that text into the clipboard;
+yanking text (e.g. @kbd{C-y}, @kbd{M-y}) inserts text from the
+clipboard. This support is transparent in that it has no effect on
+Edwin except when some other program puts text into the clipboard.
+@item
+Old @sc{rcs} support has been replaced with @sc{vc} (``Version
+Control'') as in Emacs 19. @sc{vc} is significantly easier to use. At
+present, @sc{vc} supports only @sc{rcs}.
-@node Flonum arithmetic, Miscellaneous, Fixnum arithmetic, Efficiency Tips
-@subsection Flonum arithmetic
+@item
+New command: @kbd{M-x step-expression}; steps through the evaluation of
+a Scheme expression.
-!INCOMPLETE
+@item
+New command: @kbd{M-x grep}, as in Emacs.
-Getting efficient flonum arithmetic is much more complicated and harder
-than getting efficient fixnum arithmetic.
+@item
+@sc{rmail} and Unix mail files are now stored in Unix text format,
+regardless of the underlying operating system. This allows these files
+to be more easily transferred between operating systems.
-@subsubheading Flonum consing
+@item
+The editor variable @code{evaluate-in-inferior-repl} now defaults to
+@code{#t}.
-@cindex flonum consing
-One of the main disadvantages of generic arithmetic is that not all
-kinds of number fit in a machine register.
-Flonums have to be @dfn{boxed} because a 64 bit IEEE floating point
-number (the representation the MIT Scheme uses) does not fit in a
-regular machine word.
-This is true even on 64 bit architectures because some extra bits are
-needed to distinguish floating point numbers from other objects like
-pairs ans strings.
-Values are boxed by storing them in a small record in the heap.
-Every floating point value that you see at the REPL is boxed.
-Floating point values are unboxed only for short periods of time when
-they are in the machine's floating point unit and actual floating point
-operations are begin performed.
+@item
+Customizable imaging of characters is now supported. The per-buffer
+variable @code{char-image-strings} holds a vector of 256 strings that
+determine how characters are displayed. Using an approriate vector
+allows the use of fonts with extra characters, ``hex'' displays,
+compound characters for displaying @sc{iso} Latin text in plain
+@sc{ascii}, and lots of other tricks.
+@item
+Dired's commands are now more like those in Emacs 19.
-Numerical calculations that happen to be using floating point numbers
-cause many temporary floating point numbers to be allocated. It is not
-uncommon for numerical programs to spend over half of the time creating
-and garbage collecting the boxed flonums.
+@item
+Dired mode is no longer case-sensitive.
-Consider the following procedure for computing the distance of a point
-@var{(x,y)} from the origin.
+@item
+Dired now supports marking of multiple files. Many commands, such as
+@kbd{M}, @kbd{C}, and @kbd{R}, now work on the marked files if there are
+any.
-@example
-(define (distance x y)
- (sqrt (+ (* x x) (* y y))))
-@end example
+@item
+New command in Dired: @kbd{+} creates a new directory.
-The call @code{(distance 0.3 0.4)} returns a new, boxed flonum, 0.5.
-The calculation also generates three intermediate boxed flonums. This
-next version works only for flonum inputs, generates only one boxed
-flonum (the result) and runs eight times faster:
+@item
+OS/2 and Unix only: Fetching mail from a @sc{pop} server is now
+supported, using the @file{popclient} program as a subprocess. Supports
+three different @file{popclient} password schemes: standard, Debian
+GNU/Linux, and Kerberos V4. Do @kbd{M-x variable-apropos RET pop RET}
+to see the variables that control the use of the @file{popclient}
+program.
-@example
-(define (flo:distance x y)
- (flo:sqrt (flo:+ (flo:* x x) (flo:* y y))))
-@end example
+@item
+OS/2 and Unix only: Compressed files are now fully supported. Edwin can
+read, write, and append compressed files. Methods are provided to
+support the @file{gzip} and @file{compress} compression programs, using
+the suffixes @file{.gz} and @file{.Z}, respectively. If Edwin is
+attempting to open a file that doesn't exist, but it sees what appears
+to be a compressed version of that file, it opens the compressed file
+instead.
-Note that @code{flo:} operations are usually effective only within a
-single arithmetic expression. If the expression contains conditionals
-or calls to procedures then the values tend to get boxed anyway.
+@item
+OS/2 and Unix only: In Dired, @kbd{s} now toggles between alphabetic
+sorting and time sorting.
+@end itemize
+@noindent
+Changes Specific to Windows 3.1, Windows 95, and Windows NT:
-@subsubheading A safer alternative
+@itemize @bullet
+@item
+Long filenames are now supported.
-An alternative to putting in @code{flo:} operations yourself is to let
-the compiler try.
-In the next definition of @code{distance}, the programmer explicitly
-tests for flonum arguments and duplicates the expression.
+@item
+The network @file{\\@var{host}\@var{directory}} notation is now
+supported.
-The compiler compiles the expressions differently: for the first
-expression it knows from the conditional that @var{x} and @var{y} are
-flonums and will replace both @code{*} and the @code{+} operators with
-flonum operators.
-It doesn't replace the @code{sqrt} operator, though, as it doesn't know
-that sums of squares of reals are non-negative.
+@item
+Scheme no longer supports the @code{^Z} end-of-file convention for
+files. A @code{^Z} appearing in a file is treated as an ordinary
+character, and output files do not have @code{^Z} placed at their end.
-This approach has the advantage of being completely safe, and
-@code{distance} will still work for other kinds of number.
+@item
+The runtime system now has better heuristics for determining the
+user name and home directory.
-@example
-(define (distance x y)
- (if (and (flo:flonum? x) (flo:flonum? y))
- (sqrt (+ (* x x) (* y y)))
- (sqrt (+ (* x x) (* y y)))))
-@end example
+@item
+The catatonia timeout has been extended to 120 seconds --- much more
+reasonable on slow machines.
-This approach is effective only for MIT Scheme version 8.0 and later.
-Earlier versions do not do this kind of type analysis.
+@item
+Window text color now defaults to the system default rather than to
+black.
+@item
+The default window font family and size is now selectable by the
+environment variable @samp{MITSCHEME_FONT}.
-@subsubheading Flonum vectors
+@item
+@code{process-time-clock} now returns the process time, rather than the
+real time, under NT or any variant of Win32 that supports
+@code{GetProcessTimes}.
-Flonum vectors are vectors which contain only floating point values, in
-much the same way as a string is a `vector' containing only character
-values.
+@item
+A bug has been fixed in the directory reader in which the OS handle was
+never closed. This was manifested under Windows 3.1 as Edwin being
+unable to do filename completion or file saving after 32 handles were
+opened but never closed.
+@end itemize
-Flonum vectors have the advantages of compact storage (about half of
-that of a conventional vector of flonums) and judicious use of flonum
-vectors can decrease flonum consing.
+@noindent
+Changes Specific to Edwin under Windows:
-The disadvantages are that flonum vectors are incompatible with ordinary
-vectors, and if not used carefully, can increase flonum consing. Flonum
-vectors are a pain to use because they require you to make a decision
-about the representation and stick with it, and it might not be easy to
-ascertain whether the advantages in one part of the program outweigh the
-disadvantages in another.
+@itemize @bullet
+@item
+File systems with either long or short file names are now supported.
+Edwin modifies its behavior depending on the file-system type, for
+example, using Unix-style @file{.~@var{n}~} backup names with long
+files.
-The flonum vector operations are:
+@item
+Multiple Edwin screens are now supported.
-@deffn {procedure+} flo:vector-cons n
-Create a flonum vector of length @var{N}.
-The contents of the vector are arbitrary and might not be valid floating
-point numbers.
-The contents should not be used until initialized.
-@end deffn
+@item
+The handling of windows has been significantly improved; it is now
+faster and less buggy.
-@deffn {procedure+} flo:vector-ref flonum-vector index
-@deffnx {procedure+} flo:vector-set! flonum-vector index value
-@deffnx {procedure+} flo:vector-length flonum-vector
-These operations are analogous to the ordinary vector operations.
-@end deffn
+@item
+New Edwin commands include @kbd{M-x set-font}, @kbd{M-x
+set-default-font}, @kbd{M-x set-icon}, @kbd{M-x set-foreground-color}
+and @kbd{M-x set-background-color}.
+@end itemize
+@noindent
+Changes Specific to OS/2 (since the 7.4.1 release):
-@subsubheading Examples
+@itemize @bullet
+@item
+The main console window now supports a Copy command. Any text appearing
+on the window can be copied to the clipboard by marking it with the
+mouse and invoking the Copy command.
-The following operation causes no flonum consing because the flonum is
-loaded directly from the flonum vector into a floating point machine
-register, added, and stored again. There is no need for a temporary
-boxed flonum.
+@item
+The main console window now has a menu bar, which provides the following
+operations: Exit, Copy, Paste, Set font, and About.
-@example
-(flo:vector-set v 0 (flo:+ (flo:vector-ref v 0) 1.2))
-@end example
+@item
+The main console window now has a list of fonts that it tries to use to
+set the default font, rather than just @code{"4.System VIO"}. It tries
+these fonts in order until it finds one. This allows Scheme to be used
+on systems that don't support the @samp{System VIO} font, as is true of
+some non-US versions of OS/2.
-In this next example, every time @code{g} is called, a new boxed flonum
-has to be created so that a valid Scheme object can be returned. If
-@code{g} is called more often than the elements of @var{v} are changed
-then an ordinary vector might be more efficient.
+@item
+Closing the main console window using the window Close command now asks
+whether you want to kill Scheme or just close the window and leave
+Scheme running; usually you will want the former. Previously, it did
+the latter without asking.
-@example
-(define (g i)
- (flo:vector-ref v i))
-@end example
+@item
+All windows created by Scheme now have icons to give them a distinctive
+appearance when minimized.
+@item
+Compilation of the microcode is supported using IBM Visual Age C++,
+Watcom C/C++, or @sc{emx/gcc}.
+@item
+Unix file systems are supported specially, e.g. Linux @code{ext2} or
+Unix @sc{nfs}. End-of-line translation is not done for files on such
+file systems, so that the files are read and written properly.
-@subsubheading Common pitfalls
+@item
+The network @file{\\@var{host}\@var{directory}} notation is now
+supported.
+@end itemize
-Pitfall 1:
-Make sure that your literals are floating point constants:
+@noindent
+Changes Specific to Edwin under OS/2:
-@example
-(define (f1 a) (flo:+ a 1))
-(define (f2 a) (flo:+ a 1.))
-@end example
+@itemize @bullet
+@item
+The Close command on the window menu of an Edwin window now acts like
+@kbd{C-x C-c} if this is the only Edwin window for this process.
-@code{F1} will most likely cause a hardware error, and certainly give
-the wrong answer. @code{F2} is correct.
+@item
+In Dired, @kbd{S} now toggles between showing and hiding system/hidden
+files; these files are initially hidden.
+@item
+Dired has an @kbd{M} command to set the attributes of a file. It
+prompts for an attribute string such as @samp{+r} or @samp{-h} and makes
+the corresponding change to the file's attributes.
+@end itemize
-Pitfall 2:
-It is tempting to insert calls to @code{exact->inexact} to coerce values
-into flonums. This does not always work because complex numbers may be
-exact or inexact too. Also, the current implementation of
-@code{exact->inexact} is slow.
+@node 7.3 News, 7.2 News, 7.4 News, Release Notes
+@section Changes from Release 7.2 to 7.3
+This is an abbreviated list of the changes that have been incorporated
+in the 7.3 release since the (partial) 7.2 release.
-Pitfall 3:
-A great deal of care has to be taken with the standard math procedures.
-For example, when called with a flonum, both @code{sqrt} and @code{asin}
-can return a complex number (e.g -1.5).
+@itemize @bullet
+@item
+Support for MS Windows (3.1 and NT).
+@item
+Native compiled-code support for DEC Alpha.
+@item
+Compiler can now generate C code. This is used to support the Sun SPARC
+and IBM RS6000 architectures.
-@node Miscellaneous, , Flonum arithmetic, Efficiency Tips
-@subsection Miscellaneous
+@item
+Support for dynamic loading of compiled C code on several operating
+systems, including HP-UX, OSF/1, SunOS 4, and AIX.
-@subsubheading @code{in-package} and declarations
+@item
+New data structures: red/black trees and weight-balanced trees.
-Declarations from outside of an @code{in-package} form do not apply to
-the body of the form.
-This is because, in general, the new package (environment) could be nay
-package, including one which contains alternative definitions for the
-standard procedures.
-The declarations in the enclosing text might be meaningless in the
-@code{in-package} body.
-As the @code{usual-integrations} declaration is included in this rule,
-it is usually a good idea to repeat the declaration e.g@:.
+@item
+Redesign of hash tables makes them much faster and somewhat more
+flexible.
-@lisp
- ...
- (in-package some-environment
- (declare (usual-integrations))
- ...)
- ...
-@end lisp
+@item
+Completely new random-number generator. The interface to the
+random-number generator has been changed to be like that of Common Lisp.
+@item
+Record abstraction now uses a special @dfn{record} type to represent
+records (previously it used vectors). @code{define-structure} now
+creates records by default; these records are identical to those created
+with the record abstraction.
+@item
+@code{call-with-current-continuation} is now properly tail-recursive.
-@node GNU Emacs Interface, Edwin, Compiling Files, Top
-@chapter GNU Emacs Interface
+@item
+New command-line switch @code{-no-suspend-file} prevents the generation
+of @file{scheme_suspend} files.
-There is an interface library, called @code{xscheme}, distributed with
-MIT Scheme and GNU Emacs, which facilitates running Scheme as a
-subprocess of Emacs. If you wish to use this interface, please install
-the version of @file{xscheme.el} that comes with MIT Scheme, as it is
-guaranteed to be correct for your version of Scheme.
+@item
+Uncompression of compiled-code debugging information is now memoized
+to save time when doing many accesses to the same information (a
+common occurrence).
-@findex run-scheme
-@findex -emacs
-To invoke Scheme from Emacs, use @kbd{M-x run-scheme}, which is defined
-when either of the libraries @file{scheme} or @file{xscheme} is loaded.
-You may give @code{run-scheme} a prefix argument, in which case it will
-allow you to edit the command line that is used to invoke Scheme.
-@emph{Do not} remove the @code{-emacs} option!
+@item
+Constant space now grows automatically when needed.
-@findex scheme-interaction-mode
-Scheme will be started up as a subprocess in a buffer called
-@code{*scheme*}. This buffer will be in @code{scheme-interaction-mode}
-and all output from the Scheme process will go there. The mode line for
-the @code{*scheme*} buffer will have this form:
+@item
+New procedures:
@example
---**-*scheme*: 1 [Evaluator] (Scheme Interaction: input)------
+call-with-values @r{;replaces} with-values
+current-load-pathname
+error-output-port
+fold-left
+fold-right
+interaction-i/o-port
+notification-output-port
+prompt-for-command-char
+prompt-for-command-expression
+prompt-for-confirmation
+prompt-for-evaluated-expression
+prompt-for-expression
+standard-unparser-method @r{;replaces} unparser/standard-method
+stream-first
+stream-rest
+symbol<?
+trace-output-port
@end example
-@noindent
-@cindex level number, REPL
-The first field, showing @samp{1} in this example, is the level number.
-
-@noindent
-The second field, showing @samp{[Evaluator]} in this example, describes
-the type of @sc{repl} that is running. Other values include:
+@item
+@code{string-pad-left} now truncates from the left instead of the right.
-@example
-[Debugger]
-[Where]
-@end example
+@item
+Argument to @code{make-graphics-device} is now a symbol.
-@noindent
-The @dfn{mode} after @samp{Scheme Interaction} is one of:
+@item
+Each @sc{repl} now has its own working directory pathname and pathname
+defaults. @code{set-working-directory-pathname!} changes only the value
+for the current @sc{repl}.
-@table @samp
-@item input
-Scheme is waiting for input.
+@item
+The definitions of the following procedures have been changed to
+implement more useful behavior:
-@item run
-Scheme is running an evaluation.
+@example
+string-capitalized?
+string-lower-case?
+string-upper-case?
+substring-capitalized?
+substring-lower-case?
+substring-upper-case?
+@end example
-@item gc
-Scheme is garbage collecting.
-@end table
+@item
+New Edwin features:
-@findex scheme-mode
-When @code{xscheme} is loaded, @code{scheme-mode} is extended to include
-commands for evaluating expressions (do @kbd{C-h m} in any
-@code{scheme-mode} buffer for the most up-to-date information):
+@display
+@kbd{M-x dabbrev-expand}
+@kbd{M-x describe-syntax}
+@kbd{M-x rcs-ci-locked-files}
+@kbd{M-x rcs-diff}
+@kbd{M-x rcs-list-locked-files}
+@kbd{M-x rcs-log}
+@kbd{M-x recover-file}
+@kbd{M-x show-parameter-list}
+@kbd{M-x sort-lines} and other sorting commands
+@code{auto-mode-alist} variable (as in Emacs)
+Encryption/decryption of files in @code{Dired}
+Undo upgraded to match GNU Emacs 18.57
+Buffers grow/shrink with constant amortized time
+Emacs 19 tags support (multiple tags files, inclusion)
+@end display
-@table @kbd
-@item @key{ESC} o
-@kindex @key{ESC} o
-@findex xscheme-send-buffer
-Evaluates the current buffer (@code{xscheme-send-buffer}).
+@item
+Edwin compression/uncompression commands changed to use @code{gzip}
+instead of @code{compress}.
-@item @key{ESC} z
-@kindex @key{ESC} z
-@findex xscheme-send-definition
-Evaluates the current definition (@code{xscheme-send-definition}). This
-is also bound to @kbd{@key{ESC} C-x}.
+@item
+Edwin now has text-properties mechanism that permits implementation
+of highlighted and mouse-sensitive regions.
+@end itemize
-@item @key{ESC} C-z
-@kindex @key{ESC} C-z
-@findex xscheme-send-region
-Evaluates the current region (@code{xscheme-send-region}).
+@node 7.2 News, , 7.3 News, Release Notes
+@section Changes from Release 7.1 to 7.2
-@item C-x C-e
-@kindex C-x C-e
-@findex xscheme-send-previous-expression
-Evaluates the expression to the left of point
-(@code{xscheme-send-previous-expression}). This is also bound to
-@kbd{@key{ESC} @key{RET}}.
+This is an abbreviated list of the changes that were incorporated
+in the (partial) 7.2 release since the 7.1 release.
-@item C-c C-s
-@kindex C-c C-s
-@findex xscheme-select-process-buffer
-Selects the @code{*scheme*} buffer and places you at its end
-(@code{xscheme-select-process-buffer}).
+@itemize @bullet
+@item
+Support for MS DOS.
-@item C-c C-y
-@kindex C-c C-y
-@findex xscheme-yank-previous-send
-Yanks the most recently evaluated expression, placing it at point
-(@code{xscheme-yank-previous-send}). This works only in the
-@code{*scheme*} buffer.
-@end table
+@item
+Native compiled-code support for the Intel i386 and i486 architectures.
-The following commands provide interrupt capability:
+@item
+Fixes to MIPS compiled-code support MIPS R3000 with large cache-line
+sizes.
-@table @kbd
-@item C-c C-c
-@kindex C-c C-c
-@findex xscheme-send-control-g-interrupt
-Like typing @kbd{C-g} when running Scheme without Emacs
-(@code{xscheme-send-control-g-interrupt}).
+@item
+Complete redesign of the error system.
-@item C-c C-x
-@kindex C-c C-x
-@findex xscheme-send-control-x-interrupt
-Like typing @kbd{C-c C-x} when running Scheme without Emacs
-(@code{xscheme-send-control-x-interrupt}).
+@item
+X11 graphics interface redesigned. The new design is smarter about
+interaction with the window manager (for example, it implements the
+@code{WM_DELETE_WINDOW} protocol) and has some limited support for event
+handling. Windows are now closed when they are reclaimed by the garbage
+collector.
-@item C-c C-u
-@kindex C-c C-u
-@findex xscheme-send-control-u-interrupt
-Like typing @kbd{C-c C-u} when running Scheme without Emacs
-(@code{xscheme-send-control-u-interrupt}).
+@item
+Redesign of @sc{i/o} ports. New design supports ports that perform both
+input and output.
-@item C-c C-b
-@kindex C-c C-b
-@findex xscheme-send-breakpoint-interrupt
-Like typing @kbd{C-c C-b} when running Scheme without Emacs
-(@code{xscheme-send-breakpoint-interrupt}).
+@item
+Ports now have better-defined control over blocking mode and terminal
+mode. Flushing of output buffers is not done automatically, except for
+the console port.
-@item C-c C-p
-@kindex C-c C-p
-@findex xscheme-send-proceed
-Like evaluating @code{(proceed)} (@code{xscheme-send-proceed}).
-@end table
+@item
+New procedures:
-@node Edwin, Concept Index, GNU Emacs Interface, Top
-@chapter Edwin
+@example
+*default-pathname-defaults*
+->namestring
+->truename
+close-port
+directory-namestring
+directory-pathname
+directory-pathname-as-file
+enough-namestring
+enough-pathname
+file-access
+file-attributes-direct @r{;same as} file-attributes
+file-modification-time-direct
+file-modification-time-indirect @r{;same as} file-modification-time
+file-namestring
+file-pathname
+file-readable?
+host-namestring
+i/o-port?
+make-generic-i/o-port
+make-i/o-port
+open-i/o-file
+pathname-simplify
+pathname-wild?
+pathname=?
+port/copy
+port/input-channel
+port/operation
+port/operation-names
+port/output-channel
+port/state
+port?
+record-copy
+record-modifier @r{;replaces} record-updater
+set-port/state!
+@end example
-This chapter describes how to start Edwin, the MIT Scheme text editor.
-Edwin is very similar to GNU Emacs --- you should refer to the GNU Emacs
-manual for information about Edwin's commands and key bindings ---
-except that Edwin's extension language is MIT Scheme, while GNU Emacs
-extensions are written in Emacs Lisp. This manual does not discuss
-customization of Edwin.
+@item
+@code{with-input-from-file} and @code{with-output-to-file} no longer
+close the port when they are exited abnormally.
-@menu
-* Starting Edwin::
-* Leaving Edwin::
-* Last Resorts::
-* Comparison of Edwin 3.82 to Emacs 18.57::
-@end menu
+@item
+Redefined @code{#!optional} and @code{#!rest} to be something distinct
+from symbols.
-@node Starting Edwin, Leaving Edwin, Edwin, Edwin
-@section Starting Edwin
+@item
+Strings now accept @code{"\@var{nnn}}" octal character escapes, much
+like those in C.
-To use Edwin, start Scheme with a world image containing Edwin (for
-example by giving the @code{-edwin} command-line option), then call the
-procedure @code{edit}:
+@item
+Redesign of pathname abstraction. New design is very similar to the
+Common Lisp pathname abstraction.
-@deffn {procedure+} edit
-@deffnx {procedure+} edwin
-Enter the Edwin text editor. If entering for the first time, the editor
-is initialized (by calling @code{create-editor} with no arguments).
-Otherwise, the previously-initialized editor is reentered.
+@itemize @bullet
+@item
+->PATHNAME no longer accepts a symbol as an argument. Only strings
+and pathnames are valid.
-This procedure is sometimes evaluated from the command line to start
-Scheme with Edwin running:
+@item
+Procedures eliminated:
@example
-scheme -edwin -eval (edit)
+canonicalize-input-filename
+canonicalize-input-pathname
+canonicalize-output-filename
+canonicalize-output-pathname
+canonicalize-overwrite-filename
+canonicalize-overwrite-pathname
+home-directory-pathname
+init-file-truename
+pathname->absolute-pathname
+pathname->input-truename
+pathname->output-truename
+pathname->overwrite-truename
+pathname->string
+pathname-components
+pathname-default-host
+pathname-directory-path
+pathname-directory-string
+pathname-name-path
+pathname-name-string
+pathname-new-host
+pathname-relative?
+string->pathname
+symbol->pathname
@end example
-@findex edwin
-The procedure @code{edwin} is an alias for @code{edit}.
-@end deffn
-
-@defvr {variable+} inhibit-editor-init-file?
-When Edwin is first initialized, it loads your init file (called
-@file{~/.edwin} on unix, @file{edwin.ini} on PCs) if you have one. If
-the Scheme variable @code{inhibit-editor-init-file?} is true, however,
-your init file will not be loaded even if it exists. By default, this
-variable is false.
-@end defvr
-
-@deffn {procedure+} create-editor arg @dots{}
-Initializes Edwin, or reinitializes it if already initialized.
-@code{create-editor} is normally invoked automatically by @code{edit}.
-
-If no @var{arg}s are given, the value of @code{create-editor-args} is
-used instead. In other words, the following are equivalent:
-
-@lisp
-(create-editor)
-(apply create-editor create-editor-args)
-@end lisp
-
-@noindent
-On the other hand, if @var{arg}s are given, they are used to update
-@code{create-editor-args}, making the following equivalent:
+@item
+@code{pathname-default} no longer accepts a @var{host} argument.
-@lisp
-(apply create-editor @var{args})
-(begin (set! create-editor-args @var{args}) (create-editor))
-@end lisp
-@end deffn
+@item
+Representation of pathname directories changed to match Common Lisp.
+Directory is now either @code{#f} or a list of symbols and strings with
+first element either @code{absolute} or @code{relative}.
-@defvr {variable+} create-editor-args
-This variable controls the initialization of Edwin. The following
-values are defined:
+@item
+Unix pathnames now set @var{device} and @var{version} to
+@code{unspecific}. @code{unspecific} now means that the field is not
+used by the operating system.
-@table @code
-@item (console)
-This says to run Edwin on Scheme's console, or in unix terminology, the
-standard input and output. If the console is not a terminal device, or
-is not powerful enough to run Edwin, an error will be signalled at
-initialization time.
+@item
+Parsing rules for Unix filenames changed: the file type is the part of
+the name after the last dot, if any. If the dot occurs at the beginning
+or end of the filename, then it doesn't count --- in that case there is
+no type. Thus, names like @file{.} and @file{..} have no type.
+@end itemize
-@item (x)
-@findex DISPLAY
-This says to create an X window and run Edwin on it. This requires the
-@code{DISPLAY} environment variable to have been set to the appropriate
-value before Scheme was started.
+@item
+New Edwin features:
-@item (x @var{geometry})
-This is like @code{(x)} except that @var{geometry} specifies the
-window's geometry in the usual way. @var{Geometry} must be a character
-string whose contents is an X geometry specification.
+@display
+@kbd{M-x manual-entry}
+@kbd{M-x outline-mode}
+@kbd{M-x shell-resync-dirs}
+@kbd{M-x shell-command}
+@kbd{M-x shell-command-on-region}
+@kbd{M-x telnet}
+@sc{rmail} summary
+@sc{rmail} sort
+@sc{repl} mode and asynchronous evaluation
+Printing commands
+``run light'' for evaluation commands
+Reading and writing of compressed files (@code{".Z"} suffix)
+Reading and writing of encrypted files (@code{".KY"} suffix)
+Compress/uncompress commands for @code{Dired}
+Support for X protocols: @code{WM_DELETE_WINDOW} and @code{WM_TAKE_FOCUS}
+Time, load, and mail notification in mode line
+@end display
+@end itemize
-@item (#f)
-This is the default. It says to try running Edwin on Scheme's console,
-and failing that, to create an X window and run Edwin on that. This
-signals an error if neither the console nor the X display is usable.
-@end table
-@end defvr
+@node Known Problems, Comparison of Edwin to Emacs, Release Notes, Top
+@appendix Known Problems
-@node Leaving Edwin, Last Resorts, Starting Edwin, Edwin
-@section Leaving Edwin
+@itemize @bullet
+@item
+The Windows version of MIT Scheme is more robust under NT than Windows
+3.1
-Once Edwin has been entered, it can be exited in the following ways:
+@item
+[NT] Exclusive file access problems. Edwin sometimes can't write a file
+that is still open for reading.
-@table @kbd
-@item C-x z
-@kindex C-x z
-@findex suspend-edwin
-Stop Edwin and return to Scheme (@code{suspend-edwin}). The call to the
-procedure @code{edit} that entered Edwin returns normally. A subsequent
-call to @code{edit} will resume Edwin where it was stopped.
+Typically you will have entered @code{(load "foo.scm")} in the
+interaction buffer and got an error, say a mis-matched parenthesis.
+You then switch to the @code{foo.scm} buffer, fix the problem and then
+try to save the file.
+Edwin refuses, saying
-@item C-x c
-@kindex C-x c
-@findex save-buffers-kill-edwin
-Offer to save any modified buffers, then kill Edwin, returning to Scheme
-(@code{save-buffers-kill-edwin}). This is like the @code{suspend-edwin}
-command, except that a subsequent call to @code{edit} will reinitialize
-the editor.
+@example
+Unable to open file "@var{your-path}\\foo.scm" because: Unknown
+@end example
-@item C-x C-z
-@kindex C-x C-z
-@findex suspend-scheme
-Stop Edwin and suspend Scheme, returning control to the operating
-system's command interpreter (@code{suspend-scheme}). When Scheme is
-resumed (using the command interpreter's job-control commands), Edwin is
-automatically restarted where it was stopped. This command is identical
-to the @kbd{C-x C-z} command of GNU Emacs.
+@noindent
+Work-around: In the interaction buffer: Quit to top level. Do a
+@code{(gc-flip)}, which forces the file to be closed when the file port
+is garbage-collected. Now you will be able to save the file.
-@item C-x C-c
-@kindex C-x C-c
-@findex save-buffers-kill-scheme
-Offer to save any modified buffers, then kill both Edwin and Scheme
-(@code{save-buffers-kill-scheme}). Control is returned to the operating
-system's command interpreter, and the Scheme process is terminated.
-This command is identical to the @kbd{C-x C-c} command of GNU Emacs.
-@end table
+@item
+@code{MITSCHEME_INF_DIRECTORY} sometimes does not work.
+The runtime system cannot find the debugging information unless it is on
+the @file{C:} drive.
+To test if the debugging information is available, try
-@node Last Resorts, Comparison of Edwin 3.82 to Emacs 18.57, Leaving Edwin, Edwin
-@section Last Resorts
+@example
+(pp pp)
+@end example
-When Scheme exits abnormally it tries to save any unsaved Edwin buffers.
-The buffers are saved in an auto-save file in case the original is more
-valuable than the unsaved version. You can use the editor command
-@code{M-x recover-file} to recover the auto-saved version. The
-auto-save files are named so: under unix, @file{foo.scm} will be saved
-as @file{#foo.scm#}; on PCs it will be saved as @file{foo.s00}, a backup
-file with version @samp{00} (which is never used as an actual version).
+@noindent
+If the debugging information is available the @code{pp} procedure
+pretty-prints procedures as Scheme code.
+If the information cannot be found then it prints the procedure as an
+opaque object, similar to this:
-The following Scheme procedures are useful for recovering from bugs in
-Edwin's implementation. All of them are designed for use when Edwin is
-@emph{not} running --- they should not be used when Edwin is running.
-These procedures are designed to help Edwin's implementors deal with
-bugs during the implementation of the editor; they are not intended for
-casual use, but as a means of recovering from bugs that would otherwise
-require reloading the editor's world image from the disk.
+@example
+#[compiled-procedure 13 ("pp" #x2) #xF #x646BF7]
+@end example
-@deffn {procedure+} save-editor-files
-Examines Edwin, offering to save any unsaved buffers. This is useful if
-some bug caused Edwin to die while there were unsaved buffers, and you
-want to save the information without restarting the editor.
-@end deffn
+@item
+Edwin autoloads.
+A few files that are automatically part of Edwin under Unix are not part
+of Edwin in the PC. These can be loaded manually from the auto-load
+directory, for example, by putting
-@deffn {procedure+} reset-editor
-Resets Edwin, causing it to be reinitialized the next time that
-@code{edit} is called. If you encounter a fatal bug in Edwin, a good
-way to recover is to first call @code{save-editor-files}, and then to
-call @code{reset-editor}. That should completely reset the editor to
-its initial state.
-@end deffn
+@example
+(edwin-load "dabbrev")
+@end example
-@deffn {procedure+} reset-editor-windows
-Resets Edwin's display structures, without affecting any of the buffers
-or their contents. This is useful if a bug in the display code causes
-Edwin's internal display data structures to get into an inconsistent
-state that prevents Edwin from running.
-@end deffn
+@noindent
+in your @file{edwin.ini} file.
+@end itemize
-@node Comparison of Edwin 3.82 to Emacs 18.57, , Last Resorts, Edwin
-@section Comparison of Edwin 3.82 to Emacs 18.57
+@node Comparison of Edwin to Emacs, Index, Known Problems, Top
+@appendix Comparison of Edwin to Emacs
-This section documents all known differences between Edwin 3.82 and
-Emacs 18.57. A reference to a ``documented'' feature of Emacs means
-that the feature is documented in the GNU Emacs version 18 manual.
+This section documents known differences between Edwin 3.90 and Emacs
+18.57. A reference to a ``documented'' feature of Emacs means that the
+feature is documented in the GNU Emacs version 18 manual.
@menu
* Incompatibilities of Edwin::
* Edwin Bugs::
@end menu
-@node Incompatibilities of Edwin, Deficiencies of Edwin, Comparison of Edwin 3.82 to Emacs 18.57, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Incompatibilities
+@node Incompatibilities of Edwin, Deficiencies of Edwin, Comparison of Edwin to Emacs, Comparison of Edwin to Emacs
+@section Incompatibilities
These are differences in design, unlikely to be `fixed'.
@itemize @bullet
@item
Edwin's keyboard character set is a superset of Emacs'. Edwin has
-support for real MIT-style bucky bits. Under X windows (and perhaps
-other systems) Edwin can distinguish between @kbd{C-a} and @kbd{C-a},
-@kbd{C-SPC} and @kbd{C-@@}, etc. When running on a terminal or a PC/DOS
-console, the input set is limited to 8-bit ASCII as in Emacs.
+support for real MIT-style bucky bits. Under X windows and OS/2 (and
+perhaps other systems) Edwin can distinguish between @kbd{C-a} and
+@kbd{C-A}, @kbd{C-SPC} and @kbd{C-@@}, etc. When running on a terminal,
+the input set is limited to 8-bit @sc{ascii} as in Emacs.
@item
Edwin is case-insensitive for command and variable names.
@item
Edwin additionally defines @kbd{C-z} and @kbd{C-^} as prefix keys.
@kbd{C-z} is the @key{CTRL-META} prefix, and @kbd{C-^} is the @key{CTRL}
-prefix, both as in TOPS-20 EMACS.
+prefix, both as in TOPS-20 Emacs.
@item
@kbd{C-z} doesn't suspend Edwin. @kbd{C-x C-z} suspends both Emacs and
@item
In Edwin, @kbd{C-w} and @kbd{C-y} don't skip to next occurrence in
-reverse i-search. This is intentional.
+reverse i-search. This is intentional, and matches the behavior of
+Emacs 19.
@item
@code{comment-indent-hook} is defined differently. In Emacs, it is
of the comment, and with point undefined.
@item
-Edwin's completion of Scheme variables is environment dependent. In
-@code{Scheme} and @code{Scheme Interaction} modes, @kbd{M-TAB} completes
-the Scheme variable name. Completion is environment-dependent, so a
-prefix may complete differently (or not at all) in two different buffers
-with different associated environments.
-
-DOS Note: Since @kbd{Alt+TAB} is an MS Windows hot key, you can get the
-same effect (without disabling it) by typing @kbd{Alt+Ctrl+I}.
+Edwin's completion of Scheme variables is dependent on the environment.
+In @code{Scheme} and @code{Scheme Interaction} modes, @kbd{M-TAB}
+completes the Scheme variable name. Completion is
+environment-dependent, so a prefix may complete differently (or not at
+all) in two different buffers with different associated environments.
@item
@kbd{M-x load-file} and @kbd{M-x load-library} behave somewhat
procedure of no arguments.
@end itemize
-@node Deficiencies of Edwin, Subsystems Missing from Edwin, Incompatibilities of Edwin, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Deficiencies
+@node Deficiencies of Edwin, Subsystems Missing from Edwin, Incompatibilities of Edwin, Comparison of Edwin to Emacs
+@section Deficiencies
Deficiencies are shortcomings of Edwin that are likely to be fixed.
@item
Dired is missing these commands in Edwin: @kbd{v} and @kbd{B}.
-Under DOS it is missing the following:
-
-@example
-v @r{view this file.}
-B @r{byte-compile this file.}
-M @r{change this file's permissions.}
-G @r{change this file's group.}
-O @r{change this file's owner.}
-C @r{compress this file.}
-U @r{uncompress this file.}
-@end example
-
-@item
-Dired has the following subcommands that Emacs does not have:
-
-@example
-k @r{mark file for copying}
-y @r{copy marked files}
-@end example
@item
@kbd{C-x n} is not disabled by default.
Edwin does not have the notion of ``novice''.
@end itemize
-@node Subsystems Missing from Edwin, Commands Missing from Edwin, Deficiencies of Edwin, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Missing Subsystems
+@node Subsystems Missing from Edwin, Commands Missing from Edwin, Deficiencies of Edwin, Comparison of Edwin to Emacs
+@section Missing Subsystems
The following documented subsystems are implemented by Emacs but not by
Edwin.
text formatter modes: nroff, scribe, tex, latex
@end itemize
-DOS Note:
-
-Some modes are available under Unix, but are not included in the standard
-DOS edwin binary to reduce its size or because they don't work under DOS:
-
-@example
-Missing Command or mode Reason
------------------------ ------
-
-* dabbrev reduce size
- compile needs subprocess support
- shell needs subprocess support
- + there is a DOS replacement
- techinfo specific to MIT & Unix
- telnet needs subprocess support
-* midas mode (assembly language editing) reduce size
-* pascal mode reduce size
- texinfo reduce size
- man specific to unix
- print does not work yet
-* run-notifier reduce size
-* outline mode reduce size
-* info reduce size
- rcs needs subprocess support
- sendmail needs subprocess support
- malias useless without sendmail
-* occur (and list-matching-lines) reduce size
- rmail needs subprocess support
- + specific to Unix ?
- rmailsrt useless without rmail
-@end example
-
-Many of the missing modes and commands (compile, shell, rcs,
-sendmail) require subprocess support. They should be easy to bring
-up if subprocesses become available, however the code (or even the
-concept) may be Unix specific. There is a pseudo-shell mode for DOS.
-
-Many of the subsystems listed above have not been tried under DOS.
-The ones that are known to work are marked with an asterisk (*),
-although for some of them variables have to be set appropriately
-before use (e.g.@: @code{info-directory} for info).
-
-@node Commands Missing from Edwin, Variables Missing from Edwin, Subsystems Missing from Edwin, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Missing Commands
+@node Commands Missing from Edwin, Variables Missing from Edwin, Subsystems Missing from Edwin, Comparison of Edwin to Emacs
+@section Missing Commands
These commands are implemented by Emacs but not by Edwin. The commands
-marked with an asterisk are implemented by the unix version of Edwin but
-not by the PC version. Some of the asterisked commands can work in the
-PC version but the code to implement them is not loaded in order to save
-space; others are unix-specific and are not implemented on the PC.
+marked with an asterisk are implemented under Unix and OS/2 but not
+under Windows. Some of the asterisked commands can work under Windows
+but the code to implement them is not loaded in order to save space;
+others are require subprocess support that isn't available in the
+Windows implementation.
@example
abbrev-mode
zap-to-char
@end example
-@node Variables Missing from Edwin, Per-Buffer Variables, Commands Missing from Edwin, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Missing Variables
+@node Variables Missing from Edwin, Per-Buffer Variables, Commands Missing from Edwin, Comparison of Edwin to Emacs
+@section Missing Variables
These documented variables are implemented by Emacs but not Edwin. The
-variables marked with an asterisk are implemented by the unix version of
-Edwin, but not by the PC version.
+variables marked with an asterisk are implemented under Unix and OS/2,
+but not under Windows.
@example
abbrev-all-caps
visible-bell
@end example
-@node Per-Buffer Variables, Edwin Bugs, Variables Missing from Edwin, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Per-Buffer Variables
+@node Per-Buffer Variables, Edwin Bugs, Variables Missing from Edwin, Comparison of Edwin to Emacs
+@section Per-Buffer Variables
These documented variables are per-buffer in Emacs but not in Edwin.
shell-prompt-pattern
@end example
-@node Edwin Bugs, , Per-Buffer Variables, Comparison of Edwin 3.82 to Emacs 18.57
-@subsection Edwin Bugs
+@node Edwin Bugs, , Per-Buffer Variables, Comparison of Edwin to Emacs
+@section Edwin Bugs
Incorrect behavior of Edwin that will be fixed:
column zero.
@end itemize
-@node Concept Index, , Edwin, Top
-@unnumbered Concept Index
+@node Index, , Comparison of Edwin to Emacs, Top
+@unnumbered Index
@printindex cp
@contents
projects / mit-scheme.git / commitdiff