.\" squeak.1 -- manual page for Unix Squeak			-*- nroff -*-
.\" 
.\"   Copyright (C) 1996-2004 by Ian Piumarta and other authors/contributors
.\"                              listed elsewhere in this file.
.\"   All rights reserved.
.\"   
.\"   This file is part of Unix Squeak.
.\" 
.\"   Permission is hereby granted, free of charge, to any person obtaining a copy
.\"   of this software and associated documentation files (the "Software"), to deal
.\"   in the Software without restriction, including without limitation the rights
.\"   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
.\"   copies of the Software, and to permit persons to whom the Software is
.\"   furnished to do so, subject to the following conditions:
.\"
.\"   The above copyright notice and this permission notice shall be included in
.\"   all copies or substantial portions of the Software.
.\"
.\"   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\"   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\"   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
.\"   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\"   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
.\"   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
.\"   SOFTWARE.
.\" 
.\" Last edited: 2009-08-12 11:14:29 by piumarta on emilia-2.local
.\" 
.if @@\*(lq@ \{\
.	ds lq "
.	if t .ds lq ``
.	if !@@\(lq@ .ds lq "\(lq
.\}
.if @@\*(rq@ \{\
.	ds rq "
.	if t .ds rq ''
.	if !@@\(rq@ .ds rq "\(rq
.\}
.de Id
.ds Rv \\$3
.ds Dt \\$4
..
.de Sp
.if n .sp
.if t .sp 0.4
..
.TH SQUEAK 1 "\*(Dt" "Squeak Smalltalk System" "Squeak Smalltalk System"
.SH NAME
squeak, inisqueak \- Unix Squeak virtual machine and installer
.SH SYNOPSIS
.B inisqueak
.br
.B squeak
.RI "[ " option ".\|.\|. ] [ " image " ] [ " script " [ " argument ".\|.\|. ] ]"
.SH DESCRIPTION
.B squeak
is the virtual machine for the Squeak Smalltalk system.  It requires three files
to operate correctly: an
.B image
file containing a `snapshot' of a live Squeak session, a
.B changes
file containing the source code for modified methods in the image, and
a copy of (or a link to) a shared system
.B sources
file containing the source code for methods that have not been modified
since the last major version increment.
.PP
The image and changes files contain the state of a user's Squeak
session, which is persistent between consecutive sessions.  Private
copies of these files are therefore normally required.  The
.B inisqueak
script checks that the local Squeak installation appears sane, and then
copies the required files to the current
working directory.
If
.B inisqueak
encounters no problems, it will finish by running
.B squeak
to start a Squeak session using the newly copied image and changes files.
.PP
.B inisqueak
should be run
.I once\c
\&, when using Squeak for the first time, to create a new 'personal'
Squeak session.  Afterwards,
.B squeak
should be run each time that session is to be resumed.
.PP
.SH INVOCATION
.B inisqueak
has no options or arguments.
Simply 'cd' to the directory that is to contain the working
copies of the image and changes files, then run it.
.PP
.B squeak
accepts various
.I options
(described below), and then an optional
.I image
name (which must not begin with a minus sign '\-').  If an
.I image
name is given on the command line then
.B squeak
tries to run that image.  Otherwise
.B squeak
checks the environment variable
.B SQUEAK_IMAGE
and, if it is set, uses its value as the name of the image to run.
Otherwise 
.B squeak
looks for an image called 'squeak.image' in the current directory.
If the image file does not exist then
.B squeak
prints a message indicating which image file it failed to find and then
exits.
If the extension '.image' is missing in the
.I image
argument or in the value of the
.B SQUEAK_IMAGE
variable, it will be appended automatically.
.PP
The
.I image
argument can be followed by a
.I script
name.  This is the name of a 'document' that should contain
Smalltalk code to be executed on startup.  The document can be either
the name of a file or a URL starting with 'http:'.
Any
.I argument\c
s that appear after the
.I script
name are ignored, but are made available to the
.I script
from within Squeak via the method
.B getSystemAttribute:\c
\&.  (See the section
.B SCRIPTS
below.)
.PP
If
.I image
is given as '--' then
.B squeak
immediately stops argument processing (and behaves as if
.I image
was not specified).  This is useful to specify a
.I script
(possibly with script arguments) without specifying an explicit
.I image\c
\&.
.SH OPTIONS
Command line options fall into two categories: 'common' options
that are recognised by the base VM and 'specific' options that are
tied to a particular display or sound driver.  Common options will
always be recognised by
.B squeak\c
, whereas a given specific option will be recognised only after
.B squeak
has loaded the driver to which it relates.  Refer to the '-vm'
option below for more details.
.PP
The common options recognised by
.B squeak
are as follows:
.TP
.BI "\-encoding " "enc"
specifies the internal character encoding to be used by Squeak.  This
affects the translation that the VM performs when importing text (from
the keyboard or via 'paste' from an external selection) or exporting
text (pasting text from Squeak to another application, or when
generating filenames containing special characters).  In other words,
it affects the correspondence between what Squeak displays on the
screen and what it sends to (or receives from) external applications.
The correct value depends on the way Squeak's internal fonts are
encoded.  Current images are delivered with traditional Macintosh
\&'New York' fonts that use
.B Mac Roman
encoding, and so this is the default internal encoding.  If other
fonts (from X11 or elsewhere) are imported into the image and used as
system fonts then the this default translation will give incorrect
results for diacritical marks and special characters.  In such cases
the
.B \-encoding
option can be used to change the internal encoding, for example
.sp
.nf
\ \ \ \ \-encoding ISO-8859-15
.fi
.sp
(aka
.B Latin9\c
) which would be appropriate for many of the fonts designed for
European languages.
.TP
.B \-help
prints a short summary of the command-line syntax, options and
available drivers, then exits.
.TP
.BI "-memory " "size"[mk]
requests that a fixed heap of
.I size
bytes be allocated for the Squeak image.  If the suffix `\c
.B k\c
\&' is given then the argument is expressed in kilobytes.  If
the suffux `\c
.B m\c
\&' is given then the argument is expressed in megabytes.  This option
SHOULD NOT be used, unless there is a good reason to do so, since it
places an arbitrary limit on Squeak's object memory size.
.TP
.BI "-mmap " "size"[mk]
requests that a variable heap of at most
.I size
bytes be allocated.  (The suffixes are as described for the
\&'\-memory' option.)
.B squeak
will initially allocate a heap that is large enough to hold the image,
with a small amount of headroom.  If at any time Squeak requires more
memory for its image then additional space will be allocated
dynamically.  Likewise, when memory is no longer needed it will
deallocated and returned to the system.  The
.I size
argument places an upper limit on how big the heap can grow in this
fashion.  
.B squeak
uses a dynamic heap by default with the maximum size set to 75% of the
available virtual memory or 1 gigabyte, whichever is smaller.
.TP
.B \-noevents
disables the new (image 2.8 and later) event-driven input mechanism.
This option is only useful for testing backwards compatibility with
older images and should not be used.
.TP
.B \-notimer
disables the use of the interval timer for keeping track of low-resolution
time.  (If you are having problems with file, sound or socket i/o reporting
`interrupted system call' then setting this flag might help.)
.TP
.BI "\-pathenc " "enc"
specifies the external character encoding to be used by Squeak when accessing the filesystem
(file and directory pathnames).  The correct value depends on the local platform's characteristics.
If no encoding conversion should be performed then this should be set to the same encoding
as Squeak uses internally (see the
.I \-encoding
option).  Otherwise
.B ISO-8859-15
(aka
.B Latin9\c
) might make sense on a filesystem supporting 8\-bit characters, and
.B UTF-8
for filesystems that use Unicode-based pathnames.  The default is
.B UTF-8
which is correct for Mac OS X and very recent GNU/Linux distributions,
and which (in an ideal world) will eventually be adopted by all Unix
variants.
.TP
.BI "-plugins " "path"
specifies an alternative location for external plugins (collections of
named primitives) and drivers (for display and sound).  The
.I path
argument contains a pattern in which any occurrences of `\c
.B %n\c
\&' will be replaced by the name of the plugin or driver being loaded.
The
.I path
can name either a directory or the plugin itself and can be absolute or
relative (to the directory in which
.B squeak
was run).  If a plugin or driver cannot be found in the location
specified by
.I path
then the search continues in the default locations.
.TP
.BI "\-textenc " "enc"
specifies the external character encoding to be used by Squeak when
exchanging clipboard text with other applications.  The default is
.B UTF-8
on Mac OS X and
.B ISO-8859-15
(aka
.B Latin9\c
) on other Unix systems.  Note that X11 applications requesting the
selection converted to
.B UTF8_STRING
data will (correctly) receive the clipboard text encoded as
.B UTF-8\c
, regardless of this setting.
.sp
Squeak recognises a subset of the encoding names defined by the IANA.
(If you prefer to use the international currency symbol rather than
the Euro symbol in external text then you might want to set this to
.B ISO-8859-1\c
, aka
.B Latin1\c
\&.)
.TP
.B \-version
prints three or more lines of version information, as follows:
.RS
.TP
\ \ \ \(bu
the architecture configured for the virtual machine at compile time,
the compilation `sequence number', the time and date of compilation,
and the name (and version, if known) of the compiler that was used to
compile
.B squeak\c
;
.TP
\ \ \ \(bu
the complete
.BR uname (1)
information for the host on which the virtual machine was compiled;
.TP
\ \ \ \(bu
the default installed location for plugins and drivers;
.PP
After printing the above, the virtual machine exits.
.RE
.TP
.BI "\-vm " "driver"
asks
.B squeak
to load a sound/display driver.  For each supported device there is a
corresponding driver that
.B squeak
loads during initialisation.  Unless told otherwise,
.B squeak
will figure out sensible default drivers to load.  This choice can be
overridden using this option.  The
.I driver
argument is a list of one or more 'assignments' of the form
.sp
\ \ \ \ 
.I class\c
=\c
.I device
.sp
separated by spaces or commas.  The supported combinations are currently:
.RS
.TP
.B \ \ \ display=X11
to display the Squeak window on a local or remote X Window System
server.
.TP
.B \ \ \ display=Quartz
to display on the local Mac OS X desktop.
.TP
.B \ \ \ display=none
to disable the display (and keyboard/mouse) entirely.  (This driver is
useful primarily for running 'server' applications in Squeak.)
.TP
.B \ \ \ sound=OSS
provides sound input and output via the Open Sound System.  (If you
have a device called '/dev/dsp' then this is likely the one you
want.)
.TP
.B \ \ \ sound=MacOSX
provides sound input/output via Core Audio on Mac OS X.
.TP
.B \ \ \ sound=NAS
provides sound i/o via the Network Audio System.
.TP
.B \ \ \ sound=Sun
provides sound on Sun Microsystems hardware.
.TP
.B \ \ \ sound=none
disables sound entirely.
.B squeak
will not attempt to play or record sounds when this driver is loaded.
.RE
.PP
.RS
Note that only those drivers relevant to the local platform will be
available.  Attempting to load an unsupported driver will cause
.B squeak
to exit with an error message.  A list of available drivers is printed
by the '-help' option.  If a particular driver cannot load system
libraries on which it depends then it will neither be listed nor
be available to load at runtime.
.RE
.PP
.RS
Note also that on Mac OS X both the X11 and Quartz display drivers are
supported, although the former will refuse to load if the X11 client
libraries are not installed on the local machine.  The Quartz driver
will happily load (and Squeak will run as a fully-fledged application)
even when
.B squeak
is invoked from the command line.  Exercise caution when logged into
Mac OS X from another machine: forgetting to set DISPLAY before trying
to run
.B squeak
on the remote display could cause embarrassement.
.RE
.PP
Options specific to the X11 display driver are as follows:
.TP
.BI "\-browserWindow " "id"
specifies the
.I id
of the window that
.B squeak
should use for its display.  This option is intended for use when Squeak is
running as a web browser plugin.
.TP
.BI "\-display " "server"
specifies that Squeak should connect to the given display
.I server 
instead of looking in the environment variable
.B
DISPLAY
(the default behaviour) to find the name of the server to use.
.TP
.BI "\-cmdmod " "N"
tells the VM to map modifier key
.I N
on the keyboard to the modifier code that the image expects for the Command key.
.TP
.BI "\-optmod " "N"
tells the VM to map modifier key
.I N
on the keyboard to the modifier code that the image expects for the Option key.
.TP
.B \-compositioninput
enables support for an overlay window in which individual characters
(e.g., Japanese hiragana) are composed before being interpreted as a
single character (e.g., Japanese kanji) by the image.
.TP
.BI "\-xicfont " "font"
tells the VM to use the named
.I font
within the composition overlay window.
.TP
.B \-fullscreen
causes the Squeak window to occupy as much of the screen area as possible.
Implies '\c
.B \-notitle\c
\&'.
.TP
.B \-headless
disables the graphical display and mouse/keyboard input.  This mode of
operation is useful primarily for servers.
.TP
.B \-iconic
asks the window manager to iconify the Squeak window at startup.
.TP
.B \-lazy
causes Squeak to `snooze' whenever the main winodw is unmapped.  This can
be used if Squeak appears to be using consuming CPU time while idling (which should
not normally be the case).  Note that if this option is in effect, when the
Squeak window is unmapped
.B squeak
will not respond to any external stimuli (other than to provide the X
selection to requestors, when Squeak is the owner).
.TP
.B \-mapdelbs
maps the Delete key onto Backspace.  Backspace deletes the character to the left
of the cursor and Delete normally deletes the character
to the right of the cursor.  With this option, Deletes will behave like
Backspace.  The behaviour of Backspace is not changed.
.TP
.B \-noxdnd
disables support for the X drag-and-drop protocol.
.TP
.B \-nointl
disables the handling of dead keys on international keyboards.
Without this option, dead key handling is enabled if either
.B LC_ALL
or
.B LC_CTYPE
is set in the environment.
.TP
.B \-notitle
disables the title bar on the Squeak window (if the window manager supports it).
This option is implied by '\c
.B \-fullscreen\c
\&'.
.TP
.B \-swapbtn
swaps the yellow and blue buttons.   (Traditionally, the red button is on
the left, yellow in the middle and blue on the right.  The colourful names
come from the Xerox Alto on which Smalltalk was first implemented.)
Squeak normally maps X buttons 1, 2 and 3 to the
.B red\c
, 
.B yellow
and 
.B blue
buttons, in that order.  With this option, it maps X buttons
1, 2 and 3 to the
.B red\c
, 
.B blue
and
.B yellow
buttons.)
.TP
.B \-xasync
causes Squeak to use asynchronous display updates.  The virtual machine normally
flushes and synchronises the display connection at regular intervals.  Using this
option disables synchronisation, which will be performed only when the image
explicitly requests it.
.TP
.B \-xshm
enables the use of the X Shared Memory extension on servers that support it.
This can dramatically improve display performance, but works only when
Squeak is running on the server.
.PP
Options specific to the FBDev display driver are as follows:
.TP
.BI "\-fbdev " "device"
Use the given framebuffer
.I device
instead of the default '/dev/fb0'.
.TP
.BI "\-kbmap " "mapfile"
Load the keyboard map from the given
.I mapfile
instead of reading it from the running kernel.
Note that
.B squeak
cannot (currently) read compressed or 'shorthand'
map files (as found in /usr/share/keymaps or /lib/kbd/keymaps).
To generate a keymap file usable by
.B squeak\c
\&, execute the following program from the console:
.sp
\ \ \ \ dumpkeys -f -n --keys-only > key.map
.sp
If
.B squeak
encounters a problem while trying to load
.I mapfile\c
\&, it will print an error message and exit.
See
.BR keymaps (5)
for more information about the keymap file format.  The programs
.BR dumpkeys (1)\c
,
.BR loadkeys (1)\c
, and
.BR showkey (1)
can be used to modify the keyboard map before creating a keymap file
for
.B squeak\c
\&.
.TP
.BI "\-msdev " "device"
Use the given mouse
.I device
instead of the default.  The default is to try
\&'/dev/psaux', '/dev/input/mice' and '/dev/adbmouse',
in that order, and to use the first one that has a physical device attached.
.TP
.BI "\-msproto " "protocol"
Use the given mouse
.I protocol
instead of the default.  The supported protocols are 'ps2' and 'adb'.
The default is 'ps2' for mice attached to '/dev/psaux' or '/dev/input/mice',
and 'adb' for mice attached to '/dev/adbmouse'.
.TP
.B \-vtlock
Disallows VT switching, regardless of whether the request comes from
the keyboard or from another program such as
.BR chvt (1)\c
\&.
.TP
.B \-vtswitch
Enables keyboard VT switching.  Note that this option is effectively
disabled if the '\c
.B \-vtlock\c
\&' option is also enabled.
.PP
Options specific to the OSS and MacOSX sound drivers are as follows:
.TP
.B \-nomixer
disables the primitives that change mixer (sound) settings.  If you
prefer that Squeak leave these alone (they are, after all, really the
reponsibility of whichever mixer program or sound control panel you
use) then this option is for you.
.PP
Options specific to the ALSA sound driver are as follows:
.TP
.BI "\-capture " "device"
Uses the named input
.I device
for sound capture.
.TP
.BI "\-playback " "device"
Uses the named output
.I device
for sound playback.
.PP
Several common options are deprecated and are provided only for
backward compatibility.  These options should not be used and will be
removed in a future release:
.TP
.BI "\-display " "dpy"
is equivalent to '\-vm display=X11 \-display
.I dpy\c
\&'.
.TP
.B \-headless
is equivalent to '\-vm display=X11 \-headless'.
.TP
.B \-nodisplay
is equivalent to '\-vm display=none'.
.TP
.B \-nosound
is equivalent to '\-vm sound=none'.
.TP
.B \-quartz
is equivalent to '-vm display=Quartz'.
.SH ENVIRONMENT
Many of the options that can be set on the command line can
also be set from environment variables.
.TP
.B SQUEAK_ASYNC
if set in the environment then equivalent to the '\c
.B \-xasync\c
\&' flag.  (The value is ignored.)
.TP
.B SQUEAK_CAPTURE
see '\c
.B \-capture\c
\&'.
.TP
.B SQUEAK_COMPOSITIONINPUT
if set in the environment then equivalent to the '\c
.B \-compositioninput\c
\&' flag.  (The value is ignored.)
.TP
.B SQUEAK_ENCODING
the name of the internal character encoding used by Squeak.  Equivalent to giving the '\c
.B \-encoding\c
\&' command-line option if set.
.TP
.B SQUEAK_FBDEV
the name of the framebuffer device to use when running on the console.  See the '\c
.B \-fbdev\c
\&' option.
.TP
.B SQUEAK_FULLSCREEN
equivalent to '\c
.B \-fullscreen\c
\&' if set.
.TP
.B SQUEAK_ICONIC
equivalent to the '\c
.B \-iconic\c
\&' flag.
.TP
.B SQUEAK_IMAGE
the name of the image file to execute if no
.I image
argument is given on the command line.
.TP
.B SQUEAK_KBMAP
the name of the keymap file to use when running on the console.  See the '\c
.B \-kbmap\c
\&' option.
.TP
.B SQUEAK_LAZY
equivalent to the '\c
.B \-lazy\c
\&' flag.
.TP
.B SQUEAK_MAPDELBS
equivalent to the '\c
.B \-mapdelbs\c
\&' flag.
.TP
.B SQUEAK_MEMORY
the initial size of the heap, with optional 'k' or 'm' suffix.  Equivalent
to the '\c
.BI "-memory " size [km]\c
\&' flag.
.TP
.B SQUEAK_MSDEV
the name of the mouse device to use when running on the console.  See the '\c
.B \-msdev\c
\&' option.
.TP
.B SQUEAK_MSPROTO
the name of the mouse protocl to use when running on the console.  See the '\c
.B \-msproto\c
\&' option.
.TP
.B SQUEAK_VTLOCK
if set then equivalent to specifying the '\c
.B \-vtlock\c
\&' option on the command line.
.TP
.B SQUEAK_VTSWITCH
if set then equivalent to specifying the '\c
.B \-vtswitch\c
\&' option on the command line.
.TP
.B SQUEAK_NOEVENTS
if set, equivalent to '\c
.B \-noevents\c
\&'.
.TP
.B SQUEAK_NOINTL
equivalent to '\c
.B \-nointl\c
\&' if set.
.TP
.B SQUEAK_NOMIXER
equivalent to '\c
.B \-nomixer\c
\&' if set.
.TP
.B SQUEAK_NOTIMER
equivalent to '\c
.B \-notimer\c
\&' if set.
.TP
.B SQUEAK_NOTITLE
if set, equivalent to '\c
.B \-notitle\c
\&'.
.TP
.B SQUEAK_PATHENC
the name of the character encoding used to construct file and directory names.
Equivalent to giving the '\c
.B \-pathenc\c
\&' command-line option if set.
.TP
.B SQUEAK_PLAYBACK
see '\c
.B \-playback\c
\&'.
.TP
.B SQUEAK_PLUGINS
see '\c
.B \-plugins\c
\&'.
.TP
.B SQUEAK_SWAPBTN
equivalent to '\c
.B \-swapbtn\c
\&' if set.
.TP
.B SQUEAK_TEXTENC
the name of the character encoding used to copy/paste text from/to external applications.
Equivalent to giving the '\c
.B \-textenc\c
\&' command-line option if set.
.TP
.B SQUEAK_VM
contains the names of one or more drivers to be loaded during initialisation.
See the '\c
.B \-vm\c
\&' option for details.
.TP
.B SQUEAK_XICFONT
if set in the environment then it provides a default name for the composition overlay font; see the '\c
.B \-xicfont\c
\&' flag.
.TP
.B SQUEAK_XSHM
equivalent to '\c
.B \-xshm\c
\&'.
.PP
If an environment variable and a command-line option conflict over a
particular value then normally the value in the command line takes
precedence.  The exception to this rule is the '\-vm' option.
Environment variables are processed before command-line arguments and
\&'\-vm' cannnot be used to unload a driver that was loaded while
processing the contents of 'SQUEAK_VM'.
.PP
.B squeak
also checks the environment for
.B LC_ALL
and
.B LC_CTYPE\c
\&.  If either of these variables is set then support for
international keyboards (including dead keys for diacritical marks) is
enabled.  To prevent this support being enabled even when one or both
of these variables is set, use the '\-nointl' option (or set
.B SQUEAK_NOINTL
in the environment).  For example, to start
.B squeak
with support for dead keys on Spanish keyboards, with Latin-1 encoding
of external characters and the default MacRoman internal font
encoding, run
.B squeak
like this:
.sp
.RS
.nf
export LC_CTYPE=es_ES
export SQUEAK_TEXTENC=latin1
squeak
.fi
.RE
.SH SCRIPTS
Squeak can load and execute a 'script' file containing Smalltalk code at
startup.  The name of the file should be given as the
.I script
argument to
.B squeak\c
\&.
For example, assuming that the image 'foo.image'
contains an open Transcript window, then the following represents
the 'hello world' program for Squeak:
.sp
.RS
.nf
Transcript cr; show: 'Hello, world'.
.fi
.RE
.sp
If this script is in a file called 'hello.sq', then it could be run like this:
.sp
.RS
.nf
squeak foo.image hello.sq
.fi
.RE
.PP
It is also possible to make 'self interpreting' scripts by adding an 'interpreter
line' to the start of the script.  The 'hello.sq' file could be changed to
.sp
.RS
.nf
#![bindir]/squeak --
Transcript cr; show: 'Hello, world'.
.fi
.RE
.sp
and then made executable with
.sp
.RS
.nf
chmod +x hello.sq
.fi
.RE
.sp
and then invoked by running the script file directly:
.sp
.RS
.nf
SQUEAK_IMAGE="foo.image"
export SQUEAK_IMAGE
\&./hello.sq
.fi
.RE
.PP
If any
.I argument\c
s are present after the
.I script
name then they can be retrieved from within the script using the method
.sp
.RS
.nf
Smalltalk getSystemAttribute: \c
.I n
.fi
.RE
.sp
where
.I n
is the index of the argument, starting at 3 for the first argument.  (See the
method comment for
.sp
.RS
.nf
SystemDictionary>>getSystemAttribute:
.fi
.RE
.sp
in the image for an explanation of the meanings of the indices.)
.PP
As an example of this, here is the 'echo' program written as a Squeak script:
.sp
.RS
.nf
#![bindir]/squeak --
"Echo arguments to the Transcript."
| i a |
i := 2.
[(a := Smalltalk getSystemAttribute: (i := i + 1))
    notNil]
  whileTrue: [Transcript space; show: a].
.fi
.RE
.sp
When run as
.sp
.RS
.nf
\&./echo.sq one two three
.fi
.RE
.sp
this would print 'one two three' in the Transcript window.
.SH DIAGNOSTICS
.TP
.B inisqueak
prints several informational messages while doing its stuff.  If it encounters
a problem it prints an appropriate message before bailing out.  The messages
should be self-explanatory.
.TP
.B squeak
normally does not print anything at all.  If it prints something then there
is a problem.  The messages should be self-explanatory.
.\" .PP
.\" Sending
.\" .B squeak
.\" a SIGHUP or SIGQUIT signal will cause it dump the executing image into
.\" the working directy and then exit.  Both of these should be
.\" considered 'last resort' measures to save an image that contains
.\" valuable recent changes.  SIGHUP is synchronous (it works when the VM
.\" is in a known state) and the chances of obtaining a working image are
.\" fairly good, but it relies on the event polling loop being called.
.\" SIGQUIT is asynchronous, and the chances of recovering a working image
.\" after using it are fairly poor.  In either case, when restaring the
.\" "dumped" image, the first think that should be done is to execute
.\" .sp
.\" .RS
.\" .nf
.\" Smalltalk processStartUpList: true
.\" .fi
.\" .RE
.\" .sp
.\" in a workspace.  Recover what is needed from the image, then destroy
.\" the image (whose integrity should certainly not be trusted).
.SH FILES
.I [imgdir]/SqueakV[major].sources
.RS
Shared system sources file for the Squeak image.  There must be a
copy of (or link to) this file in the working directory when running
.B squeak\c
\&.
.RE
.sp
.I [imgdir]/Squeak*.image
.I [imgdir]/Squeak*.changes
.RS
Distributed image and changes files holding a `shapshot' of a
live Squeak session.  (The contents of these files change during a
session, and so private copies should always be made before running
.B squeak
for the first time.  See
.BR inisqueak (1)\c
).
.RE
.sp
.I ./SqueakV[major].sources
.RS
A link to the system sources file.
.RE
.sp
.IR ./ name .image
.br
.IR ./ name .changes
.RS
Private copies of image and changes files.
.RE
.sp
.I [plgdir]/*.so
.br
.I [plgdir]/*.la
.RS
Virtual machine 'plugins' (containing primitives that are loaded on
demand) and drivers (for different types of display and sound
hardware).
.RE
.sp
.I [bindir]/squeak
.br
.I [bindir]/inisqueak
.RS
The Squeak virtual machine and personal image installer script.
.RE
.sp
.I [mandir]/squeak.1
.RS
This manual page.
.RE
.sp
.I [docdir]/*
.RS
Miscellaneous documentation.
.RE
.SH NOTES
This manual page documents version [version] of Unix Squeak.  It may
not be appropriate for any other version.
.PP
The image and changes files containing a saved Squeak session are
intimately related.  They should always be used together, never be
separated, and under no circumstances should an image be run with a
changes file that has been used with a different image.  Failure to
adhere to the above could cause the source code for the methods in the
image to become garbled and impossible to retrieve.
.PP
The Unix Squeak virtual machine fully supports OpenGL in both the X11
and Quartz display drivers.  Open Croquet will run just fine with
either of these drivers (and many Mac OS X users will even have the
choice of which driver to use :).
.SH BUGS
If a 'binary' option is enabled by an environment variable, there is no
way to disable it on the command line.
.PP
Similarly, drivers specified in the
.I SQUEAK_VM
environment variable cannot be overridden by passing options on the
command line.
.PP
.B squeak
should never crash.  In the unlikely event that it does crash, or
prints any kind of message that
.I does not
appear to be caused by incorrect arguments or illegal operations from
within a Squeak program, please send a bug report to:
<ian.piumarta@squeakland.org>.  (Do not send bug reports to the
general-purpose 'squeak-dev' mailing list.  They will not be read.  If
you feel you must post a bug report to a mailing list, send it to the
Squeak 'vm-dev' mailing list in addition to the above email address.)
.SH AUTHOR
This manual page was written by Ian Piumarta.
.SH SEE ALSO
Dan Ingalls, Ted Kaehler, John Maloney, Scott Wallace and Alan Kay, \c
.I Back to the Future: The Story of Squeak, A Practical Smalltalk Written in Itself\c
\&.  Proc. OOPSLA'97.
.PP
The official Squeak home page:
.RS
.B http://squeak.org
.RE
.PP
The general-purpose 'squeak-dev' mailing list (not for VM-related bug reports):
.RS
.B http://lists.squeakfoundation.org/listinfo/squeak-dev
.RE
.PP
The Squeak 'vm-dev' mailing list (amongst others):
.RS
.B http://discuss.squeakfoundation.org/
.RE
.PP
The latest source and binary distributions of Unix Squeak:
.RS
.B http://squeakvm.org/unix
.RE
.\".PP
.\"The list of IANA-registered character encoding names, of which a proper subset is recognised by Squeak:
.\".RS
.\".B http://www.iana.org/assignments/character-sets
.\".RE