   This file documents the use of MIT Scheme.

   Copyright (C) 1991-2002 Massachusetts Institute of Technology

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

   Scheme is the UnCommon Lisp.  This Info file is the user's guide for
the MIT implementation of Scheme.  It describes how to install and run
MIT Scheme, how to execute and compile Scheme programs, and how to use
Scheme with Edwin and GNU Emacs.

Introduction
************

   This document describes how to install and use MIT Scheme, the
UnCommon Lisp.  It gives installation instructions for all of the
platforms that we support; complete documentation of the command-line
options and environment variables that control how Scheme works; and
rudimentary descriptions of how to interact with the evaluator, compile
and debug programs, and use the editor.  The release notes are included
as an appendix.

   This document discusses many operating-system specific features of
the MIT Scheme implementation.  In order to simplify the discussion, we
use abbreviations to refer to some operating systems.  When the text
uses the term "unix", this means any of the unix systems that we
support, including GNU/Linux, *BSD, HP-UX, Ultrix, NeXT, and SunOS.
The term "OS/2" means the IBM OS/2 operating system, version 2.1 or
later.  We use the term "Windows" to collectively refer to the
Microsoft Windows 32-bit operating systems: Windows 95, Windows 98,
Windows ME, Windows NT, Windows 2000, and Windows XP.  We use the term
"PC" to refer to any computer running OS/2 or Windows.  Thus we
consider a PC to be a system with a DOS-like file system, using
backslashes for directory separators, drive letters, CR-LF line
termination, and (potentially) the hideous 8.3 short filenames.

   The primary distribution site for this software is

     `http://www.swiss.ai.mit.edu/projects/scheme/'
     `ftp://ftp.swiss.ai.mit.edu/pub/mit-scheme/'

Although our software is distributed from other sites and in other
media, the complete distribution and the most recent release is always
available at our site.

   To report bugs, send email to `bug-cscheme@zurich.ai.mit.edu'.
Please include the output of the `identify-world' procedure (see
Basics of Starting Scheme), so we know what version of the system you
are using.

Installation
************

   This chapter describes how to install MIT Scheme release 7.7.  The
release is supported under several different operating systems: unix,
OS/2, and Windows.  Read the section detailing the installation for the
operating system that you are using.

Unix Installation
=================

   We will use as an example the installation for GNU/Linux.  The
installation for other unix systems is similar.

   MIT Scheme is distributed as a compressed `tar' file.  The tar file
contains two directories, called `bin' and `lib'.  The `bin' directory
contains two executable files, `scheme' and `bchscheme'.  The `lib'
directory contains one subdirectory, `lib/mit-scheme', that Scheme uses
while it is executing.

   The goal of the installation is to put the executable files in a
directory where they will be executed as commands, and to put the
library files in some convenient place where Scheme can find them.

   There are two ways to install this software: the conventional way in
`/usr/local', and the alternative way, in locations of your choice.  We
encourage you to install this software in `/usr/local' if possible.

   To install the software in `/usr/local', do the following

     cd /usr/local
     rm -f bin/scheme bin/bchscheme
     rm -rf lib/mit-scheme
     gzip -cd scheme-7.7.1-ix86-gnu-linux.tar.gz | tar xvf -

After executing these commands, the executable files will be in
`/usr/local/bin', and the library files will be in
`/usr/local/lib/mit-scheme'.  No further configuration is required.

   To install the files in directories of your choice:

   * First unpack the distribution:

          mkdir temp
          cd temp
          gzip -cd scheme-7.7.1-ix86-gnu-linux.tar.gz | tar xvf -

   * Next, move the contents of the `bin' directory to somewhere
     convenient that is on your execution path.  For example, if you
     had a directory `~/bin' on your path, you would do this:

          mv bin/* ~/bin/.

   * Next, move or copy the `mit-scheme' directory somewhere
     convenient.  For example, you could move it to your home directory:

          mv lib/mit-scheme ~/.

     Note that if you have unpacked the distribution on a different
     drive than the one you plan to store the `mit-scheme' directory
     on, you must use the command `cp -pr' rather than `mv'.

   * Next, you must tell Scheme where to find the `mit-scheme'
     directory.  This can be done in one of two ways.  The first way is
     to bind the environment variable `MITSCHEME_LIBRARY_PATH' to the
     full path to the directory, e.g. in `bash' you would do

          export MITSCHEME_LIBRARY_PATH=~/mit-scheme

     You should put this environment-variable binding in one of your
     shell init files, e.g. for `bash' it might go in the `.bashrc'
     file.

     The second way is to use a command-line argument when invoking
     Scheme, e.g.

          scheme -library ~/mit-scheme

   * You should now be able to run MIT Scheme.  See Running Scheme,
     for more information.

Windows Installation
====================

   This section describes how to install MIT Scheme on Windows 95,
Windows 98, Windows Me, Windows NT 4.0, Windows 2000, or Windows XP.
The software should also work on older versions of Windows NT, but we
haven't tested it there.

   MIT Scheme is distributed as a self-installing executable.
Installation of the software is straightforward.  Simply execute the
downloaded file and answer the installer's questions.  The installer
will allow you to choose the directory in which MIT Scheme is to be
installed, and the name of the folder in which the shortcuts are to be
placed.

   To uninstall the software, open up the `Control Panel', run
`Add/Remove Programs', and double-click on `MIT Scheme 7.7'.

OS/2 Installation
=================

   This section describes how to install MIT Scheme on a machine running
OS/2 2.1 or later.  This release of MIT Scheme has been tested only on
OS/2 Warp 4.0.  It was compiled using IBM Visual Age C++ version 3.0 and
the OS/2 Toolkit version 4.0.

OS/2 Installation Procedure
---------------------------

   After unpacking the ZIP file, `os2.zip', you will have these
directories containing the following files:

`exe'
     The executable programs `scheme.exe' and `bchschem.exe'.

`dll'
     The dynamic link libraries `blowfish.dll', `gdbm.dll', and
     `md5.dll'.

`doc'
     Documentation files in HTML.

`lib'
     A directory containing the data files needed by Scheme when it is
     running.

   Perform the following steps to install Scheme:

  1. Move the executable files `scheme.exe' and `bchschem.exe' from
     `exe' to any directory that appears in your `PATH' environment
     variable.  You may either add the `exe' directory to your path by
     editing `config.sys' and rebooting, or you may move the files in
     `exe' to an existing directory that is already on your `PATH'.

     Depending on your needs, you may want to keep only one of these
     files; chances are you'll only be using one of them.  Of course,
     you may also keep both programs around if you think you might use
     them both.  See Memory Usage, for more information about the
     tradeoffs between these two programs.

  2. Move the dynamic link libraries from `dll' to any directory that
     appears in your `LIBPATH' environment variable.  As above, you may
     either add `dll' to your `LIBPATH', or move the files in `dll' to
     a directory that is already on your `LIBPATH'.

  3. You may move the `lib' directory anywhere you like.  You may
     rename it to anything you like.  (Here at MIT, we use
     `c:\scheme\lib'.)  After you have chosen where it will be located,
     set the `MITSCHEME_LIBRARY_PATH' environment variable in
     `config.sys' to be that location.

     For example, if you decide to store the directory as `c:\schdata',
     you would add the following to `config.sys':

          SET MITSCHEME_LIBRARY_PATH=C:\SCHDATA

     (Remember that you must reboot OS/2 after editing `config.sys' in
     order for the changes to take effect.)

     You can override the setting of this environment variable with the
     `-library' command-line option to Scheme, for example:

          scheme -library d:\myscm\mylib

     If you supply a `-library' option, it is not necessary to have the
     environment variable defined.  For example, instead of editing
     `config.sys', you might create a `.cmd' file to invoke Scheme and
     pass it the `-library' option automatically.

  4. _Optional:_ Move the `doc' directory anywhere you like, or delete
     it if you do not want to keep the documentation.

  5. _Optional:_ Consider setting some of the environment variables
     described below.

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 Environment Variables.

   Note that environment variables are usually defined in the OS/2
`config.sys' file.  After editing the `config.sys' file, it is
necessary to reboot OS/2 before the changes will take effect.

`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 `-library' command-line option).

          SET MITSCHEME_LIBRARY_PATH=C:\SCHEME\LIB

`MITSCHEME_INF_DIRECTORY'
     tells Scheme where to find debugging information for the runtime
     system.  The default value for this environment variable is a
     subdirectory `src' located in the directory specified by
     `MITSCHEME_LIBRARY_PATH'.

          SET MITSCHEME_INF_DIRECTORY=C:\SCHEME\LIB\SRC

`TMPDIR'
     tells Scheme the name of a directory where it can store temporary
     files.

          SET TMPDIR=C:\TMP

`HOME'
     tells Scheme where your "home" directory is located.  This is where
     Scheme looks for init files, and it is also what the `~/' (or
     `~\\') filename prefix expands to.  If not specified, Scheme uses
     the root directory of the current drive.

          SET HOME=C:\CPH

`USER'
     tells Scheme your user name.  This is used for several purposes,
     including the name that will be used as your email address.

          SET USER=cph

`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, `cmd.exe'.

          SET SHELL=C:\4OS2251\4OS2.EXE

Optional Configuration
======================

   As distributed, Scheme contains several large files.  You might not
need all of them, so this section will tell you what each is for so
that you can decide if you want to delete some of them.  Also, we will
discuss the two different Scheme executables, which are each useful in
different situations; you should read this to decide which is right for
you.

   The Scheme runtime environment and associated tools are normally
stored in "bands", which are large memory images stored in files (see
World Images).  Scheme requires at least one band to work properly.
The Scheme distribution includes two bands.  These bands are stored in
the `lib/mit-scheme' directory on unix systems, and the `lib' directory
on PC systems.

`runtime.com'
     The is the basic world image, and the smallest.  It contains just
     the runtime files.  This is the band that is chosen when Scheme is
     invoked with no special command-line options.

`all.com'
     This contains the runtime files, the native-code compiler, and
     Edwin.  This band is chosen when either the `-compiler' or `-edwin'
     command-line options are supplied.

   Depending on your needs, you may not need both of these files.  For
example, if you always want the full development environment, you might
keep `all.com' and delete `runtime.com'.  Remember that you must keep
at least one of these files to use Scheme.

   In addition to bands, Scheme is distributed with two executable
programs: `scheme' (called `scheme.exe' on PC systems), and `bchscheme'
(called `bchschem.exe' on PC systems).  Normally you will need only one
of these files.

   The only difference between these two programs is in how they handle
garbage collection.  `scheme' 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.  `bchscheme' allocates only one memory heap,
creates a disk file during garbage collection, copies objects into the
file, then copies them back into memory.

   These programs provide you with some important performance
trade-offs.  If you have plenty of memory and want the best
performance, use `scheme'.  If you don't have enough memory, or if you
want to use less memory and will accept slower performance, use
`bchscheme'.  One way to tell that you don't have enough memory is to
run `scheme' for a while and see if your machine is paging during
garbage collection.

   You might consider trying to use `scheme' and letting the operating
system's paging handle the lack of RAM.  But usually you will find that
using `bchscheme' without paging is much faster than using `scheme'
with paging.  Of course, if you are using `bchscheme' and you're still
paging, the best solution is to install more RAM.

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.

Basics of Starting Scheme
=========================

   Under unix and OS/2, MIT Scheme is invoked by typing

     scheme

at your operating system's command interpreter.  Under Windows, MIT
Scheme is invoked by double-clicking on a shortcut.  In either case,
Scheme will load itself and print something like this:

     Scheme saved on Monday June 17, 2002 at 12:10:46 PM
       Release 7.7.1
       Microcode 14.9
       Runtime 15.1

This information, which can be printed again by evaluating

     (identify-world)

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.  `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.

   Following this there may be additional version numbers for specific
subsystems.  `SF' refers to the scode optimization program `sf', `Liar'
is the native-code compiler, `Edwin' is the Emacs-like text editor, and
`6.001' is the SICP compatibility package.

   You can load the compiler by giving Scheme the `-compiler' option:

     scheme -compiler

This option causes Scheme to use a larger constant space and heap, and
to load the world image containing the compiler.

Customizing Scheme
==================

   You can customize your setup by using a variety of tools:

   * "Command-line options".  Many parameters, like memory usage and
     the location of libraries, may be varied by command-line options.
     See Command-Line Options.

   * "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), `.bat' file
     (Windows), or `.cmd' file (OS/2) that will invoke Scheme with the
     appropriate `-heap' and other parameters.

   * Scheme supports "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 `HOME' environment variable.  Under
     unix, the file is called `.scheme.init'; on the PC it is called
     `scheme.ini'.

     In addition, when Edwin starts up, it loads a separate init file
     from your home directory into the Edwin environment.  This file is
     called `.edwin' under unix, and `edwin.ini' on the PC (see
     Starting Edwin).

     You can use both of these files to define new procedures or
     commands, or to change defaults in the system.

     The `-no-init-file' command-line option causes Scheme to ignore the
     `.scheme.init' file (see Command-Line Options).

   * "Environment variables".  Most microcode parameters, and some
     runtime system and Edwin parameters, can be specified by means of
     environment variables.  See Environment Variables.

   * "Icons".  Under OS/2 and Windows, and with some window managers
     under X11, it is possible to create icons that invoke Scheme with
     different parameters.

Memory Usage
============

   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.

   Scheme uses four kinds of memory:

   * A "stack" that is used for recursive procedure calls.

   * A "heap" that is used for dynamically allocated objects, like
     `cons' cells and strings.  Storage used for objects in the heap
     that become unreferenced is eventually reclaimed by "garbage
     collection".

   * A "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.

   * Some extra storage that is used by the microcode (the part of the
     system that is implemented in C).

All kinds of memory except the last may be controlled either by
command-line options or by environment variables.

   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 `scheme'
under unix and `scheme.exe' on the PC, has two heaps, one for each
"space".  An alternative, called `bchscheme' under unix and
`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 (see Optional Configuration).

   The total storage required by `scheme' is:

     STACK + (CONSTANT + 2*HEAP) + EXTRA

where STACK, CONSTANT and HEAP are parameters that are selected when
`scheme' starts.  For `bchscheme', which has only one heap in memory,
the equation is

     STACK + (CONSTANT + HEAP) + EXTRA

   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 `-band' option.  Dynamic adjustment of the heap and
constant space avoids this problem.

   If the size of the constant space is not specified, it is
automatically set to the correct size for the band being loaded.  Thus,
in general it is rarely necessary to explicitly set the size of the
constant space.  Additionally, each band requires a small amount of
heap space; this amount is added to any specified heap size, so that
the specified heap size is the amount of free space available.

   The Scheme expression `(print-gc-statistics)' shows how much heap
and constant space is available (see Garbage Collection).

Command-Line Options
====================

   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.  Any arguments other than these options will generate a
warning message when Scheme starts.  If you want to define your own
command-line options, see Custom Command-line Options.

   These are the microcode options:

`-compiler'
     This option specifies defaults appropriate for loading the
     compiler.  It specifies the use of large sizes, exactly like
     `-large'; if the `-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
     `MITSCHEME_COMPILER_BAND', if defined, or `compiler.com'; the
     library directories are searched to locate this file.

`-edwin'
     This option specifies defaults appropriate for loading the editor.
     It specifies the use of large sizes, exactly like `-large'; if the
     `-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 `MITSCHEME_EDWIN_BAND', if defined, or
     `edwin.com'; the library directories are searched to locate this
     file.

`-compiler -edwin'
     If both the `-compiler' and `-edwin' options are given, Scheme
     will load an environment containing both the compiler and the
     editor.  The default band's filename is the value of the
     environment variable `MITSCHEME_ALL_BAND', if defined, or
     `all.com'; the library directories are searched to locate this
     file.

`-band FILENAME'
     Specifies the initial world image file ("band") to be loaded.
     Searches for FILENAME in the working directory and the library
     directories, using the full pathname of the first readable file of
     that name.  If FILENAME is an absolute pathname (on unix, this
     means it starts with `/'), then no search occurs -- FILENAME is
     tested for readability and then used directly.  If this option
     isn't given, the filename is the value of the environment variable
     `MITSCHEME_BAND', or if that isn't defined, `runtime.com'; in
     these cases the library directories are searched, but not the
     working directory.

`-large'
     Specifies that large heap, constant, and stack sizes should be
     used.  These are specified by the environment variables

          MITSCHEME_LARGE_HEAP
          MITSCHEME_LARGE_CONSTANT
          MITSCHEME_LARGE_STACK

     If this option isn't given, the small sizes are used, specified by
     the environment variables

          MITSCHEME_SMALL_HEAP
          MITSCHEME_SMALL_CONSTANT
          MITSCHEME_SMALL_STACK

     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 `-heap',
     `-constant', and `-stack' options.

     Note: the Scheme expression `(print-gc-statistics)' shows how much
     heap and constant space is available and in use (see Garbage Collection).

`-heap BLOCKS'
     Specifies the size of the heap in 1024-word blocks.  Overrides any
     default.  Normally two such heaps are allocated; `bchscheme'
     allocates only one, and uses a disk file for the other.

     The size specified by this option is incremented by the amount of
     heap space needed by the band being loaded.  Consequently, `-heap'
     specifies how much free space will be available in the heap when
     Scheme starts, independent of the amount of heap already consumed
     by the band.

`-constant BLOCKS'
     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.

`-stack BLOCKS'
     Specifies the size of the stack in 1024-word blocks.  Overrides any
     default.  This is Scheme's stack, _not_ the unix stack used by C
     programs.

`-option-summary'
     Causes Scheme to write an option summary to standard error.  This
     shows the values of all of the settable microcode option variables.

`-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.

`-interactive'
     If this option isn't specified, and Scheme's standard 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.

     This detaching behavior is useful for running Scheme as a
     background job.  For example, using `bash', 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:

          scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 &

     This option is ignored under non-unix operating systems.

`-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.

     This option is ignored under non-unix operating systems.

`-library PATH'
     Sets the library search path to 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 `MITSCHEME_LIBRARY_PATH' is used; if that
     isn't defined, the default is used.

     On unix, the elements of the list are separated by colons, and the
     default value is `/usr/local/lib/mit-scheme'.  On PCs, the elements
     of the list are separated by semicolons, and the default value is
     `c:\scheme\lib'.

`-utabmd FILENAME'
     Specifies that FILENAME contains the microcode tables (the
     microcode tables are information that informs the runtime system
     about the microcode's structure).  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
     `MITSCHEME_UTABMD_FILE', or if that isn't defined, `utabmd.bin';
     in these cases the library directories are searched, but not the
     working directory.

     `-utab' is an alternate name for the `-utabmd' option; at most one
     of these options may be given.

`-fasl FILENAME'
     Specifies that a "cold load" should be performed, using 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 `-compiler', `-edwin', or `-band' options.  This
     option is useful only for maintenance and development of the MIT
     Scheme runtime system.

In addition to the above, `bchscheme' recognizes the following
command-line options, all of which specify parameters affecting how
`bchscheme' uses disk storage to do garbage collection:

`-gc-directory DIRECTORY'
     Specifies that DIRECTORY should be used to create files for
     garbage collection.  If the option is not given, the value of
     environment variable `MITSCHEME_GC_DIRECTORY' is used instead, and
     if that is not defined, a standard temporary directory is used (see
     `TMPDIR' in Runtime Environment Variables).

`-gc-file FILENAME'
     Specifies that FILENAME should be used for garbage collection.  If
     the option is not given, the value of environment variable
     `MITSCHEME_GC_FILE' is used, and if this is not defined, a unique
     filename is generated in the directory specified with
     `-gc-directory'.

     `-gcfile' is an alias for `-gc-file'; at most one of these options
     should be specified.

`-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.

`-gc-start-position NUMBER'
     Specifies the first byte position in the GC file at which the
     Scheme process can write.  If not given, the value of the
     environment variable `MITSCHEME_GC_START_POSITION' is used, 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 `-gc-start-position' and `-gc-end-position'.

`-gc-end-position NUMBER'
     Specifies the last byte position in the GC file at which the Scheme
     process can write.  If not given, the value of the environment
     variable `MITSCHEME_GC_END_POSITION' is used, and if that is not
     defined, the sum of the start position (as specified by
     `-gc-start-position') and the heap size is used.  The area of the
     file used (and locked if possible) is the region between
     `-gc-start-position' and `-gc-end-position'.

`-gc-window-size BLOCKS'
     Specifies the size of the windows into new space during garbage
     collection.  If this option is not given, the value of environment
     variable `MITSCHEME_GC_WINDOW_SIZE' is used instead, and if that
     is not defined, the value `16' is used.

The following command-line options are only used by an experimental
version of
`bchscheme' that uses unix System V-style shared memory, and then only
if the `gcdrone' program is installed in the library directory.

`-gc-drone PROGRAM'
     Specifies that PROGRAM should be used as the drone program for
     overlapped I/O during garbage collection.  If the option is not
     given, the value of environment variable `MITSCHEME_GC_DRONE' is
     used instead, and if that is not defined, `gcdrone' is used.

`-gc-read-overlap N'
     Specifies that Scheme should delegate at most N simultaneous disk
     read operations during garbage collection.  If the option is not
     given, the value of environment variable
     `MITSCHEME_GC_READ_OVERLAP' is used instead, and if that is not
     defined, `0' is used, disabling overlapped reads.

`-gc-write-overlap N'
     Specifies that Scheme should delegate at most N simultaneous disk
     write operations during garbage collection.  If the option is not
     given, the value of environment variable
     `MITSCHEME_GC_WRITE_OVERLAP' is used instead, and if that is not
     defined, `0' is used, disabling overlapped writes.

The following options are runtime options.  They are processed after the
microcode options and after the image file is loaded.

`-no-init-file'
     This option causes Scheme to ignore the `~/.scheme.init' or
     `scheme.ini' file, normally loaded automatically when Scheme starts
     (if it exists).

`-suspend-file'
     Under some circumstances Scheme can write out a file called
     `scheme_suspend' in the user's home directory.(1) 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.

     Normally this file is never written, but the `-suspend-file' option
     enables writing of this file.

`-eval EXPRESSION ...'
     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
     `user-initial-environment'.  Unless explicitly handled, errors
     during evaluation are silently ignored.

`-load FILE ...'
     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
     `user-initial-environment'.  Unless explicitly handled, errors
     during loading are silently ignored.

The following option is supported only when Edwin is loaded.

`-edit'
     This option causes Edwin to start immediately when Scheme is
     started.

   ---------- Footnotes ----------

   (1) Under unix, this file is written when Scheme is terminated by
the `SIGUSR1', `SIGHUP', or `SIGPWR' signals.  Under other operating
systems, this file is never written.

Custom Command-line Options
===========================

   MIT Scheme provides a mechanism for you to define your own
command-line options.  This is done by registering handlers to identify
particular named options and to process them when Scheme starts.
Unfortunately, because of the way this mechanism is implemented, you
must define the options and then save a world image containing your
definitions (see World Images).  Later, when you start Scheme using
that world image, your options will be recognized.

   The following procedures define command-line parsers.  In each, the
argument KEYWORD defines the option that will be recognized on the
command line.  The KEYWORD must be a string starting with a hyphen and
containing at least one additional character.

 - procedure+: simple-command-line-parser keyword thunk
     Defines KEYWORD to be a simple command-line option.  When this
     keyword is seen on the command line, it causes THUNK to be
     executed.

 - procedure+: argument-command-line-parser keyword multiple? procedure
     Defines KEYWORD to be a command-line option that is followed by
     one or more command-line arguments.  PROCEDURE is a procedure that
     accepts one argument; when KEYWORD is seen, it is called once for
     each argument.

     MULTIPLE?, if true, says that KEYWORD may be followed by more than
     one argument on the command line.  In this case, procedure is
     called once for each argument that follows KEYWORD and does not
     start with a hyphen.  If MULTIPLE? is `#f', PROCEDURE is called
     once, with the command-line argument following KEYWORD.  In this
     case, it does not matter if the following argument starts with a
     hyphen.

 - procedure+: set-command-line-parser! keyword procedure
     This low-level procedure defines KEYWORD to be a command-line
     option that is defined by PROCEDURE.  When KEYWORD is seen,
     PROCEDURE is called with all of the command-line arguments,
     starting with KEYWORD, as a single list argument.  PROCEDURE must
     return two values (using the `values' procedure): the unused
     command-line arguments (as a list), and a thunk that is executed to
     implement the behavior of the option.

Environment Variables
=====================

   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.

   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 `set-environment-variable!'
procedure, e.g.

     (set-environment-variable! "EDWIN_FOREGROUND" "32")

Environment Variables for the Microcode
---------------------------------------

   These environment variables are referred to by the microcode (the
executable C programs called `scheme' and `bchscheme' under unix, and
`scheme.exe' and `bchschem.exe' on the PC).

`MITSCHEME_ALL_BAND' (default: `all.com' on the library path)
     The initial band to be loaded if both the `-compiler' and `-edwin'
     options are given.  Overridden by `-band'.

`MITSCHEME_BAND' (default: `runtime.com' on the library path)
     The initial band to be loaded.  Overridden by `-band',
     `-compiler', or `-edwin'.

`MITSCHEME_COMPILER_BAND' (default: `compiler.com' on the library path)
     The initial band to be loaded if the `-compiler' option is given.
     Overridden by `-band'.

`MITSCHEME_EDWIN_BAND' (default: `edwin.com' on the library path)
     The initial band to be loaded if the `-edwin' option is given.
     Overridden by `-band'.

`MITSCHEME_LARGE_CONSTANT' (default: as needed)
     The size of constant space, in 1024-word blocks, if the `-large',
     `-compiler', or `-edwin' options are given.  Overridden by
     `-constant'.  Note: the default is computed to be the correct size
     for the band being loaded.

`MITSCHEME_LARGE_HEAP' (default: `1000')
     The size of the heap, in 1024-word blocks, if the `-large',
     `-compiler', or `-edwin' options are given.  Overridden by `-heap'.

`MITSCHEME_LARGE_STACK' (default: `100')
     The size of the stack, in 1024-word blocks, if the `-large',
     `-compiler', or `-edwin' options are given.  Overridden by
     `-stack'.

`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
     `/usr/local/lib/mit-scheme'.  On PC systems the list is
     semicolon-separated with the default `c:\scheme\lib'.

`MITSCHEME_SMALL_CONSTANT' (default: as needed)
     The size of constant space, in 1024-word blocks, if the size
     options are not given.  Overridden by `-constant', `-large',
     `-compiler', or `-edwin'.  Note: the default is computed to be the
     correct size for the band being loaded.

`MITSCHEME_SMALL_HEAP' (default: `250')
     The size of the heap, in 1024-word blocks, if the size options are
     not given.  Overridden by `-heap', `-large', `-compiler', or
     `-edwin'.

`MITSCHEME_SMALL_STACK' (default: `100')
     The size of the stack, in 1024-word blocks, if the size options
     are not given.  Overridden by `-stack', `-large', `-compiler', or
     `-edwin'.

`MITSCHEME_UTABMD_FILE' (default: `utabmd.bin' in the library path)
     The file containing the microcode tables.  Overridden by `-utabmd'
     and `-utab'.

Environment Variables for `bchscheme'
-------------------------------------

   These environment variables are referred to by `bchscheme' (_not_ by
`scheme').

`MITSCHEME_GC_DIRECTORY'
     The directory in which GC files are written.  Overridden by
     `-gc-directory'.  The default for this variable is the standard
     temporary directory (see `TMPDIR' in Runtime Environment Variables).

`MITSCHEME_GC_FILE' (default: `GCXXXXXX')
     The name of the file to use for garbage collection.  If it ends in
     6 `X's, the `X's are replaced by a letter and process id of the
     scheme process, thus generating a unique name.  Overridden by
     `-gc-file'.

`MITSCHEME_GC_START_POSITION' (default: `0')
     The first position in the GC file to use.  Overridden by
     `-gc-start-position'.

`MITSCHEME_GC_END_POSITION' (default: START-POSITION+HEAP-SIZE)
     The last position in the GC file to use.  Overridden by
     `-gc-end-position'.

`MITSCHEME_GC_WINDOW_SIZE' (default: `16')
     The size in blocks of windows into new space (in the GC file).
     Overridden by `-gc-window-size'.

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 `gcdrone' program is installed:

`MITSCHEME_GC_DRONE' (default: `gcdrone')
     The program to use as the I/O drone during garbage collection.
     Overridden by `-gc-drone'.

`MITSCHEME_GC_READ_OVERLAP' (default: `0')
     The maximum number of simultaneous read operations.
     Overridden by `-gc-read-overlap'.

`MITSCHEME_GC_WRITE_OVERLAP' (default: `0')
     The maximum number of simultaneous write operations.
     Overridden by `-gc-write-overlap'.

Environment Variables for the Runtime System
--------------------------------------------

   These environment variables are referred to by the runtime system.

`HOME'
     Directory in which to look for init files.  E.g. `c:\users\joe' or
     `/home/joe'.  This variable needs to be set on OS/2 and Windows
     9x.  Under Windows NT/2000/XP, the environment variables
     `HOMEDRIVE' and `HOMEPATH', set by the operating system, are used
     instead.  Under unix, `HOME' is set by the login shell.

`TMPDIR'
`TEMP'
`TMP'
     Directory for various temporary files.  The variables are tried in
     the given order.  If none of them is suitable, built-in defaults
     are used: under unix, `/var/tmp', `/usr/tmp', `/tmp'; under OS/2
     and Windows, `\temp', `\tmp', and `\' (all on the system drive).

`MITSCHEME_INF_DIRECTORY' (default: `SRC' on the library path)
     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
     `f:\random', runtime system debugging files will be expected in
     `f:\random\runtime', while Edwin debugging files will be expected
     in `f:\random\edwin'.

`MITSCHEME_LOAD_OPTIONS' (default: `optiondb.scm' on the library path)
     Specifies the location of the options database file used by the
     `load-option' procedure.

Environment Variables for Edwin
-------------------------------

   These environment variables are referred to by Edwin.

`EDWIN_BINARY_DIRECTORY' (default: `edwin/autoload' on the library path)
     Directory where Edwin expects to find files providing autoloaded
     facilities.

`EDWIN_INFO_DIRECTORY' (default: `edwin/info' on the library path)
     Directory where Edwin expects to find files for the `info'
     documentation subsystem.

`EDWIN_ETC_DIRECTORY' (default: `edwin/etc' on the library path)
     Directory where Edwin expects to find utility programs and
     documentation strings.

`ESHELL'
     Filename of the shell program to use in shell buffers.  If not
     defined, the `SHELL' environment variable is used instead.

`SHELL' (default: `/bin/sh' (unix), `cmd.exe' (PC))
     Filename of the shell program to use in shell buffers and when
     executing shell commands.  Used to initialize the
     `shell-path-name' editor variable.

`PATH'
     Used to initialize the `exec-path' editor variable, which is
     subsequently used for finding programs to be run as subprocesses.

`DISPLAY'
     Used when Edwin runs under unix and uses X11.  Specifies the
     display on which Edwin will create windows.

`TERM'
     Used when Edwin runs under unix on a terminal.  Terminal type.

`LINES' (default: auto-sense)
     Used when Edwin runs under unix on a terminal.  Number of text
     lines on the screen, for systems that don't support `TIOCGWINSZ'.

`COLUMNS' (default: auto-sense)
     Used when Edwin runs under unix on a terminal.  Number of text
     columns on the screen, for systems that don't support `TIOCGWINSZ'.

Environment Variables for Microsoft Windows
-------------------------------------------

   These environment variables are specific to the Microsoft Windows
implementation.

`MITSCHEME_FONT' (default: determined by operating system)
     A string specifying a font name and characteristics, for example
     `Courier New 16 bold'.  Allowed characteristics are INTEGER,
     specifying the font size in points, and the following style
     modifiers: `bold', `italic', `regular', `underline' and
     `strikeout'.  You should specify only fixed-width fonts as
     variable-width fonts are not drawn correctly.

     Once in Edwin, the font can be changed with the `set-font' and
     `set-default-font' commands.

`MITSCHEME_GEOMETRY' (default: `-1,-1,-1,-1')
     Four integers separated by commas or spaces that specify the
     placement and size of the MIT Scheme window as a
     LEFT,TOP,WIDTH,HEIGHT quadruple.  The units are screen pixels, and
     `-1' means allow the system to choose this parameter.  E.g.
     `-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.

`MITSCHEME_FOREGROUND' (default: according to desktop color scheme)
     A value specifying the window text color.  The color is specified
     as hex blue, green and red values (_not_ RGB): e.g. `0xff0000' for
     blue.

`MITSCHEME_BACKGROUND' (default: according to desktop color scheme)
     A value specifying the window background color.  See
     `MITSCHEME_FOREGROUND'.

`HOMEDRIVE'
`HOMEPATH'
     These variables are used together to indicate the user's home
     directory.  This is the preferred way to specify the home
     directory.

`USERNAME'
`USER'
     Specifies the login name of the user running Scheme.  This is used
     for several different purposes.  `USERNAME' is preferred; `USER'
     is used if `USERNAME' is not defined.  If neither of these
     variables is defined, an error is signalled when the username is
     required.

`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.