path: root/README

This directory contains the distribution of Scheme Library slib2d2.
Slib conforms to Revised^5 Report on the Algorithmic Language Scheme
and the IEEE P1178 specification.  Slib supports Unix and similar
systems, VMS, and MS-DOS.

The maintainer can be reached at agj @ alum.mit.edu.
	    http://swissnet.ai.mit.edu/~jaffer/SLIB.html

			       MANIFEST

  `README' is this file.  It contains a MANIFEST, INSTALLATION
	INSTRUCTIONS, and coding guidelines.
  `FAQ' Frequently Asked Questions and answers.
  `ChangeLog' documents changes to slib.
  `slib.texi' has documentation on library packages in TexInfo format.

  `Template.scm' Example configuration file.  Copy and customize to
	reflect your system.
  `bigloo.init' is a configuration file for Bigloo.
  `chez.init' is a configuration file for Chez Scheme.
  `DrScheme.init' is a configuration file for DrScheme.
  `elk.init' is a configuration file for ELK 2.1
  `gambit.init' is a configuration file for Gambit Scheme.
  `macscheme.init' is a configuration file for MacScheme.
  `mitscheme.init' is a configuration file for MIT Scheme.
  `pscheme.init' is configuration file for PocketScheme 0.2.5 (WinCE SIOD)
  `RScheme.init' is a configuration file for RScheme.
  `scheme2c.init' is a configuration file for DEC's scheme->c.
  `scheme48.init' is a configuration file for Scheme48.
  `s48-0_57.init is a configuration file for Scheme48-0.57.
  `scsh.init' is a configuration file for Scheme-Shell
  `scm.init' is a configuration file for SCM.
  `t3.init' is a configuration file for T3.1 in Scheme mode.
  `STk.init' is a configuration file for STk.
  `umbscheme.init' is a configuration file for umb-scheme.  
  `vscm.init' is a configuration file for VSCM.
  `guile.init' is a configuration file for guile.
  `mklibcat.scm' builds the *catalog* cache.
  `require.scm' has code which allows system independent access to
	the library files.

  `Bev2slib.scm' Converts Stephen Bevan's "*.map" files to SLIB catalog entries.
  `format.scm' has Common-Lisp style format.
  `formatst.scm' has code to test format.scm
  `pp.scm' has pretty-print.
  `ppfile.scm' has pprint-file and pprint-filter-file.
  `obj2str.scm' has object->string.
  `strcase.scm' has functions for manipulating the case of strings.
  `genwrite.scm' has a generic-write which is used by pp.scm,
	pp2str.scm and obj2str.scm
  `printf.scm' has printf, fprintf, and sprintf compatible with C.
  `scanf.scm' has scanf, fscanf, and sscanf compatible by C.
  `lineio' has line oriented input/output functions.
  `qp.scm' has printer safe for circular structures.
  `break.scm' has break and continue.
  `trace.scm' has trace and untrace for tracing function execution.
  `debug.scm' has handy higher level debugging aids.
  `strport.scm' has routines for string-ports.
  `strsrch.scm' search for chars or substrings in strings and ports.
  `differ.scm' An O(NP) Sequence Comparison Algorithm.

  `alist.scm' has functions accessing and modifying association lists.
  `hash.scm' defines hash, hashq, and hashv.
  `hashtab.scm' has hash tables.
  `sierpinski.scm' 2-dimensional coordinate hash.
  `soundex.scm' English name hash.
  `logical.scm' emulates 2's complement logical operations.
  `random.scm' has random number generator compatible with Common Lisp.
  `randinex.scm' has inexact real number distributions.
  `primes.scm' has primes and probably-prime?.
  `factor.scm' has factor.
  `root.scm' has Newton's and Laguerre's methods for finding roots.
  `minimize.scm' has Golden Section Search for minimum value.
  `cring.scm' extend + and * to custom commutative rings.
  `selfset.scm' sets single letter identifiers to their symbols.
  `determ.scm' compute determinant of list of lists.
  `charplot.scm' has procedure for plotting on character screens.
  `plottest.scm' has code to test charplot.scm.
  `tek40.scm' has routines for Tektronix 4000 series graphics.
  `tek41.scm' has routines for Tektronix 4100 series graphics.
  `getopt.scm' has posix-like getopt for parsing command line arguments. 
  `psxtime.scm' has Posix time conversion routines.
  `cltime.scm' has Common-Lisp time conversion routines.
  `timezone.scm' has the default time-zone, UTC.
  `tzfile.scm' reads sysV style (binary) timezone file.
  `comparse.scm' has shell-like command parsing.

  `rdms.scm' has code to construct a relational database from a base
	table implementation.
  `alistab.scm' has association list base tables.
  `dbutil.scm' has utilities for creating and manipulating relational
	databases.
  `htmlform.scm' generates HTML-3.2 with forms.
  `db2html.scm' convert relational database to hyperlinked tables and
	pages.
  `http-cgi.scm' serves WWW pages with HTTP or CGI.
  `uri.scm' encodes and decodes Uniform Resource Identifiers.
  `dbrowse.scm' browses relational databases.
  `paramlst.scm' has procedures for passing parameters by name.
  `getparam.scm' has procedures for converting getopt to parameters.
  `report.scm' prints database reports.
  `schmooz.scm' is a simple, lightweight markup language for
	interspersing Texinfo documentation with Scheme source code.
  `glob.scm' has filename matching and manipulation.
  `batch.scm' Group and execute commands on various operating systems.
  `makcrc.scm' Create Scheme procedure to calculate POSIX.2 checksums
	or other CRCs.

  `record.scm' a MITScheme user-definable datatypes package
  `promise.scm' has code from R4RS for supporting DELAY and FORCE.

  `repl.scm' has a read-eval-print-loop.
  `defmacex.scm' has defmacro:expand*.
  `mbe.scm' has "Macro by Example" define-syntax.
  `scmacro.scm' is a syntactic closure R4RS macro package.
	r4rsyn.scm, synclo.scm, synrul.scm have syntax definitions
	and support.
  `scmactst.scm' is code for testing SYNTACTIC CLOSURE macros.
  `scainit.scm' is a syntax-case R4RS macro package.
	scaglob.scm scamacr.scm scaoutp.scm scaexpp.scm have
	syntax definitions and support.  `syncase.sh' is a shell
	script for producing the SLIB version from the original.
  `macwork.scm' is a "Macros that work" package.
	mwexpand.scm mwdenote.scm mwsynrul.scm have support.
  `macrotst.scm' is code from R4RS for testing macros.

  `values.scm' is multiple values.
  `queue.scm' has queues and stacks.

  `object.scm' is an object system.
  `yasyn.scm' defines (syntax-rules) macros for object oriented programming.
  `collect.scm' is collection operators (like CL sequences).
  `priorque.scm' has code and documentation for priority queues.
  `wttree.scm' has weight-balanced trees.
  `wttest.scm' tests weight-balanced trees.
  `process.scm' has multi-processing primitives.
  `array.scm' has multi-dimensional arrays and sub-arrays.
  `arraymap.scm' has array-map!, array-for-each, and array-indexes.

  `sort.scm' has sorted?, sort, sort!, merge, and merge!.
  `tsort.scm' has topological-sort.
  `comlist.scm' has many common list and mapping procedures.
  `tree.scm' has functions dealing with trees.
  `coerce.scm' has coerce and type-of from Common-Lisp.
  `chap.scm' has functions which compare and create strings in
	"chapter order".

  `sc4opt.scm' has optional rev4 procedures.
  `sc4sc3.scm' has procedures to make a rev3 implementation run rev4
	code. 
  `sc2.scm' has rev2 procedures eliminated in subsequent versions.
  `mularg.scm' redefines - and / to take more than 2 arguments.
  `mulapply.scm' redefines apply to take more than 2 arguments.
  `ratize.scm' has function rationalize from Revised^4 spec.
  `trnscrpt.scm' has transcript-on and transcript-off from Revised^4 spec.
  `withfile.scm' has with-input-from-file and with-output-to-file from R4RS.
  `dynwind.scm' has dynamic-wind from R5RS.
  `eval.scm' has eval with environments from R5RS.
  `dwindtst.scm' has routines for characterizing dynamic-wind.
  `dynamic.scm' has DYNAMIC data type [obsolete].
  `fluidlet.scm' has fluid-let syntax.
  `structure.scm' has undocumented syntax-case macros.
  `byte.scm' has arrays of small integers.
  `nclients.scm' provides a Scheme interface to FTP and WWW Browsers.
  `pnm.scm' provides a Scheme interface to "portable bitmap" files.
  `simetrix.scm' provides SI Metric Interchange Format.
  `srfi.scm' implements Scheme Request for Implementation.
  `srfi-N.scm' implements srfi-N.

		      INSTALLATION INSTRUCTIONS

  There are four parts to installation:

   * Unpack the SLIB distribution.

   * Configure the Scheme implementation(s) to locate the SLIB
     directory.

   * Arrange for Scheme implementation to load its SLIB initialization
     file.

   * Build the SLIB catalog for the Scheme implementation.

Unpacking the SLIB Distribution
-------------------------------

  If the SLIB distribution is a Linux RPM, it will create the SLIB
directory `/usr/share/slib'.

  If the SLIB distribution is a ZIP file, unzip the distribution to
create the SLIB directory.  Locate this `slib' directory either in your
home directory (if only you will use this SLIB installation); or put it
in a location where libraries reside on your system.  On unix systems
this might be `/usr/share/slib', `/usr/local/lib/slib', or
`/usr/lib/slib'.  If you know where SLIB should go on other platforms,
please inform agj @ alum.mit.edu.

Configure Scheme Implementation to Locate SLIB
----------------------------------------------

  If the Scheme implementation supports `getenv', then the value of the
shell environment variable SCHEME_LIBRARY_PATH will be used for
`(library-vicinity)' if it is defined.  Currently, Chez, Elk,
MITScheme, scheme->c, VSCM, and SCM support `getenv'.  Scheme48
supports `getenv' but does not use it for determining
`library-vicinity'.  (That is done from the Makefile.)

  The `(library-vicinity)' can also be specified from the SLIB
initialization file or by implementation-specific means.

Loading SLIB Initialization File
--------------------------------

  Check the manifest in `README' to find a configuration file for your
Scheme implementation.  Initialization files for most IEEE P1178
compliant Scheme Implementations are included with this distribution.

  You should check the definitions of `software-type',
`scheme-implementation-version', `implementation-vicinity', and
`library-vicinity' in the initialization file.  There are comments in
the file for how to configure it.

  Once this is done, modify the startup file for your Scheme
implementation to `load' this initialization file.

Build New SLIB Catalog for Implementation
-----------------------------------------

  When SLIB is first used from an implementation, a file named
`slibcat' is written to the `implementation-vicinity' for that
implementation.  Because users may lack permission to write in
`implementation-vicinity', it is good practice to build the new catalog
when installing SLIB.

  To build (or rebuild) the catalog, start the Scheme implementation
(with SLIB), then:

     (require 'new-catalog)

Implementation-specific Instructions
------------------------------------

  Multiple implementations of Scheme can all use the same SLIB
directory.  Simply configure each implementation's initialization file
as outlined above.

 - Implementation: SCM
     The SCM implementation does not require any initialization file as
     SLIB support is already built into SCM.  See the documentation
     with SCM for installation instructions.

 - Implementation: VSCM
     From: Matthias Blume <blume @ cs.Princeton.EDU>
     Date: Tue, 1 Mar 1994 11:42:31 -0500

     Disclaimer: The code below is only a quick hack.  If I find some
     time to spare I might get around to make some more things work.

     You have to provide `vscm.init' as an explicit command line
     argument.  Since this is not very nice I would recommend the
     following installation procedure:

       1. run scheme

       2. `(load "vscm.init")'

       3. `(slib:dump "dumpfile")'

       4. mv dumpfile place-where-vscm-standard-bootfile-resides e.g.
          mv dumpfile /usr/local/vscm/lib/scheme-boot (In this case
          vscm should have been compiled with flag
          -DDEFAULT_BOOTFILE='"/usr/local/vscm/lib/scheme-boot"'.  See
          Makefile (definition of DDP) for details.)


 - Implementation: Scheme48
     To make a Scheme48 image for an installation under `<prefix>',

       1. `cd' to the SLIB directory

       2. type `make prefix=<prefix> slib48'.

       3. To install the image, type `make prefix=<prefix> install48'.
          This will also create a shell script with the name `slib48'
          which will invoke the saved image.

 - Implementation: PLT Scheme
 - Implementation: DrScheme
 - Implementation: MzScheme
     The `init.ss' file in the _slibinit_ collection is an SLIB
     initialization file.

     To use SLIB in MzScheme, set the SCHEME_LIBRARY_PATH environment
     variable to the installed SLIB location; then invoke MzScheme thus:

     `mzscheme -L init.ss slibinit'

 - Implementation: MIT Scheme
     `scheme -load ${SCHEME_LIBRARY_PATH}mitscheme.init'

 - Implementation: Guile
     `guile -l ${SCHEME_LIBRARY_PATH}guile.init'

			 PORTING INSTRUCTIONS

  If there is no initialization file for your Scheme implementation, you
will have to create one.  Your Scheme implementation must be largely
compliant with
  `IEEE Std 1178-1990',
  `Revised(4) Report on the Algorithmic Language Scheme', or
  `Revised(5) Report on the Algorithmic Language Scheme'
in order to support SLIB.

  `Template.scm' is an example configuration file.  The comments inside
will direct you on how to customize it to reflect your system.  Give
your new initialization file the implementation's name with `.init'
appended.  For instance, if you were porting `foo-scheme' then the
initialization file might be called `foo.init'.

  Your customized version should then be loaded as part of your scheme
implementation's initialization.  It will load `require.scm' from the
library; this will allow the use of `provide', `provided?', and
`require' along with the "vicinity" functions.  The rest of the
library will then be accessible in a system independent fashion.

  Please mail new working configuration files to `agj @ alum.mit.edu' so
that they can be included in the SLIB distribution.

			  CODING GUIDELINES

  All library packages are written in IEEE P1178 Scheme and assume that
a configuration file and `require.scm' package have already been
loaded.  Other versions of Scheme can be supported in library packages
as well by using, for example, `(provided? 'rev3-report)' or `(require
'rev3-report)'.

  `require.scm' defines `*catalog*', an association list of module
names and filenames.  When a new package is added to the library, an
entry should be added to `require.scm'.  Local packages can also be
added to `*catalog*' and even shadow entries already in the table.

  The module name and `:' should prefix each symbol defined in the
package.  Definitions for external use should then be exported by having
`(define foo module-name:foo)'.

  Submitted packages should not duplicate routines which are already in
SLIB files.  Use `require' to force those features to be supported in
your package.  Care should be taken that there are no circularities in
the `require's and `load's between the library packages.

  Documentation should be provided in Emacs Texinfo format if possible,
But documentation must be provided.