\input texinfo @c -*-texinfo-*-
@comment %**start of header
-@setfilename mit-scheme-user
-@set EDITION 1.94
-@set VERSION 9.2.1
-@set UPDATED 2015-11-25
-@settitle MIT/GNU Scheme @value{VERSION}
+@setfilename mit-scheme-pucked-user
+@comment From automake's version.texi someday:
+@set UPDATED 12 March 2017
+@set EDITION 1.0
+@comment Override VERSION with Scheme version.
+@set VERSION 9.2.7
+@settitle MIT/GNU Scheme Pucked @value{VERSION} User Manual
@comment %**end of header
@setchapternewpage odd
@finalout
@syncodeindex tp cp
@copying
-This manual documents the use of MIT/GNU Scheme @value{VERSION}.
+This manual documents the use of MIT/GNU Scheme Pucked @value{VERSION}.
+
+Copyright @copyright{} 2016, 2017 Matthew Birkholz
Copyright @copyright{} 1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993,
1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
@end quotation
@end copying
-@dircategory Programming Languages
+@dircategory MIT/GNU Scheme Pucked
@direntry
-* MIT/GNU Scheme User: (mit-scheme-user).
- User's Manual
+* User Manual: (mit-scheme-pucked-user).
@end direntry
@titlepage
-@title MIT/GNU Scheme User's Manual
-@subtitle Edition @value{EDITION} for MIT/GNU Scheme @value{VERSION}
+@title MIT/GNU Scheme Pucked User Manual
+@subtitle Edition @value{EDITION} for MIT/GNU Scheme Pucked @value{VERSION}
@subtitle @value{UPDATED}
@author by Stephen Adams
@author Chris Hanson
+@author Matt Birkholz
@author and the MIT Scheme Team
@page
@vskip 0pt plus 1filll
@ifnottex
@node Top, Introduction, (dir), (dir)
-@top MIT/GNU Scheme
+@top MIT/GNU Scheme Pucked User Manual
@insertcopying
@end ifnottex
@menu
* Introduction::
+* Changes::
* Installation::
* Running Scheme::
* Using Scheme::
* Profiling::
* GNU Emacs Interface::
* Edwin::
-* Release Notes::
* GNU Free Documentation License::
* Environment-variable Index::
* Option Index::
@node Introduction, Installation, Top, Top
@unnumbered Introduction
-This document describes how to install and use MIT/GNU Scheme, the
+This document describes how to install and use MIT/GNU Scheme Pucked,
+and experimental version of MIT/GNU Scheme, the
UnCommon Lisp. It gives installation instructions for all of the
-platforms that we support; complete documentation of the command-line
+supported platforms; complete documentation of the command-line
options and environment variables that control how Scheme works; and
rudimentary descriptions of how to interact with the evaluator, compile
-and debug programs, and use the editor. The release notes are included
-as an appendix.
-
-@cindex Unix
-@cindex Windows
-@cindex PC
-This document discusses many operating-system specific features of the
-MIT/GNU 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 and the BSD variants. We use the term
-@dfn{Windows} to collectively refer to the modern Microsoft Windows
-32-bit operating systems: Windows XP, Windows Vista, Windows 7, and
-Windows 8. We use the term @dfn{PC} to refer to any computer running
-Windows. Thus we consider a PC to be a system with a @acronym{DOS}-like
-file system, using backslashes for directory separators, drive letters,
-@sc{cr-lf} line termination, and (potentially) the hideous 8.3 short
-filenames.
+and debug programs, and use the editor.
+
+This experimental version is basically a snapshot of the development
+branch on Savannah with a selection of plugins. Differences between
+this ``pucked'' version and the development branch have been kept to a
+minimum. At the moment they are all about replacing microcode modules
+with plugins and extending Edwin with a Gtk screen. User visible
+effects of these changes are detailed in a following chapter.
+@xref{Changes}.
@cindex Web site
The primary distribution site for this software is
+@example
+@uref{http://birchwood-abbey.net/~matt/Scheme/}
+@end example
+The release notes are online at the following url.
+@example
+@uref{http://birchwood-abbey.net/~matt/Scheme/release.html}.
+@end example
+
+@cindex bugs, reporting
+@cindex reporting bugs
+To report bugs, send email to
@example
-@uref{http://www.gnu.org/software/mit-scheme/}
+@uref{puck@@birchwood-abbey.net}
@end example
+Please include the output of the @code{identify-world} procedure
+(@pxref{Basics of Starting Scheme}), so Puck knows what versions you
+are using.
+
+@section The Plugins
+
+This Scheme comes with several plugins. Many wrap a C library like
+@code{libgdbm} and only work on systems where that library is
+installed along with a dynamic loader by which to link to it. At the
+moment this means they are supported only on GNU/Linux systems.
+
+Some of the plugins are simple conversions of MIT/GNU Scheme's old
+microcode modules. They are already available as sample code in the
+project repository on Savannah. In this experimental version of
+MIT/GNU Scheme they have actually replaced the microcode modules.
+And a couple are plugin-able versions of Edwin and IMAIL
+@raggedright
+@multitable @columnfractions .15 .30 .55
+@headitem Option name @tab Dependencies @tab Description
+@item @code{blowfish}
+@tab @code{libssl}
+@tab Replaces the (runtime blowfish) package.
+@item @code{gdbm}
+@tab @code{libgdbm}
+@tab Replaces the (runtime gdbm) package.
+@item @code{mcrypt}
+@tab @code{libmcrypt}
+@tab Autoloaded by the (runtime crypto) package.
+@item @code{md5}
+@tab @code{libssl}
+@tab Autoloaded by the (runtime crypto) package.
+@item @code{mhash}
+@tab @code{libmhash}
+@tab Autoloaded by the (runtime crypto) package.
+@item @code{edwin}
+@tab @code{blowfish}, @code{md5}, @code{gdbm}
+@tab The original Edwin and its tty screen.
+@item @code{imail}
+@tab @code{edwin}
+@tab The original IMAIL.
+@item @code{x11}
+@tab @code{libX11}
+@tab Replaces the (runtime x-graphics) package and
+primitives of the X11 microcode module.
+@item @code{x11-screen}
+@tab @code{x11}, @code{edwin}
+@tab The original X11 screen type.
+@end multitable
+@end raggedright
+@sp 1
+Several of the plugins are experimental wrappers for GNOME3 and OpenGL
+libraries. Their source code is available from Birchwood Abbey.
+@raggedright
+@multitable @columnfractions .15 .30 .55
+@headitem Option name @tab Dependencies @tab Description
+@item @code{glib}
+@tab @code{libglib2}
+@tab GLib and GIO wrapper.
+@item @code{pango}
+@tab @code{glib}, @code{libglib2}
+@tab Pango wrapper.
+@item @code{cairo}
+@tab @code{pango}, @code{libcairo2}
+@tab Cairo wrapper.
+@item @code{gtk}
+@tab @code{cairo}, @code{libgtk-3}, @code{libgdk-pixbuf2}
+@tab Gtk+3 wrapper.
+@item @code{gtk-screen}
+@tab @code{gtk}
+@tab A Gtk screen for Edwin.
+@item @code{gl}
+@tab @code{gtk}, @code{libGLU1}
+@tab OpenGL Utilities wrapper.
+@item @code{planetarium}
+@tab @code{gtk}, @code{gl} optional
+@tab Just a tellurion at the moment.
+@end multitable
+@end raggedright
+@sp 1
+Instructions for installing Scheme and its 'mental plugins on a GNU or
+at least Unix-like system can be found in a following chapter.
+@xref{Installation}.
+
+@node Changes
+@chapter Changes
+
+This experimental version of MIT/GNU Scheme was given a new project
+name, MIT/GNU Scheme Pucked, with a new command name,
+@code{mit-scheme-pucked}, so that it can be installed alongside the
+stable version. The names of the plugin packages also changed, but
+not their option names in Scheme (arguments to @code{load-option}).
+
+The core system is largely unchanged by this accommodation of the new
+plugins. If you previously said
+@example
+ $ mit-scheme --load my-shtick
+@end example
+@noindent
+you should be able to say
+@example
+ $ mit-scheme-pucked --load my-shtick
+@end example
@noindent
-Although our software is distributed from other sites and in other
-media, the complete distribution and the most recent release is always
-available at our site.
+and be no worse off.
-@cindex bugs, reporting
-@cindex reporting bugs
-To report bugs, use the bug-reporting tool at
+@noindent
+Users may want to add the following to their shtick.
+@itemize @bullet
+@item
+Scheme's Debian packaging includes a @file{.menu} file in
+@url{freedesktop.org} format. In the right place it makes this Scheme
+available through any @file{.menu} aware application launcher. The
+lucky user can install the @code{x11-screen} package and find a launch
+button, a picture of a lambda holding a fountain pen.
+
+@item
+The installation process includes HTML documentation by default. In
+the right place these files are available in your web browser, whether
+online or offline, using a file URL like the following Ubuntu locator.
@example
-@uref{http://savannah.gnu.org/projects/mit-scheme/}
+ @url{file:///usr/share/doc/mit-scheme-pucked/html/}
@end example
+HTML documentation for installed plugins is found in the same location.
+
+@item
+Lucky users can install a Planetarium package and see some fancy,
+Scheme-generated graphics.
+
+@item
+And users who are @emph{really} lucky can install the Gtk Screen
+package and try out a graphical Edwin.
+@end itemize
@noindent
-Please include the output of the @code{identify-world} procedure
-(@pxref{Basics of Starting Scheme}), so we know what version of the
-system you are using.
+Users may also need to make the following changes to their shtick.
-@node Installation, Running Scheme, Introduction, Top
-@chapter Installation
+@itemize @bullet
-This chapter describes how to install MIT/GNU Scheme. The release is
-supported under various unix and Windows operating systems. Read the
-section detailing the installation for the operating system that you are
-using.
+@item
+The Edwin subsystem is now a plugin; it is no longer included in the
+default band, @file{all.com}. However that band still handles the
+@code{--edit} command line option and provides an @code{edit}
+procedure. Either method of launching Edwin autoloads it with an
+appropriate screen type. If you are launching Edwin some other way,
+you will probably need to load a screen option first, e.g.@:
+@code{x11-screen}.
-@menu
-* Unix Installation::
-* Windows Installation::
-* Portable C Installation::
-@end menu
+@item
+The @code{(runtime gdbm)} and @code{(runtime x-graphics)} packages
+were removed. All of their bindings can now be found in the
+@code{(gdbm)} and @code{(x11 graphics)} packages. Thus @code{(runtime
+gdbm)} should be replaced with @code{(gdbm)} in package descriptions,
+and a @code{(global-definitions gdbm/)} line added. A similar
+change is needed if you are using @code{(runtime x-graphics)}.
+
+One original binding cannot be found in the new packages:
+@code{gdbm-available?}. Generally, @code{-available?} procedures are
+not supported. Plugins are unknown (cannot provide such procedures)
+until @emph{after} they successfully load (at which point such
+procedures are moot). Thus something like
+@code{(gdbm-available?)} should be replaced with
+@code{(plugin-available? "gdbm")}.
-@node Unix Installation, Windows Installation, Installation, Installation
-@section Unix Installation
+@item
+The @code{(runtime postgresql)} package was removed but has not yet
+been replaced with a corresponding plugin. If you were using it, let
+Puck know.
-We will use as an example the installation for GNU/Linux. The
-installation for other unix systems is similar. There are several
-references to @var{ARCH} below; these refer to the computer
-architecture that Scheme is compiled for, either @samp{i386} or
-@samp{x86-64}.
+@item
+The @code{(runtime crypto)} and @code{(runtime blowfish)} packages are
+provided but deprecated. Their bindings are unassigned until
+corresponding plugins are loaded. When a band is restored these
+bindings are unassigned again. Thus a restored thread using them will
+quickly signal an error and can be aborted or restarted as
+appropriate. Four bindings, @code{blowfish-available?},
+@code{mcrypt-available?}, @code{md5-available?} and
+@code{mhash-available?}, are assigned procedures that autoload the
+appropriate options. A restarted thread is assumed to begin again
+with a call to one of these.
-MIT/GNU Scheme is distributed as a compressed `tar' file. The tar
-file contains both source and binary files; the binary files are
-pre-compiled Scheme code for a particular computer architecture.
+@item
+Edwin has had a number of screen procedures turned into SOS generic
+procedures, to support the experimental Gtk screen type. Such changes
+are transparent except that loading Edwin now loads SOS.
-In order to install the software, it's necessary to configure and
-compile the C code, then to install the combined C and Scheme
-binaries. This is done in the following steps:
+@end itemize
+
+@node Installation
+@chapter Installation
+
+Debian packages are the simplest way to install. The package
+manager's dependency handling will arrange to install other necessary
+plugins and external libraries. To get a system as much like the
+original MIT/GNU Scheme as possible, able to run IMAIL in a basic X11
+screen, you will want to install the
+@code{mit-scheme-pucked-x11-screen} and @code{mit-scheme-pucked-imail}
+packages.
+
+Until the Debian packages become available in a public package
+archive, you will need to download @file{.deb} files from the
+website and use the @code{dpkg} command to install them. Instructions
+on the website should make plain what files you need. Install each
+file, in order, with a command like this:
+@example
+ sudo dpkg --install mit-scheme-pucked-9.2.7_1.deb
+@end example
+
+If you cannot install Debian packages, you can install binary tarballs
+on almost any Unix-like system. Installation involves compiling some
+C code, so your system will need a C compiler and developer packages
+for the external libraries your chosen plugins will need.
+Installation of a plugin requires that Scheme be installed first, so
+you will begin by downloading and installing the binary for the core
+Scheme system. Follow the instructions on the website to download the
+appropriate tarball.
+
+The distributed binary tarballs
+contain both source and binary files; the binary files are
+pre-compiled Scheme code for a particular computer architecture. The
+@samp{x86-64} and @samp{i386}binaries contain native instructions for
+Intel@registeredsymbol{} 64 and IA-32 architecture machines. On other
+architectures you can use @samp{svm1-32} or @samp{svm1-64} binaries;
+they contain instructions for a virtual machine included in the C code.
+
+To compile the C code take the following steps:
@enumerate
@item
-Unpack the tar file,
-@file{mit-scheme-@var{VERSION}-@var{ARCH}.tar.gz}, into the directory
-@file{mit-scheme-@var{VERSION}}. For example,
+Unpack the tar file, e.g.@:
+@file{mit-scheme-pucked-9.2.7-i386.tar.gz}, to create the build
+directory, e.g.@:
+@file{mit-scheme-pucked-9.2.7}. For example,
@example
-tar xzf mit-scheme-@var{VERSION}-i386.tar.gz
+tar xzf mit-scheme-pucked-9.2.7-i386.tar.gz
@end example
-will create a new directory @file{mit-scheme-@var{VERSION}}.
+will create a new directory @file{mit-scheme-pucked-9.2.7}.
@item
Move into the @file{src} subdirectory of the new directory:
@example
-cd mit-scheme-@var{VERSION}/src
+cd mit-scheme-pucked-9.2.7/src
@end example
@item
By default, the software will be installed in @file{/usr/local}, in
the subdirectories @file{bin} and @file{lib}. If you want it
-installed somewhere else, for example @file{/opt/mit-scheme}, pass the
-@option{--prefix} option to the configure script, as in
-@kbd{./configure --prefix=/opt/mit-scheme}.
+installed somewhere else, for example @file{/opt/mit-scheme-pucked}, pass the
+@option{--prefix} option to the configure script, as in the
+command line below.
+@example
+./configure --prefix=/opt/mit-scheme-pucked
+@end example
The configure script accepts all the normal arguments for such
scripts, and additionally accepts some that are specific to MIT/GNU
Scheme. To see all the possible arguments and their meanings, run the
-command @kbd{./configure --help}.
+command @code{./configure --help}.
@item
Build the software:
may need super-user privileges to do the installation step.
@end enumerate
-@emph{After} you have installed Scheme, you can install a few
-dynamically loadable options. These are configured, built and
-installed in the customary way. To install the @code{GDBM2} and
-@code{MHASH} options:
+@emph{After} you have installed Scheme, you can install the plugins.
+These are configured, built and installed in the customary GNU way.
-@smallexample
-(cd gdbm && make && make install)
-(cd mhash && ./configure && make && make install)
-@end smallexample
+@example
+tar xzf mit-scheme-pucked-gtk-0.5-i386.tar.gz
+cd mit-scheme-pucked-gtk-0.5
+./configure
+make tags all check
+make install
+@end example
The @code{make install} command will attempt to create a subdirectory
in the first directory on the host Scheme's library path. If that
You can put a writable directory at the front of your host Scheme's
library path by setting the @code{MITSCHEME_LIBRARY_PATH} environment
variable
-
-@smallexample
-export MITSCHEME_LIBRARY_PATH=\
- ~/mit-scheme-plugins:/usr/local/lib/mit-scheme-x86-64
-@end smallexample
-
+@example
+export MITSCHEME_LIBRARY_PATH=~/pucked:/opt/mit-scheme-pucked
+@end example
+@noindent
or including the @code{--library} option on the command line.
+@example
+mit-scheme-pucked --library ~/pucked:/opt/mit-scheme-pucked
+@end example
-@smallexample
-mit-scheme --library ~/mit-scheme-plugins:/usr/local/lib/mit-scheme-svm
-@end smallexample
-
-A few of the included options wrap popular Unix libraries. To compile
+A few of the included plugins wrap popular Unix libraries. To compile
and link them you often need ``developers' packages'' installed first.
-The following table lists the included options and an example
+The following table lists the included plugins and an example
developers' package name (and shared library name). The package names
can vary quite a bit among Unix distributions; the library names less
-so. Please see the @file{README} file in each option's subdirectory
+so. Please see the @file{README} file in each plugin's directory
for more information.
-
-@table @option
-@item BLOWFISH
-libssl-dev (-lcrypto)
-@item GDBM2
-libgdbm-dev (-lgdbm)
-@item MD5
-libssl-dev (-lcrypto)
-@item MHASH
-libmhash-dev (-lmhash)
-@end table
-
+@raggedright
+@multitable @columnfractions .2 .5
+@headitem Option name @tab Developer Package
+@item @code{blowfish}
+@tab @code{libssl-dev}
+@item @code{gdbm}
+@tab @code{libgdbm-dev}
+@item @code{mcrypt}
+@tab @code{libmcrypt-dev}
+@item @code{md5}
+@tab @code{libssl-dev}
+@item @code{mhash}
+@tab @code{libmhash-dev}
+@item @code{x11}
+@tab @code{libx11-dev}
+@item @code{glib}
+@tab @code{libglib2.0-dev}
+@item @code{pango}
+@tab @code{libpango1.0-dev}
+@item @code{cairo}
+@tab @code{libcairo2-dev}
+@item @code{gtk}
+@tab @code{libgtk-3-dev}
+@item @code{gl}
+@tab @code{libglu1-mesa-dev}
+@end multitable
+@end raggedright
+
+@sp 1
After installing the software and any options, you can delete the
-unpacked directory:
-
-@example
-cd ../..
-rm -rf mit-scheme-@var{VERSION}
-@end example
-
-@node Windows Installation, Portable C Installation, Unix Installation, Installation
-@section Windows Installation
-
-This section describes how to install MIT/GNU Scheme on Windows 2000,
-Windows XP, Windows Vista, or Windows 7.
-
-MIT/GNU 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/GNU Scheme is
-to be installed, and the name of the folder in which the shortcuts are
-to be placed.
-
-To uninstall the software, open up the @samp{Control Panel}, run
-@samp{Add/Remove Programs}, and double-click on @samp{MIT/GNU Scheme}.
-
-@node Portable C Installation, , Windows Installation, Installation
-@section Portable C Installation
-
-This section describes how to generate binaries from the portable C
-distribution. These binaries should run with little or no trouble on most
-modern architectures and operating systems. It will probably require
-tweaking for systems that haven't been tested.
-
-When built this way, the system runs slower than when it is built
-using the native-code compiler. For this reason, you will usually want
-to use native-code binaries when running on a 32-bit Intel
-architecture machine. However, the portable-code binaries can address
-larger amounts of virtual memory than the native-code binaries, so it
-is reasonable (and supported) to use both kinds on the same machine.
-
-@enumerate
-@item
-Unpack the tar file,
-@file{mit-scheme-c-@var{VERSION}.tar.gz}, into the directory
-@file{mit-scheme-c-@var{VERSION}}. For example,
-
-@example
-tar xzf mit-scheme-c-@var{VERSION}.tar.gz
-@end example
-
-will create a new directory @file{mit-scheme-c-@var{VERSION}}.
-
-@item
-Move into the new directory:
+build directory:
@example
-cd mit-scheme-c-@var{VERSION}/src
+cd ../
+rm -rf mit-scheme-pucked-gtk-0.5
@end example
-@item
-Build the program:
-
-@example
-./etc/make-liarc.sh
-@end example
-
-This will take a long time; on fairly fast machines with lots of RAM
-it takes about an hour. On older machines it will take longer or fail
-altogether, at which point you should ask for help. Note that you can
-pass configure options to the script.
-
-@example
-./etc/make-liarc.sh --help
-./etc/make-liarc.sh --prefix=/usr
-@end example
-
-@item
-Install the program:
-
-@example
-make install
-@end example
-
-Depending on configuration options and file-system permissions, you
-may need super-user privileges to do the installation step.
-@end enumerate
-
@node Running Scheme, Using Scheme, Installation, Top
@chapter Running Scheme
-This chapter describes how to run MIT/GNU Scheme. It also
-describes how you can customize the behavior of MIT/GNU Scheme
+This chapter describes how to run MIT/GNU Scheme Pucked. It also
+describes how you can customize the behavior of Scheme
using command-line options and environment variables.
@menu
* Command-Line Options::
* Custom Command-line Options::
* Environment Variables::
-* Starting Scheme from Microsoft Windows::
* Leaving Scheme::
@end menu
@node Basics of Starting Scheme, Customizing Scheme, Running Scheme, Running Scheme
@section Basics of Starting Scheme
-Under unix, MIT/GNU Scheme is invoked by typing
-
+MIT/GNU Scheme Pucked is invoked by typing
@example
-mit-scheme
+mit-scheme-pucked
@end example
-
@noindent
-at your operating system's command interpreter. Under Windows,
-MIT/GNU Scheme is invoked by double-clicking on a shortcut. In
-either case, Scheme will load itself and print something like this:
+in the shell. Scheme will load itself and print something like this:
-@example
-Copyright (C) 2015 Massachusetts Institute of Technology
+@smallexample
+MIT/GNU Scheme Pucked running under GNU/Linux
+Type `^C' (control-C) followed by `H' to obtain information about interrupts.
+
+Copyright (C) 2017 Matthew Birkholz
+Copyright (C) 2017 Massachusetts Institute of Technology
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-Image saved on Wednesday November 25, 2015 at 3:49:35 PM
- Release 9.2.1 || Microcode 15.3 || Runtime 15.7 || SF 4.41 || LIAR/i386 4.118
- Edwin 3.116
-@end example
+Image saved on Sunday March 12, 2017 at 10:15:09 AM
+ Release 9.2.7 || Microcode 15.3 || Runtime 15.7 || SF 4.41
+ LIAR/x86-64 4.118
+@end smallexample
@noindent
This information, which can be printed again by evaluating
-
@findex identify-world
@example
(identify-world)
@end example
-
@cindex release number
@cindex microcode, version
@cindex runtime system, version
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) or @file{.bat} file (Windows) that will
+can write a shell script that will
invoke Scheme with the appropriate @option{--heap} and other parameters.
@item
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 @env{HOME} environment variable. Under unix, the file is called
-@file{.scheme.init}; on the PC it is called @file{scheme.ini}.
+file is called @file{.scheme.init} and is
+stored in your home directory, which is normally specified by
+the @env{HOME} environment variable.
-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
+In addition, when Edwin starts up, it loads a separate init file called
+@file{.edwin} from your home directory into the Edwin environment
(@pxref{Starting Edwin}).
You can use both of these files to define new procedures or commands, or
@item
@dfn{Icons}.
@cindex icons
-Under Windows, and with some window managers under X11, it is possible
+With some window managers under X11, it is possible
to create icons that invoke Scheme with different parameters.
@end itemize
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 @file{/}), then no search occurs---@var{filename}
+that name. If @var{filename} is an absolute pathname (it
+starts with @file{/}), 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
@env{MITSCHEME_BAND}, or if that isn't defined, @file{all.com}; in
@item --stack @var{blocks}
@opindex --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 stack used by C
programs.
@item --option-summary
option is automatically supplied by GNU Emacs, and should not be given
under other circumstances.
-@item --interactive
-@opindex --interactive
-If this option isn't specified, and Scheme's standard @acronym{I/O} is
-not a terminal, Scheme will detach itself from its controlling
-terminal, which prevents it from getting signals sent to the process
-group of that terminal. If this option is specified, Scheme will not
-detach itself from the controlling terminal.
-
-This detaching behavior is useful for running Scheme as a background
-job. For example, using Bourne shell, 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
-mit-scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 &
-@end example
-
-This option is ignored under non-unix operating systems.
-
@item --nocore
@opindex --nocore
Specifies that Scheme should not generate a core dump under any
abnormally, you will be prompted to decide whether a core dump should be
generated.
-This option is ignored under non-unix operating systems.
-
@item --library @var{path}
@opindex --library
@nvindex MITSCHEME_LIBRARY_PATH
list of directories that is searched to find various library files, such
as bands. If this option is not given, the value of the environment
variable @env{MITSCHEME_LIBRARY_PATH} is used; if that isn't defined,
-the default is used.
-
-On unix, the elements of the list are separated by colons, and the
-default value is @file{/usr/local/lib/mit-scheme-@var{ARCH}}. On PCs,
-the elements of the list are separated by semicolons, and the default
-value is @file{c:\local\mit-scheme}.
+the default is used. The elements of the list are separated by colons.
+The default value is @file{/usr/local/lib/mit-scheme-pucked-@var{ARCH}}.
@item --fasl @var{filename}
@opindex --fasl
@item --suspend-file
@opindex --suspend-file
-Under some circumstances Scheme can write out a file called
-@file{scheme_suspend} in the user's home directory.@footnote{Under unix,
-this file is written when Scheme is terminated by the @samp{SIGUSR1},
-@samp{SIGHUP}, or @samp{SIGPWR} signals. Under other operating systems,
-this file is never written.} This file is a world image containing the
+Scheme can write out a file called
+@file{scheme_suspend} in the user's home directory
+when Scheme is terminated by the @samp{SIGUSR1},
+@samp{SIGHUP}, or @samp{SIGPWR} signals.
+This file is a world image containing the
complete state of the Scheme process; restoring this file continues the
computation that Scheme was performing at the time the file was written.
delayed actions.
@end deffn
-@node Environment Variables, Starting Scheme from Microsoft Windows, Custom Command-line Options, Running Scheme
+@node Environment Variables, Leaving Scheme, Custom Command-line Options, Running Scheme
@section Environment Variables
Scheme refers to many environment variables. This section lists these
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; others can be defined or
overwritten within Scheme by using the @code{set-environment-variable!}
procedure, e.g.@:
* Microcode Environment Variables::
* Runtime Environment Variables::
* Edwin Environment Variables::
-* Windows Environment Variables::
@end menu
@node Microcode Environment Variables, Runtime Environment Variables, Environment Variables, Environment Variables
@subsection Environment Variables for the Microcode
These environment variables are referred to by the microcode (the
-executable C program called @command{mit-scheme} under unix, and
-@command{mit-scheme.exe} on the PC).
+executable C program called @command{mit-scheme-pucked}).
@table @env
@item MITSCHEME_BAND
@nvindex MITSCHEME_LIBRARY_PATH
A list of directories. These directories are searched,
left to right, to find bands and various other files.
-On unix systems the list is colon-separated, with the default
-@file{/usr/local/lib/mit-scheme-@var{ARCH}}.
-On PC systems the list is semicolon-separated with the default
-@file{c:\local\mit-scheme}.
+The list is colon-separated, with the default
+@file{/usr/local/lib/mit-scheme-pucked-@var{ARCH}}.
@item MITSCHEME_CONSTANT
@nvindex MITSCHEME_CONSTANT
@table @env
@item HOME
-@itemx HOMEDRIVE
-@itemx HOMEPATH
@nvindex HOME
-@nvindex HOMEDRIVE
-@nvindex HOMEPATH
-Directory in which to look for init files. E.g.@: @file{c:\users\joe}
-or @file{/home/joe}. Under Windows, the environment variables
-@env{HOMEDRIVE} and @env{HOMEPATH}, set by the operating system, are
-used instead. Under unix, @env{HOME} is set by the login shell.
+Directory in which to look for init files, e.g.@: @file{/home/joe}.
+@env{HOME} is set by the login shell.
@item TMPDIR
@itemx TEMP
@nvindex 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}, @file{/tmp}; under
-Windows, @file{\temp}, @file{\tmp}, and @file{\} (all on the system
-drive).
+@file{/var/tmp}, @file{/usr/tmp}, @file{/tmp}.
@item MITSCHEME_INF_DIRECTORY
@nvindex MITSCHEME_INF_DIRECTORY
the library path.
@end table
-@node Edwin Environment Variables, Windows Environment Variables, Runtime Environment Variables, Environment Variables
+@node Edwin Environment Variables, , Runtime Environment Variables, Environment Variables
@subsection Environment Variables for Edwin
These environment variables are referred to by Edwin.
@nvindex 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
-variable. The default is @file{/bin/sh} on unix systems and
-@file{cmd.exe} on Windows systems.
+variable. The default is @file{/bin/sh}.
@item PATH
@nvindex PATH
-Used to initialize the @code{exec-path} editor variable, which is
+The initial value of the @code{exec-path} editor variable, which is
subsequently used for finding programs to be run as subprocesses.
@item DISPLAY
@nvindex DISPLAY
-Used when Edwin runs under unix and uses X11. Specifies the display
-on which Edwin will create windows.
+The X11 display on which Edwin will create windows.
@item TERM
@nvindex TERM
-Used when Edwin runs under unix on a terminal. Terminal type.
+The terminal type used by Edwin when it runs on a terminal.
@item LINES
@nvindex LINES
-Used when Edwin runs under unix on a terminal. Number of text lines
-on the screen, for systems that don't support @samp{TIOCGWINSZ}.
+The number of text lines used by Edwin when it runs on a terminal,
+for systems that don't support @samp{TIOCGWINSZ}.
@item COLUMNS
@nvindex COLUMNS
-Used when Edwin runs under unix on a terminal. Number of text columns
-on the screen, for systems that don't support @samp{TIOCGWINSZ}.
+The number of text columns used by Edwin when it runs on a terminal,
+for systems that don't support @samp{TIOCGWINSZ}.
@end table
-@node Windows Environment Variables, , Edwin Environment Variables, Environment Variables
-@subsection Environment Variables for Microsoft Windows
-
-These environment variables are specific to the Microsoft Windows
-implementation.
-
-@table @env
-@item MITSCHEME_FONT
-@nvindex MITSCHEME_FONT
-@cindex fonts
-A string specifying a font name and characteristics, for example
-@samp{Courier New 16 bold}. Allowed characteristics are @var{integer},
-specifying the font size in points, and the following style modifiers:
-@samp{bold}, @samp{italic}, @samp{regular}, @samp{underline} and
-@samp{strikeout}. You should specify only fixed-width fonts as
-variable-width fonts are not drawn correctly.
-
-Once in Edwin, the font can be changed with the @code{set-font} and
-@code{set-default-font} commands.
-
-@item MITSCHEME_GEOMETRY
-@nvindex MITSCHEME_GEOMETRY
-@cindex window position
-Four integers separated by commas or spaces that specify the placement
-and size of the MIT/GNU Scheme window as a
-@var{left},@var{top},@var{width},@var{height} quadruple. The units are
-screen pixels, and @samp{-1} means allow the system to choose this
-parameter. E.g.@: @samp{-1,-1,500,300} places a 500 by 300 pixel window
-at some system-determined position on the screen. The width and height
-include the window border and title. The default value is
-@samp{-1,-1,-1,-1}.
-
-@item MITSCHEME_FOREGROUND
-@nvindex MITSCHEME_FOREGROUND
-@cindex window color
-A value specifying the window text color. The color is specified as
-hex blue, green and red values (@emph{not} RGB): e.g.@:
-@code{0xff0000} for blue.
-
-@item MITSCHEME_BACKGROUND
-@nvindex MITSCHEME_BACKGROUND
-A value specifying the window background color. See
-@env{MITSCHEME_FOREGROUND}.
-
-@item HOMEDRIVE
-@itemx HOMEPATH
-@nvindex HOMEDRIVE
-@nvindex HOMEPATH
-These variables are used together to indicate the user's home
-directory. This is the preferred way to specify the home directory.
-
-@item USERNAME
-@itemx USER
-@nvindex USERNAME
-@nvindex USER
-Specifies the login name of the user running Scheme. This is used for
-several different purposes. @env{USERNAME} is preferred; @env{USER}
-is used if @env{USERNAME} is not defined. If neither of these
-variables is defined, an error is signalled when the username is
-required.
-
-@item USERDIR
-@nvindex USERDIR
-Specifies a directory that contains the home directories of users.
-One of the places in which Scheme looks for the user's home directory,
-by searching for a subdirectory with the user's login name.
-@end table
-
-@node Starting Scheme from Microsoft Windows, Leaving Scheme, Environment Variables, Running Scheme
-@section Starting Scheme from Microsoft Windows
-
-The Microsoft Windows version of MIT/GNU Scheme runs as a
-graphics-based application. Scheme is normally started using shortcuts;
-the installer automatically generates several different predefined
-shortcuts for your convenience.
-
-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, 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
-Use an absolute pathname to @command{mit-scheme.exe} in the shortcut
-@var{Command line}.
-
-@item
-If you specify the @option{--library} command-line option then you do
-not have to worry about the @env{MITSCHEME_LIBRARY_PATH} environment
-variable.
-
-@item
-Set the shortcut's @var{Working Directory} to something sensible. On
-Windows you can use @samp{%HOMEDRIVE%%HOMEPATH%} to make Scheme start
-up in the user's home directory.
-
-@item
-There are several icons available in the Scheme executable---choose
-one that best represents the options given on the command line.
-
-@item
-If you want the shortcut to start up Edwin automatically, put
-@option{--edit} at the end of the command line.
-@end itemize
-
-@node Leaving Scheme, , Starting Scheme from Microsoft Windows, Running Scheme
+@node Leaving Scheme, , Environment Variables, Running Scheme
@section Leaving Scheme
There are several ways that you can leave Scheme: there are two Scheme
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
-Scheme). To suspend Scheme, evaluate
+restart where you left off. To suspend Scheme, evaluate
@findex quit
@example
respectively.
@item
-@emph{Graphical-interface buttons that you can activate.} Under
-Windows, closing the console window (Scheme's main window) causes
-Scheme to be terminated. Under any operating system, closing an Edwin
+@emph{Graphical-interface buttons that you can activate.} Closing
+an Edwin
window causes that window to go away, and if it is the only Edwin
window, it terminates Scheme as well.
@end itemize
@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-g}, @kbd{C-b}, @kbd{C-x} and @kbd{C-u}. The
+Scheme has several interrupt keys: @kbd{C-g} and @kbd{C-c}. The
@kbd{C-g} key stops any Scheme evaluation that is running and returns
you to the top level @acronym{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 unix,
-type @kbd{C-c ?} for more possibilities. Note that in any given
-implementation, only a subset of the following keys is available.
+Here are the definitions of the more common interrupt keys;
+type @kbd{C-c ?} for more possibilities.
@table @kbd
@item C-c C-c
will be read-only, a certain size, etc. many of the remaining checks
can prove unnecessary. To make these decisions for yourself, you can
turn off the compiler's implicit checks. The following procedure
-definition ensures minimum flonum consing (i.e. none, @pxref{Flonum
+definition ensures minimum flonum consing (i.e.@: none, @pxref{Flonum
arithmetic}) and maximum speed. It's safe use is entirely up to you.
@example
say version 22 or later, use the @file{xscheme} file that comes with
it. Otherwise use the one that is in the Scheme distribution.
-This interface works under unix only, because it requires unix signals
-for its operation. Porting it to Windows would require reimplementing
-the interface to eliminate the use of signals. We have no plans to do
-this.
-
@findex run-scheme
@opindex --emacs
To invoke Scheme from Emacs, load the @file{xscheme} library, then use
Like evaluating @samp{(continue)}. (@code{xscheme-send-proceed})
@end table
-@node Edwin, Release Notes, GNU Emacs Interface, Top
+@node Edwin, GNU Free Documentation License, GNU Emacs Interface, Top
@chapter Edwin
This chapter describes how to start Edwin, the MIT/GNU Scheme text
To use Edwin, start Scheme with the following command-line options:
@example
-mit-scheme --edit
+mit-scheme-pucked --edit
@end example
@noindent
-Alternatively, you can load Edwin by giving the @option{--edwin}
-command-line option and then calling the procedure @code{edit}:
+Alternatively, you can load Edwin by calling the procedure @code{edit}:
@deffn procedure edit
@deffnx procedure edwin
-Enter the Edwin text editor. If entering for the first time, the editor
-is initialized (by calling @code{create-editor} with no arguments).
+Load and enter the Edwin text editor. If entering for the first time,
+the editor is loaded and initialized (by calling @code{create-editor}
+with no arguments).
Otherwise, the previously-initialized editor is reentered.
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.
+@file{~/.edwin}) 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.
@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 Gtk and X11 are
+that window as Edwin's main window. If Gtk and X11 are
not available or if the @env{DISPLAY} environment variable is
undefined, Edwin will run on Scheme's console.
@item (gtk)
-Unix only. Creates an X window containing Gtk widgets, mostly Scheme
+Creates an X window containing Gtk widgets, mostly Scheme
canvases. This requires the @env{DISPLAY} environment variable to
have been set to the appropriate value before Scheme was started, and
the @code{gtk-screen} option to have been loaded.
@item (x)
-Unix only. Creates an X window and uses it as Edwin's main window.
+Creates an X window and uses it as Edwin's main window.
This requires the @env{DISPLAY} environment variable to have been set
to the appropriate value before Scheme was started.
@item (x @var{geometry})
-Unix only. Like @samp{(x)} except that @var{geometry} specifies the
+Like @samp{(x)} except that @var{geometry} specifies the
window's geometry in the usual way. @var{Geometry} must be a character
string whose contents is an X geometry specification.
@item (console)
-Unix only. Causes Edwin to run on Scheme's console, or in unix
-terminology, the standard input and output. If the console is not a
+Causes Edwin to run on Scheme's console, i.e.@:
+the standard input and output. If the console is not a
terminal device, or is not powerful enough to run Edwin, an error will
be signalled at initialization time.
-
-@item (win32)
-Windows only. Creates a window and uses it as Edwin's main window.
@end table
@end defvr
The buffers are saved in an auto-save file in case the original is more
valuable than the unsaved version. You can use the editor command
@kbd{M-x recover-file} to recover the auto-saved version. The name
-used to specify an auto-save file is operating-system dependent: under
-unix, and on PC file systems with long file names, @file{foo.scm} will
-be saved as @file{#foo.scm#}; on PC file systems with short file names,
-it will be saved as @file{foo.sav}.
+used to specify an auto-save file for @file{foo.scm} is
+@file{#foo.scm#}.
The following Scheme procedures are useful for recovering from bugs in
Edwin's implementation. All of them are designed for use when Edwin is
state that prevents Edwin from running.
@end deffn
-@node Release Notes, GNU Free Documentation License, Edwin, Top
-@appendix Release Notes
-
-The release notes are online at
-@uref{http://www.gnu.org/software/mit-scheme/release.html}.
-
-@node GNU Free Documentation License, Environment-variable Index, Release Notes, Top
+@node GNU Free Documentation License, Environment-variable Index, Edwin, Top
@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
projects / mit-scheme.git / commitdiff