From ca21a891762d368e3594ace2578641da0d7d4432 Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Sat, 3 Jul 1999 02:28:34 +0000 Subject: [PATCH] Many changes in preparation for the upcoming 7.5 release. There's still a fair amount left to do. --- v7/doc/user-manual/user.texinfo | 2610 +++++++++---------------------- 1 file changed, 709 insertions(+), 1901 deletions(-) diff --git a/v7/doc/user-manual/user.texinfo b/v7/doc/user-manual/user.texinfo index d4c49d8bb..b9e5f8ff5 100644 --- a/v7/doc/user-manual/user.texinfo +++ b/v7/doc/user-manual/user.texinfo @@ -2,7 +2,7 @@ @iftex @finalout @end iftex -@comment $Id: user.texinfo,v 1.55 1999/02/26 05:39:41 cph Exp $ +@comment $Id: user.texinfo,v 1.56 1999/07/03 02:28:34 cph Exp $ @comment %**start of header (This is for running Texinfo on a region.) @setfilename user.info @settitle MIT Scheme User's Manual @@ -41,9 +41,9 @@ by the Massachusetts Institute of Technology. @titlepage @title{MIT Scheme User's Manual} -@subtitle Edition 1.55 +@subtitle Edition 1.56 @subtitle for Scheme Release 7.5 -@subtitle 26 February 1999 +@subtitle 2 July 1999 @author by Stephen Adams @author Chris Hanson @author and the MIT Scheme Team @@ -87,7 +87,6 @@ Scheme with Edwin and GNU Emacs. * GNU Emacs Interface:: * Edwin:: * Release Notes:: -* Comparison of Edwin to Emacs:: * Index:: @end menu @@ -109,23 +108,22 @@ release notes, is included as appendices. 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 @dfn{Unix}, this means any of the Unix systems that we support, -including GNU/Linux, HP-UX, Ultrix, NeXT, and SunOS. The term -@dfn{OS/2} means the IBM OS/2 operating system, version 2.1, 2.11, or -3.0 Warp. We use the term @dfn{Windows} to collectively refer to the -Microsoft Windows operating systems: Windows 3.1, Windows 95, and -Windows NT. We use the term @dfn{PC} to refer to any computer running -OS/2 or Windows. Thus we consider a PC to be a system with a -@sc{dos}-like file system, using backslashes for directory separators, -drive letters, @sc{cr-lf} line termination, and (potentially) the -hideous 8.3 short filenames. +the term @dfn{unix}, this means any of the unix systems that we support, +including GNU/Linux, *BSD, HP-UX, Ultrix, NeXT, and SunOS. The term +@dfn{OS/2} means the IBM OS/2 operating system, version 2.1 or later. +We use the term @dfn{Windows} to collectively refer to the Microsoft +Windows operating systems: Windows 95, Windows 98, and Windows NT. We +use the term @dfn{PC} to refer to any computer running OS/2 or Windows. +Thus we consider a PC to be a system with a @sc{dos}-like file system, +using backslashes for directory separators, drive letters, @sc{cr-lf} +line termination, and (potentially) the hideous 8.3 short filenames. @cindex Web site @cindex FTP site The primary distribution site for this software is @example -http://www-swiss.ai.mit.edu/scheme-home.html +http://www.swiss.ai.mit.edu/scheme-home.html ftp://swiss-ftp.ai.mit.edu/pub @end example @@ -144,236 +142,118 @@ system you are using. @node Installation, Running Scheme, Introduction, Top @chapter Installation -This chapter describes how to install MIT Scheme release 7.4. The -release is supported under several different operating systems: Unix, +This chapter describes how to install MIT Scheme release 7.5. 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. -If you are installing on an HP 9000 series 700 or 800, you should also -read @ref{HP-PA Installation}. - @menu * Unix Installation:: -* HP-PA Installation:: * OS/2 Installation:: * Windows Installation:: +* Optional Configuration:: @end menu -@node Unix Installation, HP-PA Installation, Installation, Installation +@node Unix Installation, OS/2 Installation, Installation, Installation @section Unix 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}. +installation for other unix systems is similar. MIT Scheme is distributed as a compressed `tar' file. The tar file -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 -that are used during the installation process. The @file{lib} -subdirectory contains several files and subdirectories that Scheme uses -while it is executing. +contains two directories, called @file{bin} and @file{lib}. The +@file{bin} directory contains two executable files, @file{scheme} and +@file{bchscheme}. The @file{lib} directory contains one subdirectory, +@file{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. -@itemize @bullet -@item -First unpack the distribution: - -@example -gzip -cd linux.tar.gz | tar xvf - -@end example - -If you do not have the `gzip' program: we have built executables of -this program for each of the machines that we support. Either use -the executable that we have already built, or else get the gzip -sources (from us or from numerous other sources) and build it -yourself. +There are two ways to install this software: the conventional way in +@file{/usr/local}, and the alternative way, in locations of your +choice. We encourage you to install this software in @file{/usr/local} +if possible. -@item -Next, go to the directory that you just unpacked: +To install the software in @file{/usr/local}, do the following @example -cd dist-7.4 +@group +cd /usr/local +gzip -cd @var{path-to-distribution}/linux.tar.gz | tar xf - +@end group @end example -The easiest way to install the files is to use the "install.sh" shell -script that we've provided in the distribution. You will need to edit -that script to tell it where and how you want Scheme installed. If -you want to do something more complicated, or if the script can't -easily be made to work for your system, use the script as a guide to -installation. - -@item -The script assumes there is no pre-existing installation of MIT Scheme -on your system. If there is, you may need to edit the script, or delete -the existing version (particularly the contents of -@file{/usr/local/lib/mit-scheme}, see the later note on editing -@samp{libdir}). If you have trouble deleting the binary because it is in -use, try renaming it to @file{scheme.busy} and deleting it later. - -@item -The installation script normally uses the command @samp{cp -pr} to copy -the files from the distribution directory to their final locations. You -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. 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 -the installation. This is normally done using the command @samp{ln -s}. -If your system doesn't support symbolic links, or if you prefer to -copy or hard-link files, change the definition of the @samp{link} -variable in the shell script. - -@item -For many systems, a standard place to put executable files is the -directory@* @file{/usr/local/bin}. If this is true for your system, we -suggest installing the executables there. Otherwise, you probably -have some other directory that serves the same purpose; edit -@file{install.sh} and change the definition of the shell variable -@samp{bindir} to be this other directory. - -@item -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. +@noindent +After executing these commands, the executable files will be in +@file{/usr/local/bin} (and consequently on your execution path), and the +library files will be in @file{/usr/local/lib/mit-scheme}. No further +configuration is required. -@item -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. +To install the files in directories of your choice: +@itemize @bullet @item -Once you are satisfied that the @file{install.sh} script is correct, -execute it: +First unpack the distribution: @example -./install.sh +mkdir temp +cd temp +gzip -cd linux.tar.gz | tar xvf - @end example @item -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 +Next, copy the contents of the @file{bin} directory to somewhere +convenient that is on your execution path. For example, if you had a +directory @file{~/bin} on your path, you would do this: @example -scheme +cp -p bin/* ~/bin/. @end example -@noindent -at the command line (if you use the C shell, you may have to type -@samp{rehash} before @samp{scheme} will be recognized). -@end itemize - -@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 -your computer's model, because each model has different cache -hardware. - -This distribution contains a database, called @file{hppacach.mod}, that -describes the cache structure for each model of computer. As of this -writing, that database contains entries for the following models: +@item +Next, move or copy the @file{mit-scheme} directory somewhere +convenient. For example, you could move it to your home directory: @example -@group -705, 710, 712, 715, 720, 725, 730, 735, 750, 755, 770, -816, 834, 835, 850, 867, 877 -@end group +mv lib/mit-scheme ~/. @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, -and stop. If this happens, you must add an entry to the database. -This must be done once, at installation, for each new model. - -Here is the procedure for updating the database: - -@itemize @bullet -@item -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 -in a non-standard place it will be different. For example, if you -install Scheme as @file{/usr/foo/mit-scheme/}, the database file is -called@* @file{/usr/foo/mit-scheme/hppacach.mod}. +Note that if you have unpacked the distribution on a different drive +than the one you plan to store the @file{mit-scheme} directory on, you +must use the command @samp{cp -pr} rather than @samp{mv}. @item -Assuming that Scheme is installed in the normal place, update the -database by becoming the super-user and executing the following -commands on your machine: +Next, if you stored the @file{mit-scheme} directory somewhere other than +@file{/usr/local/lib/mit-scheme}, you must tell Scheme where to find it. +This can be done in one of two ways. The first way is to bind the +environment variable @code{MITSCHEME_LIBRARY_PATH} to the full path to +the directory, e.g.@: in @file{bash} you would do this @example -@group -cd /usr/local/lib/mit-scheme -./hppacach -update hppacach.mod -@end group +export MITSCHEME_LIBRARY_PATH=~/mit-scheme @end example -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{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. - -Please note that you must execute this program on the computer whose -model you wish to add to the database. Also, if you wish to add several -models to the database, you must execute the program once on each model. -If you have several computers that are all of the same model, you need -only update the database once from one of the computers; thereafter all -of the other computers of that model will work. +You should put this environment-variable binding in one of your shell +init files, e.g.@ for @file{bash} it might go in the @file{.bashrc} file. -@item -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{hppacach} program, as follows: +The second way is to use a command-line argument when invoking Scheme, +e.g.@: @example -@group -cd /usr/local/lib/mit-scheme -./hppacach -print hppacach.mod > model-7xx -@end group +scheme -library ~/mit-scheme @end example -(If you have previously updated the database, you do not need to be -super-user to execute this command.) The resulting file, -@file{model-7xx} in this example, is the model information for the -machine that you executed the command on; it is C code that we can use -to update our copy of the database. Send the model information for each -new model to us by electronic mail at -@code{bug-cscheme@@zurich.ai.mit.edu}. Thanks! +@item +You should now be able to run MIT Scheme. @xref{Running Scheme} for +more information. @end itemize -@node OS/2 Installation, Windows Installation, HP-PA Installation, Installation +@node OS/2 Installation, Windows Installation, Unix 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. +OS/2 2.1 later. @menu * Prerequisites for OS/2 Installation:: @@ -688,445 +568,91 @@ SET SHELL=C:\LOCAL\PROG\4OS2251\4OS2.EXE @end example @end table - -@node Windows Installation, , OS/2 Installation, Installation +@node Windows Installation, Optional Configuration, OS/2 Installation, Installation @section Windows Installation -This section describes how to install MIT Scheme on Windows 3.1, Windows -95 and Windows NT. Note that we have tested MIT Scheme only on Windows -NT 3.10, Windows 3.1 and Windows 95. It should run under Windows NT -3.51. It was compiled using the Microsoft's MSTOOLS compiler that comes -with Windows NT 3.10. - -It is helpful to read these instructions through before trying the -installation. There are several places where the instructions differ -depending on what flavor of Windows you are running. We suggest that -you omit the optional instructions unless you have a pressing need. - -@menu -* What to download:: -* Prerequisites for Windows Installation:: -* Windows Installation Procedure:: -@end menu - -@node What to download, Prerequisites for Windows Installation, Windows Installation, Windows Installation -@subsection What to download - -The distribution has five files: - -@table @file -@item w32bin.zip -This contains most of MIT Scheme, including the scheme executables, -scheme libraries, and documentation as @file{.HLP} files. - -@item unzip.exe -Unzip program for installing @file{.zip} files. You must use this -program to unpack the @file{.zip} files. Not all `unzip' programs are -compatible and we have seen many problems due to using another program -to unpack the zip files. Use this one. - -@item w32rtbci.zip -Debugging support for runtime system (which includes all the standard -procedures). - -@itemx w32edbci.zip -Debugging support for Edwin. This is not very useful unless you want to -do lots of programming to change Edwin's behaviour. - -@item pw1118.exe -Microsoft's Win32S system. This is required only for Windows 3.1. -@end table - -Throughout these instructions we assume that you downloaded these files -into a directory called @file{C:\download}. - - -@node Prerequisites for Windows Installation, Windows Installation Procedure, What to download, Windows 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 (see "Image Files" below). - -MIT Scheme requires a fair amount of RAM to run well. Our experience is -that you should have at least 12 megabytes of RAM, and preferably 16 -megabytes or more. - -MIT Scheme is a 32-bit program. To run it on Windows 3.1 you need to -install the Win32s compatibility package from Microsoft. You might -already have Win32s on your machine if another 32-bit software package -installed it. Win32s is provided in the self-extracting @sc{zip} file -@file{pw1118.exe}. - -To install Win32s do the following: Create a directory (it does not -matter what it is called). Copy or download @file{pw1118.exe} into the -directory. Then change into the directory and run @samp{pw1118}. This -will create three files. Follow the instructions in @file{readme.txt}. -Using an MSDOS window, you can do the above by entering each of the -following commands in turn: - -@example -mkdir \temp -cd \temp -copy c:\download\pw1118.exe \temp -pw1118 -@end example - - - -@node Windows Installation Procedure, , Prerequisites for Windows Installation, Windows Installation -@subsection Windows Installation Procedure - +This section describes how to install MIT Scheme on Windows 95, Windows +98, or Windows NT 4.0. 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. -Unless otherwise stated, these instructions should be followed by typing -commands into a command shell window and pressing the Enter key. Do -not try to run the commands from File/Run menu or the Start button as -most of the commands do not work properly this way. +To uninstall the software, open up the @samp{Control Panel}, run +@samp{Add/Remove Programs}, and double-click on @samp{MIT Scheme 7.5}. -You can start an MSDOS window by (Windows 3.1, NT 3.51) double-clicking -the MSDOS icon called `Command prompt' in the `Main' program manager -group, or (Windows 95, NT 4.0) from the `Start' button, => Programs => -Shell. +@node Optional Configuration, , Windows Installation, Installation +@section 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. - -Create a directory where you would like Scheme to be installed. We -suggest @file{c:\scheme}. From now on we will call this directory the -@dfn{Scheme root directory}. Change to this directory and unpack -@file{w32bin.zip}: - -@example -cd \ -mkdir scheme -cd scheme -c:\download\unzip c:\download\w32bin.zip -@end example - -@noindent -You should now have the following files and directories in the scheme -root directory. +The Scheme runtime environment and associated tools are normally stored +in @dfn{bands}, which are large memory images stored in files (@pxref +{World Images}). Scheme requires at least one band to work properly. +The Scheme distribution contains several bands. These bands are stored +in the @file{lib/mit-scheme} directory on unix systems, and the +@file{lib} directory on PC systems. @table @file -@item readme -These installation instructions. - -@item bin\ -The executable programs @file{scheme.exe} and @file{bchschem.exe}, the -libraries @file{scheme16.dll}, @file{scheme31.dll} and -@file{scheme32.dll}, and the libraries@* @file{dibutils.dll} and -@file{pmgrpapi.dll}. - -@item doc\ -Documentation files. Three files, the @cite{MIT Scheme Users' Manual}, -the @cite{MIT Scheme Reference Manual}, and the @cite{Revised^4 Report -on the Algorithmic Language Scheme}, are provided in Windows Help -(@file{.hlp}) format. - -@item etc\ -Installation command files (mostly @file{.bat} and @file{.scm} files). - -@item lib\ -Contains the data files needed by Scheme when it is running. Mostly -large @file{.com} files. - -@item cref\ -This is useful only for people who want to recompile Edwin or the -compiler. - +@item 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. + +@item compiler.com +This contains the runtime files and the native-code Scheme compiler. +This band is chosen when the @code{-compiler} command-line option is +supplied. + +@item edwin.com +This contains the runtime files and the Edwin text editor. This band is +chosen when the @code{-edwin} command-line option is supplied. + +@item all.com +This contains the runtime files, the native-code compiler, and Edwin. +This band is chosen when both the @code{-compiler} and @code{-edwin} +command-line options are supplied. @end table -Note that the @file{.com} files in the @file{lib} directory and -elsewhere in the MIT Scheme system are data files and @emph{not} -programs, so you should not try to run them. - - -@noindent -If you do not get this directory structure you are probably using the -wrong version of @file{unzip}. In this case use the version of -@file{unzip} that comes with MIT Scheme, in the same directory as the -@file{.zip} files. - -Perform the following steps to install Scheme: - -@enumerate -@item -@emph{Build the bands.} - -Make sure that you are in a command shell window and in the Scheme root -directory (you should be there already). Run the following commands by -typing in each line and pressing @kbd{Enter}. Each command (except -@samp{cd}) will open a window, do some processing, close the window, and -return to the prompt. - -@example -@group -cd c:\scheme -etc\mk_comp.bat -etc\mk_edwin.bat -etc\mk_all.bat -@end group -@end example - -This will create the files @file{lib\compiler.com}, -@file{lib\edwin.com}, and @file{lib\all.com}. +Depending on your needs, you may not need all of these files. For +example, if you always want the full development environment, you might +keep @file{all.com} and delete the others. Or if you will never use the +compiler, you could delete @file{compiler.com} and @file{all.com}. +Remember that you must keep at least one of these files to use Scheme. -These files are MIT Scheme `image' files (also called `bands'). An -image file is a collection of Scheme programs and data that has been -combined into a single file. @file{.com} files are not MSDOS or Windows -programs so do not try to run them. - -@file{lib\compiler.com} contains the runtime system (i.e.@: standard -Scheme definitions) plus the native code compiler. @file{lib\edwin.com} -contains the runtime system plus the Edwin editor. @file{lib\all.com} -contains the runtime system, the compiler and Edwin. - -You may now delete the files @file{lib\compdel.com} and -@file{lib\eddel.com}. - -If you are running Windows 3.1 you cannot run Scheme from the command -line. You need to make a folder containing icons to run Scheme (how to -do this is described below) and then run (double-click) the following -icons in turn, waiting for each one to finish before starting the next: -@samp{Build COMPILER.COM band}, @samp{Build EDWIN.COM band} and -@samp{Build ALL.COM band}. - -@item -@emph{Optional system configuration.} - -You may move the executable files @file{scheme.exe} and -@file{bchschem.exe} and the@* @file{.dll} files from @file{bin\} to any -directory that appears in your @samp{PATH}. We suggest that you leave -them put. - -Depending on your needs, you may want to keep only one of the -@file{scheme.exe} or@* @file{bchschem.exe} files; each of these files is -about 550 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. +In addition to bands, Scheme is distributed with two executable +programs: @file{scheme} (called @file{scheme.exe} on PC systems), and +@file{bchscheme} (called @file{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. @file{scheme.exe} allocates two memory heaps, and +garbage collection. @file{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. @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. +of the time the other heap is occupying valuable memory but doesn't hold +any interesting data. @file{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 -@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 -@emph{Optional system configuration.} - -You may move the @file{lib\} directory anywhere you like. You may -rename it to anything you like. (Here at MIT, we use -@file{c:\scheme\lib}.) After you have chosen where it will be located, -set the @code{MITSCHEME_LIBRARY_PATH} environment variable to be that -location. - -For example, if you decide to store the directory as @file{d:\schdata}, -On Windows 95 or Windows 3.1 you would add the following line to -@file{autoexec.bat}: - -@example -SET MITSCHEME_LIBRARY_PATH=D:\SCHDATA -@end example - -@noindent -@file{autoexec.bat} is usually in @file{c:\windows\autoexec.bat} or -@file{c:\autoexec.bat}. You can use the Notepad accessory to edit the -file. - -On Windows NT, environment variables can be set by editing -@file{autoexec.bat} or by using the `System' item in the Control Panel. - - -You can override the setting of @code{MITSCHEME_LIBRARY_PATH} with the -@code{-library} option to Scheme, for example: - -@example -scheme -library d:\schdata -@end example - -@noindent -If you always supply a @code{-library} option, it is not necessary to -have the environment variable defined. For example, instead of editing -@file{autoexec.bat}, you might create a @file{.bat} file or a shortcut -(icon) to invoke Scheme and pass it the @code{-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{Creating a Scheme folder (Program group).} - -This step creates a folder (or Program Manager group) called @samp{MIT Scheme 7.4.2} -which contains -shortcuts (icons) to invoke Scheme. - -This step creates a folder (or Program Manager group) called @samp{MIT -Scheme 7.4.2} containing shortcuts (icons) for running Scheme and for -reading the help files. The shortcuts called @samp{Runtime}, -@samp{Edwin}, @samp{Compiler}, and @samp{MIT Scheme (Edwin + Compiler)} -correspond to running Scheme with 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. - - -@emph{Windows 95, Windows NT:} -@noindent -Still at the @samp{c:\scheme} prompt, enter the following command line. - -@example -bin\scheme -library lib -load etc\pmgrp -@end example - -@emph{Windows 3.1:} -@noindent -On Windows 3.1 you have to use the @samp{File | Run..} menu option of the -Program Manager or File Manager and enter the full paths: - -@example -c:\scheme\bin\scheme -library c:\scheme\lib -load c:\scheme\etc\pmgrp.scm -@end example - -@noindent - -There is a bug in Windows 95 and Windows NT 4.0 that prevents the Edwin -shortcut from being created correctly. Each shortcut contains a -`target' which is like a command line. We were unable to create a -shortcut with a target containing parentheses. To get around this -problem, we have created the shortcut with an incorrect target. You -have to manually edit the shortcut to change the curly braces in the -target to parentheses. Also, if there are any double quote symbols, -remove them. The end of the target reads - -@example - -eval @{edit@} -@end example - -@noindent -but should read - -@example - -eval (edit) -@end example - -How to edit the shortcut: - -@enumerate -@item -Right click on the Start button, and select Open from the menu that appears. -A window will appear with all the first-level Start menu shortcuts. -@item -Double-click (with the left mouse button) on the "Programs" item. -@item -In the resulting window there will be a folder called @samp{MIT Scheme 7.4.2} -Double-click on it. -@item -Right-click on the @samp{Edwin} shortcut. -A menu will appear. -Choose `Properties' from this menu. -@item -You now get a dialog box with two tabs. -Select the `Shortcut' tab. -@item -You will see a line labeled `Target'. -This is the text that you should edit. -@item -Click OK and test the shortcut. (Double left click). When the shortcut -is correct, Scheme will create a window with the title `@samp{Edwin:*scheme*}' -@item -You can now close all those windows. -@end enumerate - - -On Windows 3.1 you can edit the same line like this: - -@enumerate -@item -Double-click the @samp{MIT Scheme 7.4.2} program group. -@item -Left-click ONCE on the Edwin item. -@item -Select File | Properties from the Program Manager menu. -@item -The same command line appear as above. -@end enumerate - - -@item -@emph{Installing debugging information} -@noindent -The two files @file{w32rtbci.zip} and @file{w32edbci.zip} contain -debugging information for the Scheme runtime and Edwin respectively. -The total space required for all of the debugging information is about 8 -megabytes. The runtime debugging information is the more useful as it -allows the debugger to give you source code level information on all of -the standard procedures like @samp{map} and @samp{number->string}. - -Debugging information can be installed by unzipping the -@file{w32rtbci.zip} and@* @file{w32edbci.zip} files in the @file{SRC} -subdirectory of the library directory. Start a command shell window (as -described earlier), and use it to enter the following commands: - -@example -@group -cd c:\scheme\lib -mkdir SRC -cd SRC -c:\download\unzip c:\download\w32rtbci -c:\download\unzip c:\download\w32edbci -@end group -@end example - -@noindent -The @file{SRC} directory should now contain three subdirectories called -@file{edwin}, @file{runtime} and @file{win32}. These directories in -turn contain lots of @file{.bci} files. - -To test that you have installed the debugging information correctly, try -to pretty-print a compiled procedure, for example, - -@example -(pp pp) -@end example - -@noindent -When the debugging information is installed correctly, Scheme will be -able to find the source code for the @code{pp} procedure, and display it -(about fifteen lines of Scheme code_). Otherwise it will use the short -opaque form, something like this: - -@example -#[compiled-procedure 13 ("pp" #x2) #xF #x646BF7] -@end example - -Debugging information files can be installed in another place. In this -case the @code{MITSCHEME_INF_DIRECTORY} environment variable should be -set to the directory path where you unzipped the @file{.zip} files. - -@end enumerate +@file{scheme}. If you don't have enough memory, or if you want to use +less memory and will accept slower performance, use @file{bchscheme}. +One way to tell that you don't have enough memory is to run +@file{scheme} for a while and see if your machine is paging during +garbage collection. +You might consider trying to use @file{scheme} and letting the operating +system's paging handle the lack of RAM. But usually you will find that +using @file{bchscheme} without paging is much faster than using +@file{scheme} with paging. Of course, if you are using @file{bchscheme} +and you're still paging, there's nothing you can do to win. @node Running Scheme, Using Scheme, Installation, Top @chapter Running Scheme @@ -1140,6 +666,7 @@ environment variables. * Customizing Scheme:: * Memory Usage:: * Command-Line Options:: +* Custom Command-line Options:: * Environment Variables:: * Starting Scheme from Windows:: * Leaving Scheme:: @@ -1155,17 +682,15 @@ scheme @end example @noindent -at your operating system's command interpreter. (Under Windows 3.1 you -must use the Program Manager's @samp{File | Run..} command, or an icon.) -Scheme will load itself, clear the screen, and print something like -this: +at your operating system's command interpreter. Scheme will load +itself, clear the screen, and print something like this: @example @group -Scheme saved on Monday March 25, 1996 at 2:15:03 PM - Release 7.4.2 - Microcode 11.151 - Runtime 14.168 +Scheme saved on Thursday June 10, 1999 at 12:28:55 PM + Release 7.5a + Microcode 11.163 + Runtime 14.180 @end group @end example @@ -1184,11 +709,10 @@ This information, which can be printed again by evaluating @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. +each time a new version of Scheme is released. @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. @cindex subsystem versions @cindex SF, version @@ -1200,11 +724,10 @@ 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. +and @samp{6.001} is the @sc{sicp} compatibility package. @cindex compiler, starting -If the compiler is supported for your machine, you can invoke it by -giving Scheme the @code{-compiler} option: +You can load the compiler by giving Scheme the @code{-compiler} option: @example scheme -compiler @@ -1233,7 +756,7 @@ 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} +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 @code{-heap} and other parameters. @@ -1243,12 +766,12 @@ 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 +the @samp{HOME} environment variable. Under unix, the file is called @file{.scheme.init}; on the PC it is called @file{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 -@file{.edwin} under Unix, and @file{edwin.ini} on the PC. +@file{.edwin} under unix, and @file{edwin.ini} on the PC. You can use both of these files to define new procedures or commands, or to change defaults in the system. @@ -1264,8 +787,8 @@ environment variables. @xref{Environment Variables}. @item @dfn{Icons}. @cindex icons -Under OS/2 and Windows it is possible to create icons that invoke Scheme -with different parameters. +Under OS/2 and Windows, and with some window managers under X11, it is +possible to create icons that invoke Scheme with different parameters. @end itemize @node Memory Usage, Command-Line Options, Customizing Scheme, Running Scheme @@ -1283,7 +806,7 @@ Scheme uses four kinds of memory: @itemize @bullet @item @cindex stack space -A @dfn{stack} that is used for recursive procedure calls, +A @dfn{stack} that is used for recursive procedure calls. @item @cindex heap space @@ -1307,17 +830,17 @@ that is implemented in C). @end itemize @noindent -@findex scheme -@findex bchscheme All kinds of memory except the last may be controlled either by command-line options or by environment variables. +@findex scheme +@findex bchscheme 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, +@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 +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. @@ -1342,43 +865,32 @@ 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 @code{-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. +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 @samp{(print-gc-statistics)} shows how much heap and constant space is available (@pxref{Garbage Collection}). -@node Command-Line Options, Environment Variables, Memory Usage, Running Scheme +@node Command-Line Options, Custom Command-line Options, Memory Usage, Running Scheme @section 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. (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.) +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 @ref{Custom Command-line Options}. These are the microcode options: @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. - @item -compiler @findex -compiler @findex MITSCHEME_COMPILER_BAND @@ -1388,8 +900,7 @@ specifies the use of large sizes, exactly like @code{-large}; if the 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. +file. @item -edwin @findex -edwin @@ -1400,21 +911,44 @@ specifies the use of large sizes, exactly like @code{-large}; if the 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. +file. -@item -large -@findex -large -Specifies that large heap, constant, and stack sizes should be used. -These are specified by the environment variables +@item -compiler -edwin +@findex MITSCHEME_ALL_BAND +If both the @code{-compiler} and @code{-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 +@code{MITSCHEME_ALL_BAND}, if defined, or @file{all.com}; the library +directories are searched to locate this file. -@findex MITSCHEME_LARGE_HEAP -@findex MITSCHEME_LARGE_CONSTANT -@findex MITSCHEME_LARGE_STACK -@example -@group -MITSCHEME_LARGE_HEAP -MITSCHEME_LARGE_CONSTANT +@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. + +@item -large +@findex -large +Specifies that large heap, constant, and stack sizes should be used. +These are specified by the environment variables + +@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 @@ -1451,6 +985,11 @@ 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. +The size specified by this option is incremented by the amount of heap +space needed by the band being loaded. Consequently, @code{-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. + @item -constant @var{blocks} @findex -constant Specifies the size of constant space in 1024-word blocks. Overrides any @@ -1460,7 +999,7 @@ and other subsystems. @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 +default. This is Scheme's stack, @emph{not} the unix stack used by C programs. @item -option-summary @@ -1483,16 +1022,16 @@ 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 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 +job. For example, using @file{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: @example -scheme < /usr/cph/foo.in >& /usr/cph/foo.out & +scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 & @end example -This option is ignored under non-Unix operating systems. +This option is ignored under non-unix operating systems. @item -nocore @findex -nocore @@ -1501,7 +1040,7 @@ 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. +This option is ignored under non-unix operating systems. @item -library @var{path} @findex -library @@ -1512,10 +1051,10 @@ 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. -On Unix, the elements of the list are separated by colons, and the +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}. +@samp{c:\scheme\lib}. @item -utabmd @var{filename} @findex -utabmd @@ -1538,8 +1077,9 @@ one of these options may be given. 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. +together with the @code{-compiler}, @code{-edwin}, or @code{-band} +options. This option is useful only for maintenance and development of +the MIT Scheme runtime system. @end table @noindent @@ -1554,7 +1094,8 @@ command-line options, all of which specify parameters affecting how 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. +if that is not defined, a standard temporary directory is used (see +@code{TMPDIR} in @pxref{Runtime Environment Variables}). @item -gc-file @var{filename} @findex -gc-file @@ -1579,20 +1120,20 @@ by this invocation of Scheme, and this option is not set. @item -gc-start-position @var{number} @findex -gc-start-position @findex MITSCHEME_GC_START_POSITION -Specifies the first byte position in @sc{gc} file at which the Scheme -process can write. If not given, the value of the environment -variable @code{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 +Specifies the first byte position in the @sc{gc} file at which the +Scheme process can write. If not given, the value of the environment +variable @code{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 @code{-gc-start-position} and @code{-gc-end-position}. @item -gc-end-position @var{number} @findex -gc-end-position @findex MITSCHEME_GC_END_POSITION -Specifies the last byte position in @sc{gc} file at which the Scheme -process can write. If not given, the value of the environment -variable @code{MITSCHEME_GC_END_POSITION} is used, and if that is not -defined, the sum of the start position (as specified by +Specifies the last byte position in the @sc{gc} file at which the Scheme +process can write. If not given, the value of the environment variable +@code{MITSCHEME_GC_END_POSITION} is used, and if that is not defined, +the sum of the start position (as specified by @code{-gc-start-position}) and the heap size is used. The area of the file used (and locked if possible) is the region between @code{-gc-start-position} and @code{-gc-end-position}. @@ -1603,12 +1144,12 @@ file used (and locked if possible) is the region between 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. +is not defined, the value @samp{16} is used. @end table @noindent The following command-line options are only used by an experimental -version of@* @file{bchscheme} that uses Unix System V-style shared +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. @@ -1654,7 +1195,7 @@ This option causes Scheme to ignore the @file{~/.scheme.init} or @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, +@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 @@ -1681,7 +1222,64 @@ option that starts with a hyphen. The files are loaded in the Unless explicitly handled, errors during loading are silently ignored. @end table -@node Environment Variables, Starting Scheme from Windows, Command-Line Options, Running Scheme +@noindent +The following option is supported only when the editor is loaded. + +@table @code +@item -edit +@findex -edit +This option causes the editor to start immediately when Scheme is +started. +@end table + +@node Custom Command-line Options, Environment Variables, Command-Line Options, Running Scheme +@section 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 +(@pxref{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 @var{keyword} defines the option that will be recognized on the +command line. The @var{keyword} must be a string starting with a hyphen +and containing at least one additional character. + +@deffn {procedure+} simple-command-line-parser keyword thunk +Defines @var{keyword} to be a simple command-line option. When this +keyword is seen on the command line, it causes @var{thunk} to be +executed. +@end deffn + +@deffn {procedure+} argument-command-line-parser keyword multiple? procedure +Defines @var{keyword} to be a command-line option that is followed by +one or more command-line arguments. @var{Procedure} is a procedure that +accepts one argument; when @var{keyword} is seen, it is called once for +each argument. + +@var{Multiple?}, if true, says that @var{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 @var{keyword} and does not +start with a hyphen. If @var{multiple?} is @code{#f}, @var{procedure} +is called once, with the command-line argument following @var{keyword}. +In this case, it does not matter if the following argument starts with a +hyphen. +@end deffn + +@deffn {procedure+} set-command-line-parser! keyword procedure +This low-level procedure defines @var{keyword} to be a command-line +option that is defined by @var{procedure}. When @var{keyword} is seen, +@var{procedure} is called with all of the command-line arguments, +starting with @var{keyword}, as a single list argument. @var{Procedure} +must return two values (using the @code{values} procedure): the unused +command-line arguments (as a list), and a thunk that is executed to +implement the behavior of the option. +@end deffn + +@node Environment Variables, Starting Scheme from Windows, Custom Command-line Options, Running Scheme @section Environment Variables Scheme refers to many environment variables. This section lists these @@ -1689,7 +1287,7 @@ 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 +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.@: @@ -1711,9 +1309,14 @@ procedure, e.g.@: 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). +unix, and @file{scheme.exe} and @file{bchschem.exe} on the PC). @table @asis +@item @code{MITSCHEME_ALL_BAND} (default: @file{all.com} on the library path) +@findex MITSCHEME_ALL_BAND +The initial band to be loaded if both the @code{-compiler} and +@code{-edwin} options are given. Overridden by @code{-band}. + @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}, @@ -1729,12 +1332,12 @@ Overridden by @code{-band}. The initial band to be loaded if the @code{-edwin} option is given. Overridden by @code{-band}. -@item @code{MITSCHEME_LARGE_CONSTANT} (default: @samp{1000}) +@item @code{MITSCHEME_LARGE_CONSTANT} (default: as needed) @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 depends on machine; on most machines it -is larger than @samp{1000}. +@code{-constant}. Note: the default is computed to be the correct size +for the band being loaded. @item @code{MITSCHEME_LARGE_HEAP} (default: @samp{1000}) @findex MITSCHEME_LARGE_HEAP @@ -1752,17 +1355,17 @@ The size of the stack, in 1024-word blocks, if the @code{-large}, @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 +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}. -@item @code{MITSCHEME_SMALL_CONSTANT} (default: @samp{450}) +@item @code{MITSCHEME_SMALL_CONSTANT} (default: as needed) @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 depends on machine; -on most machines it is larger than @samp{450}. +@code{-compiler}, or @code{-edwin}. Note: the default is computed to be +the correct size for the band being loaded. @item @code{MITSCHEME_SMALL_HEAP} (default: @samp{250}) @findex MITSCHEME_SMALL_HEAP @@ -1790,10 +1393,12 @@ These environment variables are referred to by @file{bchscheme} (@emph{not} by @file{scheme}). @table @asis -@item @code{MITSCHEME_GC_DIRECTORY} (default: @file{/tmp}) +@item @code{MITSCHEME_GC_DIRECTORY} @findex MITSCHEME_GC_DIRECTORY The directory in which @sc{gc} files are written. Overridden by -@code{-gc-directory}. +@code{-gc-directory}. The default for this variable is the standard +temporary directory (see @code{TMPDIR} in @pxref{Runtime Environment +Variables}). @item @code{MITSCHEME_GC_FILE} (default: @file{GCXXXXXX}) @findex MITSCHEME_GC_FILE @@ -1819,7 +1424,7 @@ Overridden by @code{-gc-window-size}. @noindent The following environment variables are only used by an experimental -version of Bchscheme that uses Unix System V-style shared memory, and +version of Bchscheme that uses unix System V-style shared memory, and then only if the @file{gcdrone} program is installed: @table @asis @@ -1847,15 +1452,23 @@ These environment variables are referred to by the runtime system. @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}. - -@item @code{TEMP} +Directory in which to look for init files. E.g.@: @samp{c:\users\joe} +or @samp{/home/joe}. This variable needs to be set on OS/2 and Windows +9x. Under Windows NT, the environment variables @code{HOMEDRIVE} and +@code{HOMEPATH}, set by the operating system, are used instead. Under +unix, @code{HOME} is set by the login shell. + +@item @code{TMPDIR} +@itemx @code{TEMP} @itemx @code{TMP} +@findex TMPDIR @findex TEMP @findex TMP -Directory for various temporary files. @samp{TEMP} is given preference -to @samp{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, @file{/var/tmp}, @file{/usr/tmp}, @code{/tmp}; under OS/2 +and Windows, @file{\temp}, @file{\tmp}, and @file{\} (all on the system +drive). @item @code{MITSCHEME_INF_DIRECTORY} (default: @samp{SRC} on the library path) @findex MITSCHEME_INF_DIRECTORY @@ -1898,7 +1511,7 @@ strings. 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)) +@item @code{SHELL} (default: @file{/bin/sh} (unix), @file{cmd.exe} (PC)) @findex SHELL Filename of the shell program to use in shell buffers and when executing shell commands. Used to initialize the @code{shell-path-name} editor @@ -1942,15 +1555,11 @@ These environment variables are specific to the Windows implementation. @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. +@samp{Courier New 16 bold}. Allowed characteristics are @var{integer}, +specifiying the font size in points, and the following style modifiers: +@samp{bold}, @samp{italic}, @samp{regular}, @samp{underline} and +@samp{strikeout}. 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. @@ -1992,7 +1601,8 @@ directory. This is the preferred way to specify the home directory. 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. +variables is defined, an error is signalled when the username is +required. @item @code{USERDIR} @findex USERDIR @@ -2013,52 +1623,52 @@ searching for a subdirectory with the user's login name. These environment variables are specific to the OS/2 implementation. -@table @asis -@item @code{USER} +@table @code +@item 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. +several different purposes. If this variable is undefined, an error is +signalled when the username is required. -@item @code{USERDIR} +@item 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. + +@item COMSPEC +@findex COMSPEC +Specifies the command shell. This is set in all versions of OS/2 (and +is required for proper operation of the operating system). Scheme uses +this to determine the user's shell if the environment variable +@code{SHELL} is not defined. @end table @node Starting Scheme from Windows, Leaving Scheme, Environment Variables, Running Scheme @section Starting Scheme from Windows The Windows version of MIT Scheme runs as a graphics-based application. -Under Windows NT and Windows 95, Scheme can be started from the command -line as described at the beginning of this chapter. - -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 it is -not a @sc{dos} program (although some people run other shell programs in -place of @file{command.com} that can run Windows applications). +Scheme can be started from the command line as described at the +beginning of this chapter. -Shortcuts (Windows 95) or Program Manager groups and icons (Windows 3.1 -and Windows NT) are a convenient way to start Scheme. -The rest of this section gives some tips on how to set up shortcuts -that run Scheme. If you are unfamiliar with -this concept you should read about it in the system help. +Shortcuts are a convenient way to start Scheme. The rest of this +section gives some tips on how to set up shortcuts that run Scheme. If +you are unfamiliar with this concept you should read about it in the +system help. @itemize @bullet @item -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 icon properties 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. +Under Windows NT shortcuts can be @emph{common} or @emph{personal}. +When setting common shortcuts it is important to make the shortcut +properties independent of the vagaries of the environment of the user +who is running them. @item Give the shortcut an accurate @var{Description}. @item Include absolute pathnames to @file{scheme.exe} and @file{bchscheme.exe} -in the icon @var{Command line}. +in the shortcut @var{Command line}. @item I you specify the @code{-library} command-line option then you do not @@ -2067,8 +1677,10 @@ variable. @item Set the shortcut's @var{Working Directory} to something sensible. On -Windows NT you can use @samp{%HOMEPATH%} to make Scheme start up in the -user's home directory. +Windows NT you can use @samp{%HOMEDRIVE%%HOMEPATH%} to make Scheme start +up in the user's home directory. On Windows 9x you can use +@samp{%HOME%} to achieve the same effect, provided that you have set the +@code{HOME} environment variable as we recommend. @item There are several icons available in the Scheme executable --- choose @@ -2076,13 +1688,8 @@ 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 - -@example --eval (edit) -@end example - -at the end of the command line. +editor. You also have to put @samp{-edit} at the end of the command +line. @end itemize @node Leaving Scheme, , Starting Scheme from Windows, Running Scheme @@ -2110,8 +1717,8 @@ be done lightly. 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 +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 @findex quit @@ -2246,14 +1853,13 @@ destroyed, and you may not be able to find out what happened. @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. +underlying operating system: under unix, @kbd{C-g} and @kbd{C-c}; under +OS/2 and Windows, @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. Note @@ -2348,8 +1954,9 @@ Another way to exit a @sc{repl} is to use the @code{restart} procedure: @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: +restart methods is different for each @sc{repl} and for each error; in +the case of an error @sc{repl}, this list is printed when the @sc{repl} +is started: @example @group @@ -2442,8 +2049,6 @@ which it was closed by evaluating (procedure-environment @var{procedure}) @end example -Your programs create new environments whenever a procedure is called. - Here is the procedure that changes the @sc{repl}'s environment: @deffn {procedure+} ge environment @@ -2544,29 +2149,44 @@ A number of built-in options are defined: @table @code @item compress -Code to compress and uncompress files. Undocumented. Used by the -runtime system for compression of compiled-code debugging information. +Support to compress and uncompress files. Undocumented; see the source +file @file{runtime/cpress.scm}. Used by the runtime system for +compression of compiled-code debugging information. @item format The @code{format} procedure. Documented in the Reference Manual. +@item gdbm +Support to access @code{gdbm} databases. Undocumented; see the source +file @file{runtime/gdbm.scm}. + @item hash-table The hash-table data type. Documented in the Reference Manual. @item ordered-vector -Code to search and do completion on vectors of ordered elements. -Undocumented. +Support to search and do completion on vectors of ordered elements. +Undocumented; see the source file @file{runtime/ordvec.scm}. @item rb-tree The red-black tree data type. Documented in the Reference Manual. +@item regular-expression +Support to search and match strings for regular expressions. Documented +in the Reference Manual. + @item stepper -Code to step through the evaluation of Scheme expressions. -Undocumented. Used by the Edwin command @kbd{M-x step-expression}. +Support to step through the evaluation of Scheme expressions. +Undocumented; see the source file @file{runtime/ystep.scm}. Used by the +Edwin command @kbd{M-x step-expression}. @item subprocess -Code to run other programs as subprocesses of the Scheme process. -Undocumented, but used extensively by Edwin. +Support to run other programs as subprocesses of the Scheme process. +Undocumented; see the source file @file{runtime/process.scm}. Used +extensively by Edwin. + +@item synchronous-subprocess +Support to run synchronous subprocesses. Documented in the reference +manual. @item wt-tree The weight-balanced tree data type. Documented in the Reference Manual. @@ -2598,8 +2218,8 @@ executed in order from left to right. 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 +The method writes a file containing all of the Scheme code and data 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}. @@ -2636,40 +2256,6 @@ 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. Your system is a C back end system if the following -expression does not evaluate to @code{#f}: - -@example -(system-library-directory-pathname "shared") -@end example - -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. -@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 @@ -2681,12 +2267,12 @@ Forces a garbage collection to occur. Returns the number of words of storage available after collection, an exact non-negative integer. @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. +to system tasks after the need for a garbage collection is detected and +before garbage collector is started. (An example of such a system task +is changing the run-light to show ``gc'' when scheme is running under +Emacs.) @strong{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 @deffn {procedure+} purify object [pure-space? [queue?]] @@ -2711,17 +2297,17 @@ 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. +The optional argument @var{queue?}, if @code{#f}, specifies that +@var{object} should be moved to constant space immediately; otherwise +@var{object} is 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 @deffn {procedure+} flush-purification-queue! @@ -2767,8 +2353,9 @@ GC #1: took: 0.13 (81%) CPU time, 0.15 (1%) real time; free: 207210 @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. +@var{on?} is true, notification is enabled; otherwise notification is +disabled. If @var{on?} is not given, it defaults to @code{#t}. When +Scheme starts, notification is disabled. The notification appears as a single line like the following, showing how many garbage collections have occurred, the time taken to perform the @@ -2781,7 +2368,7 @@ GC #5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346 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 +CPU time percentage 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 @code{-heap} command-line @@ -2798,9 +2385,7 @@ turned on, turns it off; otherwise turns it on. @chapter Compiling Programs 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. +the @code{-compiler} command-line option is specified. @menu * Compilation Procedures:: @@ -3456,7 +3041,7 @@ on the right. @item The @code{singleton} option specifies a function, @var{unop}, to be -invoked on the single argument left. This option supersedes the +invoked on the single argument given. This option supersedes the @code{null-value} option, which can only take the value @code{none}. @item @@ -3491,7 +3076,7 @@ operators and compile them efficiently. The @code{usual-integrations} declaration is usually sufficient to get good quality compiled code. -If you really need to squeeze more performance out of you code then we +If you really need to squeeze more performance out of your code then we hope that you find the following grab-bag of tips, hints and explanations useful. @@ -3629,6 +3214,12 @@ definitions of the following forms come first: @end group @end example +Note: The IEEE Scheme standard permits @emph{only} lambda expressions +and constants as the value of internal defines. Furthermore, all +internal definitions must appear before any other expressions in the +body. Following the standard simultaneously assures portability and +avoids the implementation inefficiencies described in this section. + @node Global variables, Fixnum arithmetic, Coding style, Efficiency Tips @subsection Global variables @@ -3755,9 +3346,9 @@ kinds of number. @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 +machine word. In MIT Scheme, fixnums are 26 bits on 32-bit machines, +and 56 bits on 64-bit machines; it is reasonable to assume that fixnums +are at least 24 bits. Fixnums are signed; they are encoded using 2's complement. All exact integers that are small enough to be encoded as fixnums are @@ -3771,37 +3362,11 @@ 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. +garbage collector. For a listing of all fixnum operations, see +@ref{Top, , Fixnum Operations, scheme, The MIT Scheme Reference Manual}. 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. @node Flonum arithmetic, , Fixnum arithmetic, Efficiency Tips @subsection Flonum arithmetic @@ -3928,7 +3493,7 @@ register, added, and stored again. There is no need for a temporary boxed flonum. @example -(flo:vector-set v 0 (flo:+ (flo:vector-ref v 0) 1.2)) +(flo:vector-set! v 0 (flo:+ (flo:vector-ref v 0) 1.2)) @end example In this next example, every time @code{g} is called, a new boxed flonum @@ -3997,10 +3562,8 @@ can return a complex number (e.g@: with argument @code{-1.5}). @node Debugging, GNU Emacs Interface, Compiling Programs, Top @chapter Debugging -@strong{This chapter is out of date and will eventually be revised}. - -This chapter is adapted from @cite{Don't Panic: A 6.001 User's Guide to -the Chipmunk System}, by Arthur A. Gleckler. +Parts of this chapter are adapted from @cite{Don't Panic: A 6.001 User's +Guide to the Chipmunk System}, by Arthur A. Gleckler. @cindex bugs @cindex debugging @@ -4081,12 +3644,12 @@ appear, be prepared to attack them with all the tools available. @menu * Subproblems and Reductions:: -* Debugger:: +* Command-Line Debugger:: * Debugging Aids:: * Advising Procedures:: @end menu -@node Subproblems and Reductions, Debugger, Debugging, Debugging +@node Subproblems and Reductions, Command-Line Debugger, Debugging, Debugging @section Subproblems and Reductions @cindex subproblem @@ -4156,26 +3719,27 @@ 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}. -@node Debugger, Debugging Aids, Subproblems and Reductions, Debugging -@section The Debugger +@node Command-Line Debugger, Debugging Aids, Subproblems and Reductions, Debugging +@section The Command-Line Debugger @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 @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}. - +There are two debuggers available with MIT Scheme. One of them runs +under Edwin, and is described in that section of this document +(@pxref{Edwin}). The other is command-line oriented, does not require +Edwin, and is described here. + +@cindex command-line debugger +The @dfn{command-line 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}. + 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 @@ -4211,7 +3775,7 @@ You are now in the debugger. Type q to quit, ? for commands. @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 +this is subproblem level 0, the first of 6 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 @@ -4220,21 +3784,169 @@ 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 +What follows is a description of the commands available in the debugger. +To understand how the debugger works, you need to understand that the +debugger has an implicit state that is examined and modified by +commands. The state consists of three pieces of information: a +@dfn{subproblem}, a @dfn{reduction}, and an @dfn{environment frame}. +Each of these parts of the implicit state is said to be @dfn{selected}; +thus one refers to the @dfn{selected subproblem}, and so forth. The +debugger provides commands that examine the selected state, and allow +you to select different states. + +Here are the debugger commands. Each of these commands consists of a +single letter, which is to be typed by itself at the debugger prompt. +It is not necessary to type @key{RET} after these commands. + +@table @asis +@item Traversing subproblems +@cindex Debugger command: u +@cindex Debugger command: d +@cindex Debugger command: g +@cindex Debugger command: h +The debugger has several commands for traversing the structure of the +continuation. It is useful to think of the continuation as a +two-dimensional structure: a backbone consisting of subproblems, and +associated ribs consisting of reductions. The bottom of the backbone is +the most recent point in time; that is where the debugger is positioned +when it starts. Each subproblem is numbered, with @code{0} representing +the most recent time point, and ascending integers numbering older time +points. The @kbd{u} command moves up to older points in time, and the +@kbd{d} command moves down to newer points in time. The @kbd{g} +command allows you to select a subproblem by number, and the @kbd{h} +command will show you a brief summary of all of the subproblems. + +@item Traversing reductions +@cindex Debugger command: r +@cindex Debugger command: b +@cindex Debugger command: f +If the subproblem description says that ``The execution history for this +subproblem contains @var{N} reduction(s)'', then there is a ``rib'' of +reductions for this subproblem. You can see a summary of the reductions +for this subproblem using the @kbd{r} command. You can move to the +next reduction using the @kbd{b} command; this moves you to the next +older reduction. The @kbd{f} command moves in the opposite direction, +to newer reductions. If you are at the oldest reduction for a given +subproblem and use the @kbd{b} command, you will move to the next older +subproblem. Likewise, if you are at the newest reduction and use +@kbd{f}, you'll move to the next newer subproblem. + +@item Examining subproblems and reductions +@cindex Debugger command: t +@cindex Debugger command: l +The following commands will show you additional information about the +currently selected subproblem or reduction. The @kbd{t} command will +reprint the standard description (in case it has scrolled off the +screen). The @kbd{l} command will pretty-print (using @code{pp}) the +subproblem's expression. + +@item Traversing environments +Nearly all subproblems and all reductions have associated environments. +Selecting a subproblem or reduction also selects the associated +environment. However, environments are structured as a sequence of +frames, where each frame corresponds to a block of environment +variables, as bound by @code{lambda} or @code{let}. These frames +collectively represent the block structure of a given environment. + +@cindex Debugger command: p +@cindex Debugger command: s +Once an environment frame is selected by the debugger, it is possible to +select the parent frame of that frame (in other words, the enclosing +block) using the @kbd{p} command. You can subsequently return to the +original child frame using the @kbd{s} command. The @kbd{s} command +works because the @kbd{p} command keeps track of the frames that you +step through as you move up the environment hierarchy; the @kbd{s} +command just retraces the path of saved frames. Note that selecting a +frame using @kbd{p} or @kbd{s} will print the bindings of the newly +selected frame. + +@item Examining environments +@cindex Debugger command: a +@cindex Debugger command: c +@cindex Debugger command: e +@cindex Debugger command: o +@cindex Debugger command: v +@cindex Debugger command: w +The following commands allow you to examine the contents of the selected +frame. The @kbd{c} command prints the bindings of the current frame. +The @kbd{a} command prints the bindings of the current frame and each +of its ancestor frames. The @kbd{e} command enters a read-eval-print +loop in the selected environment frame; expressions typed at that +@sc{repl} will be evaluated in the selected environment. To exit the +@sc{repl} and return to the debugger, evaluate @code{(abort->previous)} +or use @code{restart}. The @kbd{v} command prompts for a single +expression and evaluates it in the selected environment. The @kbd{w} +command invokes the environment inspector (@code{where}); quitting the +environment inspector returns to the debugger. Finally, the @kbd{o} +command pretty-prints the procedure that was called to create the +selected environment frame. + +@item Continuing the computation +@cindex Debugger command: k +There are three commands that can be used to restart the computation +that you are examining. The first is the @kbd{k} command, which shows +the currently active restarts, prompts you to select one, and passes +control to the it. It is very similar to evaluating @samp{(restart)}. + +The other two commands allow you to invoke internal continuations. This +should not be done lightly; invoking an internal continuation can +violate assumptions that the programmer made and cause unexpected +results. Each of these commands works in the same way: it prompts you +for an expression, which is evaluated in the selected environment to +produce a value. The appropriate internal continuation is then invoked +with that value as its sole argument. The two commands differ only in +which internal continuation is to be invoked. + +@cindex Debugger command: j +The @kbd{j} command invokes the continuation associated with +the selected subproblem. What this means is as follows: when the +description of a subproblem is printed, it consists of two parts, and +``expression'' and a ``subproblem being executed''. The latter is +usually marked in the former by the specific character sequence +@samp{###}. The internal continuation of the subproblem is the code +that is waiting for the ``subproblem being executed'' to return a +value. So, in effect, you are telling the program what the ``subproblem +being executed'' will evaluate to, and bypassing further execution of +that code. + +@cindex Debugger command: z +The @kbd{z} command is slightly different. It instead invokes the +continuation that is waiting for the outer ``expression'' to finish. In +other words, it is the same as invoking the @kbd{j} command in the next +frame up. So you can think of this as an abbreviation for the @kbd{u} +command followed by the @kbd{j} command. + +@item Wizard commands +@cindex Debugger command: m +@cindex Debugger command: x +@cindex Debugger command: y +The @kbd{m}, @kbd{x}, and @kbd{y} commands are for Scheme wizards. +If you want to find out what they do, read the source code. + +@item Miscellaneous commands +@cindex Debugger command: i +@cindex Debugger command: q +@cindex Debugger command: ? +The @kbd{i} command will reprint the error message for the error that +was in effect immediately before the debugger started. The @kbd{q} +command quits the debugger, returning to the caller. And the @kbd{?} +command prints a brief summary of the debugger's commands. +@end table + +@node Debugging Aids, Advising Procedures, Command-Line Debugger, Debugging @section Debugging Aids -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. +This section describes additional commands that are useful for debugging. -@deffn {procedure+} 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. The -environment of the read-eval-print loop is derived by examining the -continuation of the call to @code{bkpt}; if the call appears in a -non-tail-recursive position, the environment will be that of the call -site. To exit from the breakpoint and proceed with the interrupted -process, call the procedure @code{continue}. Sample usage: +@deffn {procedure+} bkpt datum argument @dots{} +Sets a breakpoint. When the breakpoint is encountered, @var{datum} and +the @var{argument}s are typed (just as for @code{error}) and a +read-eval-print loop is entered. The environment of the read-eval-print +loop is derived by examining the continuation of the call to +@code{bkpt}; if the call appears in a non-tail-recursive position, the +environment will be that of the call site. To exit from the breakpoint +and proceed with the interrupted process, call the procedure +@code{continue}. Sample usage: @example @group @@ -4262,32 +3974,69 @@ bar @end deffn @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). +However, since this is a very useful debugging tool, we also mention it +here. @code{pp} provides two very useful functions: + +@enumerate +@item +@code{pp} will print the source code of a given procedure. Often, when +debugging, you will have a procedure object but will not know exactly +what procedure it is. Printing the procedure using @code{pp} will show +you the source code, which greatly aids identification. + +@item +@code{pp} will print the fields of a record structure. If you have a +compound object pointer, print it using @code{pp} to see the component +fields, like this: + +@example +@group +(pp (->pathname "~")) +@print{} #[pathname 14 "/usr/home/cph"] +@print{} (host #[host 15]) +@print{} (device unspecific) +@print{} (directory (absolute "usr" "home")) +@print{} (name "cph") +@print{} (type ()) +@print{} (version unspecific) +@end group +@end example +When combined with use of the @code{#@@} syntax, @code{pp} provides the +functionality of a simple object inspector. For example, let's look at +the fields of the host object from the above example: + +@example +@group +(pp #@@15) +@print{} #[host 15] +@print{} (type-index 0) +@print{} (name ()) +@end group +@end example +@end enumerate +@end deffn + +@deffn {procedure+} pa procedure @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 -1 ]=> for-all? -;Value 40: #[compiled-procedure 40 ("boole" #x6) #xC #x20ECB0] - -1 ]=> (pa for-all?) -(items predicate) -;No value - -1 ]=> (pp for-all?) -(named-lambda (for-all? items predicate) - (let loop ((items items)) - (or (null? items) - (and (predicate (car items)) - (loop (cdr items)))))) +for-all? + @result{} #[compiled-procedure 40 ("boole" #x6) #xC #x20ECB0] + +(pa for-all?) +@print{} (items predicate) + +(pp for-all?) +@print{}(named-lambda (for-all? items predicate) +@print{} (let loop ((items items)) +@print{} (or (null? items) +@print{} (and (predicate (car items)) +@print{} (loop (cdr items)))))) @end group @end example @end deffn @@ -4323,15 +4072,14 @@ is @code{#f} if @var{package/env} is specified, and @code{#t} if @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 +(apropos "search") +@print{} #[package 41 (user)] +@print{} #[package 33 ()] +@print{} list-search-negative +@print{} list-search-positive +@print{} search-ordered-subvector +@print{} search-ordered-vector +@print{} vector-binary-search @end group @end example @end deffn @@ -4505,23 +4253,19 @@ 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. - -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. +guaranteed to be correct for your version of Scheme. Note that this +interface is supported under unix only. @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! - -@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 +To invoke Scheme from Emacs, load the @file{xscheme} library, then use +@kbd{M-x run-scheme}. 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! + +@emph{Note carefully:} In Emacs 19 and later, 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}. @findex scheme-interaction-mode @@ -4569,19 +4313,19 @@ commands for evaluating expressions (do @kbd{C-h m} in any @code{scheme-mode} buffer for the most up-to-date information): @table @kbd -@item @key{ESC} o -@kindex @key{ESC} o +@item M-o +@kindex M-o @findex xscheme-send-buffer Evaluates the current buffer (@code{xscheme-send-buffer}). -@item @key{ESC} z -@kindex @key{ESC} z +@item M-z +@kindex M-z @findex xscheme-send-definition Evaluates the current definition (@code{xscheme-send-definition}). This -is also bound to @kbd{@key{ESC} C-x}. +is also bound to @kbd{C-M-x}. -@item @key{ESC} C-z -@kindex @key{ESC} C-z +@item C-M-z +@kindex C-M-z @findex xscheme-send-region Evaluates the current region (@code{xscheme-send-region}). @@ -4590,7 +4334,7 @@ Evaluates the current region (@code{xscheme-send-region}). @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}}. +@kbd{M-@key{RET}}. @item C-c C-s @kindex C-c C-s @@ -4636,8 +4380,7 @@ Like typing @kbd{C-c C-b} when running Scheme without Emacs.@* @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}) +Like evaluating @code{(continue)}. (@code{xscheme-send-proceed}) @end table @node Edwin, Release Notes, GNU Emacs Interface, Top @@ -4682,7 +4425,7 @@ The procedure @code{edwin} is an alias for @code{edit}. @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 +@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. @@ -4721,7 +4464,7 @@ values are defined: @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 +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. @@ -4736,7 +4479,7 @@ window's geometry in the usual way. @var{Geometry} must be a character string whose contents is an X geometry specification. @item (console) -Unix only. Causes Edwin to run on Scheme's console, or in Unix +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. @@ -4797,7 +4540,7 @@ 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 +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}. @@ -4830,947 +4573,12 @@ Edwin's internal display data structures to get into an inconsistent state that prevents Edwin from running. @end deffn -@node Release Notes, Comparison of Edwin to Emacs, Edwin, Top +@node Release Notes, Index, Edwin, Top @appendix Release Notes -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. - -@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 - -@node 7.4 News, 7.3 News, Release Notes, Release Notes -@section Changes from Release 7.3 to 7.4 - -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. - -@noindent -Changes to Scheme: - -@itemize @bullet -@item -MIT Scheme is now supported under OS/2. - -@item -Illegally-placed internal definitions now signal an error. - -@item -Stream operations from the upcoming new edition of @sc{sicp} are -implemented. - -@item -The @code{load-option} procedure is now extensible, allowing users to -add their own options to the database. - -@item -Daylight-savings-time information is now included in the decoded time -data structure. -@end itemize - -@noindent -Changes to Edwin: - -@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}. - -@item -New command: @kbd{M-x step-expression}; steps through the evaluation of -a Scheme expression. - -@item -New command: @kbd{M-x grep}, as in Emacs. - -@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. - -@item -The editor variable @code{evaluate-in-inferior-repl} now defaults to -@code{#t}. - -@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. - -@item -Dired mode is no longer case-sensitive. - -@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. - -@item -New command in Dired: @kbd{+} creates a new directory. - -@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. - -@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. - -@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: - -@itemize @bullet -@item -Long filenames are now supported. - -@item -The network @file{\\@var{host}\@var{directory}} notation is now -supported. - -@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. - -@item -The runtime system now has better heuristics for determining the -user name and home directory. - -@item -The catatonia timeout has been extended to 120 seconds --- much more -reasonable on slow machines. - -@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 @code{MITSCHEME_FONT}. - -@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}. - -@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 - -@noindent -Changes Specific to Edwin under Windows: - -@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. - -@item -Multiple Edwin screens are now supported. - -@item -The handling of windows has been significantly improved; it is now -faster and less buggy. - -@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): - -@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. - -@item -The main console window now has a menu bar, which provides the following -operations: Exit, Copy, Paste, Set font, and About. - -@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. - -@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. - -@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. - -@item -The network @file{\\@var{host}\@var{directory}} notation is now -supported. -@end itemize - -@noindent -Changes Specific to Edwin under OS/2: - -@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. - -@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 - -@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. - -@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. - -@item -Support for dynamic loading of compiled C code on several operating -systems, including HP-UX, OSF/1, SunOS 4, and AIX. - -@item -New data structures: red/black trees and weight-balanced trees. - -@item -Redesign of hash tables makes them much faster and somewhat more -flexible. - -@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. - -@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 -symbolnamestring -->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 - -@item -@code{with-input-from-file} and @code{with-output-to-file} no longer -close the port when they are exited abnormally. - -@item -Redefined @code{#!optional} and @code{#!rest} to be something distinct -from symbols. - -@item -Strings now accept @code{"\@var{nnn}}" octal character escapes, much -like those in C. - -@item -Redesign of pathname abstraction. New design is very similar to the -Common Lisp pathname abstraction. - -@itemize @bullet -@item -->PATHNAME no longer accepts a symbol as an argument. Only strings -and pathnames are valid. - -@item -Procedures eliminated: - -@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 - -@item -@code{pathname-default} no longer accepts a @var{host} argument. - -@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 -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 -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 -New Edwin features: - -@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 - -@c @node Known Problems, Comparison of Edwin to Emacs, Release Notes, Top -@c @appendix Known Problems -@c -@c Edwin autoloads. -@c A few files that are automatically part of Edwin under Unix are not part -@c of Edwin in the PC. These can be loaded manually from the auto-load -@c directory, for example, by putting -@c -@c @example -@c (edwin-load "dabbrev") -@c @end example -@c -@c @noindent -@c in your @file{edwin.ini} file. -@c @end itemize - -@node Comparison of Edwin to Emacs, Index, Release Notes, Top -@appendix Comparison of Edwin to Emacs - -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:: -* Deficiencies of Edwin:: -* Subsystems Missing from Edwin:: -* Commands Missing from Edwin:: -* Variables Missing from Edwin:: -* Per-Buffer Variables:: -* Edwin Bugs:: -@end menu - -@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 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. - -@item -@kbd{C-z} doesn't suspend Edwin. @kbd{C-x C-z} suspends both Emacs and -Edwin, but isn't defined in the Emacs Manual. Under X, Emacs produces -an error message when @kbd{C-x C-z} is typed; Edwin suspends itself if -it was started from a shell with job control, otherwise it dies. - -@item -@kbd{C-h f} doesn't work for anything but editor commands, i.e.@: it -only documents editor commands, not ordinary Scheme procedures like -@code{car} or @code{call-with-current-continuation}. - -@item -@kbd{C-h v} doesn't work for anything but editor variables, i.e.@: it -only documents editor variables, not ordinary Scheme variables. - -@item -In Edwin, @kbd{C-w} and @kbd{C-y} don't skip to next occurrence in -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 -called with no arguments and with point at the beginning of the comment; -in Edwin, it is called with a single argument, the mark at the beginning -of the comment, and with point undefined. - -@item -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 -differently in Edwin. - -@item -The evaluation commands are much different in Edwin. - -@item -Edwin doesn't recognize @samp{Local Variables:} at the end of a file; -instead it recognizes @samp{Edwin Variables:}. This is done because it -cannot support the full syntax of Emacs local variables. - -@item -Variable @code{text-mode-hook} is an event distributor rather than a -procedure of no arguments. -@end itemize - -@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. - -@itemize @bullet -@item -@kbd{C-x ^} can be used to grow or shrink the minibuffer window in Emacs -but not in Edwin. - -@item -@kbd{C-h} in Edwin is a subset of that in Emacs. -Missing subcommands: - -@example -n view-emacs-news -c-c describe-copying -c-d describe-distribution -c-w describe-warranty -@end example - -@item -Dired is missing these commands in Edwin: @kbd{v} and @kbd{B}. - -@item -@kbd{C-x n} is not disabled by default. - -@item -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 to Emacs -@section Missing Subsystems - -The following documented subsystems are implemented by Emacs but not by -Edwin. - -@itemize @bullet -@item -abbrev mode (edwin has dynamic abbreviations) - -@item -emulation modes: edt, vi, vip - -@item -file locks - -@item -language modes: emacs-lisp, fortran, lisp, modula-2, prolog - -@item -overwrite mode - -@item -picture mode - -@item -slow terminal incremental search - -@item -spelling - -@item -tab stops - -@item -text formatter modes: nroff, scribe, tex, latex -@end itemize - -@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 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 - abbrev-prefix-mark - add-change-log-entry - add-change-log-entry-other-window - add-global-abbrev - add-mode-abbrev - add-name-to-file - append-to-buffer - byte-compile-file - byte-recompile-directory - cancel-debug-on-entry -* compile - convert-mocklisp-buffer - copy-to-buffer - debug-on-entry - define-abbrevs -* delete-matching-lines -* delete-non-matching-lines - describe-copying - describe-distribution - describe-no-warranty - describe-syntax - disable-command - disassemble - display-time @r{(}run-notifier @r{is similar)} - dissociated-press - doctor - edit-abbrevs - edit-abbrevs-redefine - edit-options - edit-picture - edit-tab-stops - edit-tab-stops-note-changes - edt-emulation-on - emacs-lisp-mode - emacs-version - enable-command - expand-abbrev - expand-region-abbrevs - flush-lines - fortran-mode - global-set-key @r{(}set-key @r{is similar)} - grep - hanoi - indent-c-exp c-indent-expression - insert-abbrevs - insert-kbd-macro write-kbd-macro - insert-parentheses - inverse-add-global-abbrev - inverse-add-mode-abbrev -* keep-lines - kill-all-abbrevs - latex-mode Note: BAL has one - lisp-complete-symbol @r{(}scheme-complete-variable @r{is similar)} - lisp-interaction-mode @r{(}inferior-repl-mode @r{is similar)} - lisp-mode - lisp-send-defun - list-abbrevs - list-command-history - list-options - list-tags - local-set-key -* lpr-buffer -* lpr-region - make-symbolic-link - make-variable-buffer-local -* manual-entry - modify-syntax-entry - move-past-close-and-reindent - next-error - next-file - nroff-mode -* occur -* occur-mode-goto-occurrence - open-dribble-file - open-termscript - overwrite-mode - plain-tex-mode - prepend-to-buffer -* print-buffer -* print-region - read-abbrev-file - recover-file - run-lisp - save-buffers-kill-emacs save-buffers-kill-scheme - set-gosmacs-bindings -* shell-command -* shell-command-on-region - spell-buffer - spell-region - spell-string - spell-word - suspend-emacs suspend-scheme - tab-to-tab-stop - tags-apropos - tex-mode - top-level - unexpand-abbrev - vi-mode - view-buffer - view-emacs-news - view-file - vip-mode - write-abbrev-file - yow - zap-to-char -@end example - -@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 under Unix and OS/2, -but not under Windows. - -@example - abbrev-all-caps - abbrev-file-name - blink-matching-paren - blink-matching-paren-distance - buffer-read-only - c-tab-always-indent - comment-start-skip -* compile-command - completion-ignore-case @r{(not documented)} - ctl-arrow - debug-on-error debug-on-editor-error - debug-on-internal-error - debug-on-evaluation-error - @r{are similar, but more specific} - debug-on-quit - default-directory - default-major-mode - echo-keystrokes - initial-major-mode @r{Scheme variable} initial-buffer-mode - insert-default-directory - inverse-video - kill-ring-max - load-path -* lpr-switches - major-mode - mark-ring - mark-ring-max mark-ring-maximum - meta-flag - no-redraw-on-recenter - save-abbrevs - selective-display-ellipses -* shell-file-name - tab-stop-list - tags-file-name @r{(}tags-table-pathname@r{ is similar)} - track-eol - visible-bell -@end example - -@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. - -@example -abbrev-mode -auto-fill-hook -buffer-auto-save-file-name -buffer-backed-up -buffer-file-name -buffer-offer-save -buffer-read-only -buffer-saved-size -buffer-undo-list -ctl-arrow -default-directory -local-abbrev-table -major-mode -mark-ring -mode-name -overwrite-mode -selective-display -selective-display-ellipses -shell-prompt-pattern -@end example - -@node Edwin Bugs, , Per-Buffer Variables, Comparison of Edwin to Emacs -@section Edwin Bugs - -Incorrect behavior of Edwin that will be fixed: - -@itemize @bullet -@item -Negative argument to @kbd{M-u}, @kbd{M-l}, and @kbd{M-c} seems to work -by accident. - -@item -@samp{-*- foo -*-} is valid if preceded only by blank lines; in Edwin -this works only if it is on a file's the first line. - -@item -Closing paren doesn't check for mismatched delimiters and issue warning -message. In c-mode, @samp{]} isn't treated specially, and don't flash -the matching delimiter. - -@item -@kbd{C-u C-x ;} isn't handled right in Edwin. - -@item -@kbd{M-x indent-for-comment} shouldn't reindent existing comment in -column zero. -@end itemize +The last full release of MIT Scheme was version 7.4.7 in 1998. -@node Index, , Comparison of Edwin to Emacs, Top +@node Index, , Release Notes, Top @unnumbered Index @printindex cp -- 2.25.1