README: SAN Kit (Standard Algebraic Notation source toolkit) information file

Revised: 1994.02.22

By: Steven J. Edwards (sje@world.std.com)

SAN Kit Research Project
P.O. Box 215
Chelmsford, MA 01824
USA

This is the information file for the SAN Kit chess software package.


No warranty
-----------

All of the contents of this package are provided "as is" and without warranty
of any kind.  Use at your own risk.  The package may be redistributed freely as
long as this README file remains in the distribution with this paragraph
unmodified.  The package may be used in both free and commercial applications
as long as future distribution is unhindered.  It may be stored at ftp sites
and on commercial timesharing services.  There is no guarantee of support of
any kind by the original author or later contributors.


Purpose
-------

This package contains a set of C language source files that support chess
programming.  They may be used for study, for expanding the capabilities of
existing chess programs (if one has the source), for writing chess related
applications (opening repositories), and for writing one's own chess program.
From some to all of the supplied routines may be used as required.  When taken
as a whole, the SAN Kit routines provide most of the required code for a
chessplaying program.  Users can add search and evaluation routines and have a
working program in a few days.


Directories
-----------

The directories in this release are named SAN_DOC, SAN_MSC, and SAN_SRC.

The SAN_DOC directory is for documentation and some test suites.  The SAN_MSC
directory  has various miscellaneous files.  The SAN_SRC directory has the
project source files and the Makefile.

In the source directory, note that each C language file with a ".c" suffix has
a corresponding ".h" file that contains the function headers for the nonstatic
routines in the ".c" file.  These are function prototypes for use with ANSI C
compilers.  Also, note that all of the files are formatted with tab stops set
at every four columns instead of eight as used by some.  One may wish to run
the source through a formatter program.


Platforms
---------

The SAN Kit was first developed using a slightly hacked Apple Macintosh Plus
(16 MHz MC68030) with the ANSI C Think C compiler by Symantec.  A 16 MHz
iAPX386 SX notebook machine using gcc 2.3.2 under Mark Williams Company
Coherent (Unix clone) operating system is also employed for development and
testing.  A 33 MHz iAPX486 DX tower machine that also uses Coherent is drafted
for long duration stress testing.

In addition to the above, the SAN Kit has been reported to be used on machines
including Mega ST units from Atari, Amiga platforms from Commodore, several
implementations of MS-DOS on Intel boxes, VAX systems (VMS and Ultrix) from
DEC, and Unix systems too numerous to mention.

It is intended that the strict adherence to ANSI C along with the avoidance of
platform specific behavioralisms allows the SAN Kit to compile and run on any
reasonable C environment.  Also, as the SAN Kit uses a simple text interface,
there is no worry about graphical user interface dependencies.  Of course,
experimenters are welcome to construct or adapt a GUI for their own purposes.

Experimenters using limited platforms with only 64 Kbyte data space might want
to shrink some of the allocation limits (e.g., legL and fmpL in the file
sandef.h).  Alternatively, those cursed with baroque segmentation schemes may
want to try large memory model compilation.


Suggested starting areas for newcomers
--------------------------------------

The Manifest file briefly describes all of the project files.

The Manual file, incomplete at this time, will contain a complete guide to the
command line user interface.

The Makefile in the source directory lists the source files of interest.  It is
likely that the Makefile may need to be slightly modified for different C
language development environments.

The best place to start is the file sandef.h which has the global definitions
for preprocessor constants and typedef information.  The file sanvar.c contains
the global variables with the external declarations appearing in sanvar.h.

The SAN Kit package is configured with an interactive command line processor.
This processor is also able to handle nested command batch files.  The commands
listed in sandef.h are dispatched from sancmd.c and are handled in sandci.c.
The "help" command gives a brief description of each command and each program
option.  The command set forms the basis the the upcoming IPCC (Inter Program
Chess Communication) standard.

SAN move notation encoding is found in file sanmne.c and decoding is found in
file sanmnd.c.

FEN position notation encoding and decoding is found in file sanfen.c.

PGN game notation encoding is found in file sanpgn.c.  PGN decoding is the file
sanrdr.c.

Example strategy modules are of the form "x_???.c"; the samples include the
"eat", "gtp", "ran", "sc0", and "sc1" strategies.

To find out what each file is about, try (in directory SAN_SRC):

    grep -e ">>>" *.[hc]

To list all the function abstracts, try (also in directory SAN_SRC):

    grep -e "-->" *.c

Our Mottos
----------

    "Gens una sumus."

    "Go standard or go home."

    "No case too big, no case too small."

README: EOF
