Welcome to the Smalltalk/X educational distribution !
-----------------------------------------------------

Please read LICENSE for what you may/may not do with this
package.

This release is not bug-free - some bugs are known, many 
are still to be found. Please have a look at 'doc/bug_list'
for what is already known.

You are welcome to send notes/bug-reports to:

        clam!st_bug @ ssw.de
or:
        office @ tomcat.de

(but please check if not already in the list, or if it 
 wasn't just a misunderstanding 
 - otherwise, I may probably not find time to do anything 
   else than reading mails in the future :-)


running Smalltalk/X
-------------------

    setenv DISPLAY ...

    cd smalltalk
    smalltalk

the directory-hierarchy found here is self contained, 
meaning that other directories, files or installation are not 
needed to run Smalltalk/X; just tar-it-in and execute smalltalk.


installing Smalltalk/X
----------------------

If more than one person is going to use Smalltalk/X, it is
useful to install the common files in some standard places,
and have the private files per-user.
For most file accesses within Smalltalk/X, it uses a searchpath,
allowing users to override things usually found in the common
place.
(the path looks like:
                     . 
                     $HOME/.smalltalk 
                     $SMALLTALK_LIBDIR
                     /usr/local/lib/smalltalk
                     /usr/lib/smalltalk

 in this order.
)

For example, a personal startup-script 'smalltalk.rc' can be
put into '$HOME/.smalltalk/smalltalk.rc'.
(see more in doc/manuals/configuration).


To install the system into some standard place 
(usually '/usr/local/bin' and '/usr/local/lib'), 
you should create the following directories:

        /usr/local/lib/smalltalk
        /usr/local/lib/smalltalk/source
        /usr/local/lib/smalltalk/resources
        /usr/local/lib/smalltalk/bitmaps
        /usr/local/lib/smalltalk/doc

and copy the files from corresponding subdirectories 
found here to those new directories.
Also, all files ending in '.rc' and '.stc' should be copied
to the new directory.

If you do not have access to '/usr/local/lib', you can also
put the stuff wherever you like AND set the shell-variable
'SMALLTALK_LIBDIR' to whatever the name of this directory is.

Thus, your global directory should look like:

        ./source
        ./source/*.st
        ./resources
        ./resources/*.rs
        ./bitmaps
        ./bitmaps/*.xbm
        ./fileIn/...
        ./doc/coding
        ./doc/misc
        ./doc/...
        ./smalltalk.rc
        ./smalltalk_r.rc
        ./display.rc
        ./d_*.rc
        ./host.rc
        ./h_*.rc
        ./abbrev.stc
        ./patches


Since compiled code does not include the source code itself, 
but instead a reference (filename & position) to it, 
an incorrect installation will lead to no sourcecode being shown
in the browser 
(the 'smalltalk.rc' script does a quick check and gives a warning).

Also, please do not manually edit the source files themselfes -
you will make the position-information in compiled code invalid, 
and also see funny source code (parts only) later.

This package does not include all sources - some stuff is only
avaliable in the non-free release. Therefore some methods sourcecode
will not be visible in the browsers - even with a correct installation. 


startup actions
---------------

During startup, ST/X reads a file called 'smalltalk.rc' to
setup some internal stuff. Since the search for this file is done
using the above path, you can put your private 'smalltalk.rc' into
either the current directory or '$HOME/.smalltalk'.

This script will first do some display-specific setup (using
'display.rc'), then some host-specific stuff ('host.rc')
and finally launch some default applications (currently the
Transcript and Launcher). You can of course add more to this
(for example, if you like to arrange for a browser to come
 up automatically).

'display.rc' tries to find out the kind of display hardware
you are working with, and then executes one of the 'd_xxx.rc'
scripts. have a look at 'display.rc' and change it as required.
You should leave the existing 'd_xxx.rc'-files unmodified - 
better add your own new one, and call it 'd_<displayname>.rc'.

'host.rc' tries to find out, what host you are running on
(which is NOT always the same as the display in X). Host
specific setup consists mainly of printer setup.
Also, you should leave those existing files alone, and add 
a new one, called 'd_<hostname>.rc'.


The second script called 'smalltalk_r.rc' is consulted, when 
a snapshot image is restarted; it also does display- and host
setup but not launch any new applications.


making fixes permanent
----------------------

Fixes can be made permanent by appending the fix to the 'patches' 
file, which is also read at initial startup.

Thus, any changes you dont want to re-apply manually after a 
new fresh start, should be put into the patches file.

The ChangesBrowser has a special entry to do this ('make change
permanent').


surviving a crash
-----------------

In contrast to other smalltalks, the snapshot image does not play a
central role in ST/X. You can easily live without one.
In case of a crash, you can (even without image) start ST/X anew,
and apply the changes made using the ChangesBrowser.
If your changes have already been made their way into the 'patches'
file, no manual actions are required.
(notice: to do so, you need a private 'patches' file, which must be 
 in the current directory)

Do not depend exclusively on the image - its a good idea to "fileOut" 
your classes in regular intervals - it happened in the past, that images 
where not readable, and a clean start had to be done.

I suggest, you add your new applications classes to the autoload-
list (see 'patches'-file for how this is done).

Also, since "fileOut" saves its stuff in the current directory, its a
good idea to use different directories for different projects.


Some warnings / notes before you get frustrated
-----------------------------------------------

The editTextView used in the FileBrowser has a bug in not handling TABs 
correctly (in this release) - it will convert all tabs to spaces 
on output. Thus, you should not edit Makefiles with the FileBrowser.

Submenus sometimes do not appear - instead a warning "GrabNotViewable"
is output - this is a known bug in the popup-views grab handling.


how to start
------------

There is some lack of documentation in this release, therefore you
will have to find your way yourself (this will change ...).

However, I suggest you use the fileBrowser, and have a look at
the coding examples in 'doc/coding', the small demo programs in
'doc/Demos' and finally the more complex demo applications (DrawTool,
LogicTool etc.). Also the document 'doc/misc/beginner' (which is 
a misnomer) gives a list of useful selectors.

If you want to do some programming with views, take a look at
'doc/misc/quick_view_intro', which gives a step-by-step introduction,
and will teach you in 5 minutes, how to create views, buttons etc.

These documents can also be accessed through the launchers menu.

For the language itself and the basic classes, please refer to standard 
literature, I recommend the wonderful book:

        "Smalltalk-80, The language and Implementation"

to everybody. It can be used also as a reference guide, since
most information found there is also valid for ST/X.


fin
---

Have fun with smalltalk. I hope this distribution helps to
get more people hooked to this great programming language !

- Claus (cg@ssw.de)
