module/slib/README

   1 This directory contains the distribution of Scheme Library slib2d1.
   2 Slib conforms to Revised^5 Report on the Algorithmic Language Scheme
   3 and the IEEE P1178 specification.  Slib supports Unix and similar
   4 systems, VMS, and MS-DOS.
   5
   6 The maintainer can be reached at jaffer @ ai.mit.edu.
   7             http://swissnet.ai.mit.edu/~jaffer/SLIB.html
   8
   9                                MANIFEST
  10
  11   `README' is this file.  It contains a MANIFEST, INSTALLATION
  12         INSTRUCTIONS, and coding guidelines.
  13   `FAQ' Frequently Asked Questions and answers.
  14   `ChangeLog' documents changes to slib.
  15   `slib.texi' has documentation on library packages in TexInfo format.
  16
  17   `Template.scm' Example configuration file.  Copy and customize to
  18         reflect your system.
  19   `bigloo.init' is a configuration file for Bigloo.
  20   `chez.init' is a configuration file for Chez Scheme.
  21   `DrScheme.init' is a configuration file for DrScheme.
  22   `elk.init' is a configuration file for ELK 2.1
  23   `gambit.init' is a configuration file for Gambit Scheme.
  24   `macscheme.init' is a configuration file for MacScheme.
  25   `mitscheme.init' is a configuration file for MIT Scheme.
  26   `mitcomp.pat' is a patch file which adds definitions to SLIB files
  27         for the MitScheme compiler.
  28   `pscheme.init' is configuration file for PocketScheme 0.2.5 (WinCE SIOD)
  29   `RScheme.init' is a configuration file for RScheme.
  30   `scheme2c.init' is a configuration file for DEC's scheme->c.
  31   `scheme48.init' is a configuration file for Scheme48.
  32   `scsh.init' is a configuration file for Scheme-Shell
  33   `scm.init' is a configuration file for SCM.
  34   `t3.init' is a configuration file for T3.1 in Scheme mode.
  35   `STk.init' is a configuration file for STk.
  36   `umbscheme.init' is a configuration file for umb-scheme.
  37   `vscm.init' is a configuration file for VSCM.
  38   `mklibcat.scm' builds the *catalog* cache.
  39   `require.scm' has code which allows system independent access to
  40         the library files.
  41
  42   `Bev2slib.scm' Converts Stephen Bevan's "*.map" files to SLIB catalog entries.
  43   `format.scm' has Common-Lisp style format.
  44   `formatst.scm' has code to test format.scm
  45   `pp.scm' has pretty-print.
  46   `ppfile.scm' has pprint-file and pprint-filter-file.
  47   `obj2str.scm' has object->string.
  48   `strcase.scm' has functions for manipulating the case of strings.
  49   `genwrite.scm' has a generic-write which is used by pp.scm,
  50         pp2str.scm and obj2str.scm
  51   `printf.scm' has printf, fprintf, and sprintf compatible with C.
  52   `scanf.scm' has scanf, fscanf, and sscanf compatible by C.
  53   `lineio' has line oriented input/output functions.
  54   `qp.scm' has printer safe for circular structures.
  55   `break.scm' has break and continue.
  56   `trace.scm' has trace and untrace for tracing function execution.
  57   `debug.scm' has handy higher level debugging aids.
  58   `strport.scm' has routines for string-ports.
  59   `strsrch.scm' search for chars or substrings in strings and ports.
  60
  61   `alist.scm' has functions accessing and modifying association lists.
  62   `hash.scm' defines hash, hashq, and hashv.
  63   `hashtab.scm' has hash tables.
  64   `sierpinski.scm' 2-dimensional coordinate hash.
  65   `soundex.scm' English name hash.
  66   `logical.scm' emulates 2's complement logical operations.
  67   `random.scm' has random number generator compatible with Common Lisp.
  68   `randinex.scm' has inexact real number distributions.
  69   `primes.scm' has primes and probably-prime?.
  70   `factor.scm' has factor.
  71   `root.scm' has Newton's and Laguerre's methods for finding roots.
  72   `minimize.scm' has Golden Section Search for minimum value.
  73   `cring.scm' extend + and * to custom commutative rings.
  74   `selfset.scm' sets single letter identifiers to their symbols.
  75   `determ.scm' compute determinant of list of lists.
  76   `charplot.scm' has procedure for plotting on character screens.
  77   `plottest.scm' has code to test charplot.scm.
  78   `tek40.scm' has routines for Tektronix 4000 series graphics.
  79   `tek41.scm' has routines for Tektronix 4100 series graphics.
  80   `getopt.scm' has posix-like getopt for parsing command line arguments.
  81   `psxtime.scm' has Posix time conversion routines.
  82   `cltime.scm' has Common-Lisp time conversion routines.
  83   `timezone.scm' has the default time-zone, UTC.
  84   `tzfile.scm' reads sysV style (binary) timezone file.
  85   `comparse.scm' has shell-like command parsing.
  86
  87   `rdms.scm' has code to construct a relational database from a base
  88         table implementation.
  89   `alistab.scm' has association list base tables.
  90   `dbutil.scm' has utilities for creating and manipulating relational
  91         databases.
  92   `htmlform.scm' generates HTML-3.2 with forms.
  93   `db2html.scm' convert relational database to hyperlinked tables and
  94         pages.
  95   `http-cgi.scm' serves WWW pages with HTTP or CGI.
  96   `uri.scm' encodes and decodes Uniform Resource Identifiers.
  97   `dbrowse.scm' browses relational databases.
  98   `paramlst.scm' has procedures for passing parameters by name.
  99   `getparam.scm' has procedures for converting getopt to parameters.
 100   `report.scm' prints database reports.
 101   `schmooz.scm' is a simple, lightweight markup language for
 102         interspersing Texinfo documentation with Scheme source code.
 103   `glob.scm' has filename matching and manipulation.
 104   `batch.scm' Group and execute commands on various operating systems.
 105   `makcrc.scm' Create Scheme procedure to calculate POSIX.2 checksums
 106         or other CRCs.
 107
 108   `record.scm' a MITScheme user-definable datatypes package
 109   `promise.scm' has code from R4RS for supporting DELAY and FORCE.
 110
 111   `repl.scm' has a read-eval-print-loop.
 112   `defmacex.scm' has defmacro:expand*.
 113   `mbe.scm' has "Macro by Example" define-syntax.
 114   `scmacro.scm' is a syntactic closure R4RS macro package.
 115         r4rsyn.scm, synclo.scm, synrul.scm have syntax definitions
 116         and support.
 117   `scmactst.scm' is code for testing SYNTACTIC CLOSURE macros.
 118   `scainit.scm' is a syntax-case R4RS macro package.
 119         scaglob.scm scamacr.scm scaoutp.scm scaexpp.scm have
 120         syntax definitions and support.  `syncase.sh' is a shell
 121         script for producing the SLIB version from the original.
 122   `macwork.scm' is a "Macros that work" package.
 123         mwexpand.scm mwdenote.scm mwsynrul.scm have support.
 124   `macrotst.scm' is code from R4RS for testing macros.
 125
 126   `values.scm' is multiple values.
 127   `queue.scm' has queues and stacks.
 128
 129   `object.scm' is an object system.
 130   `yasyn.scm' defines (syntax-rules) macros for object oriented programming.
 131   `collect.scm' is collection operators (like CL sequences).
 132   `priorque.scm' has code and documentation for priority queues.
 133   `wttree.scm' has weight-balanced trees.
 134   `wttest.scm' tests weight-balanced trees.
 135   `process.scm' has multi-processing primitives.
 136   `array.scm' has multi-dimensional arrays and sub-arrays.
 137   `arraymap.scm' has array-map!, array-for-each, and array-indexes.
 138
 139   `sort.scm' has sorted?, sort, sort!, merge, and merge!.
 140   `tsort.scm' has topological-sort.
 141   `comlist.scm' has many common list and mapping procedures.
 142   `tree.scm' has functions dealing with trees.
 143   `coerce.scm' has coerce and type-of from Common-Lisp.
 144   `chap.scm' has functions which compare and create strings in
 145         "chapter order".
 146
 147   `sc4opt.scm' has optional rev4 procedures.
 148   `sc4sc3.scm' has procedures to make a rev3 implementation run rev4
 149         code.
 150   `sc2.scm' has rev2 procedures eliminated in subsequent versions.
 151   `mularg.scm' redefines - and / to take more than 2 arguments.
 152   `mulapply.scm' redefines apply to take more than 2 arguments.
 153   `ratize.scm' has function rationalize from Revised^4 spec.
 154   `trnscrpt.scm' has transcript-on and transcript-off from Revised^4 spec.
 155   `withfile.scm' has with-input-from-file and with-output-to-file from R4RS.
 156   `dynwind.scm' has dynamic-wind from R5RS.
 157   `eval.scm' has eval with environments from R5RS.
 158   `dwindtst.scm' has routines for characterizing dynamic-wind.
 159   `dynamic.scm' has DYNAMIC data type [obsolete].
 160   `fluidlet.scm' has fluid-let syntax.
 161   `struct.scm' has defmacros which implement RECORDS from the book:
 162         "Essentials of Programming Languages".
 163   `structure.scm' has syntax-case macros for the same.
 164   `structst.scm' has test code for struct.scm.
 165   `byte.scm' has arrays of small integers.
 166   `nclients.scm' provides a Scheme interface to FTP and WWW Browsers.
 167   `pnm.scm' provides a Scheme interface to "portable bitmap" files.
 168   `simetrix.scm' provides SI Metric Interchange Format.
 169
 170                       INSTALLATION INSTRUCTIONS
 171
 172   Check the manifest in `README' to find a configuration file for your
 173 Scheme implementation.  Initialization files for most IEEE P1178
 174 compliant Scheme Implementations are included with this distribution.
 175
 176   If the Scheme implementation supports `getenv', then the value of the
 177 shell environment variable SCHEME_LIBRARY_PATH will be used for
 178 `(library-vicinity)' if it is defined.  Currently, Chez, Elk,
 179 MITScheme, scheme->c, VSCM, and SCM support `getenv'.  Scheme48
 180 supports `getenv' but does not use it for determining
 181 `library-vicinity'.  (That is done from the Makefile.)
 182
 183   You should check the definitions of `software-type',
 184 `scheme-implementation-version', `implementation-vicinity', and
 185 `library-vicinity' in the initialization file.  There are comments in
 186 the file for how to configure it.
 187
 188   Once this is done you can modify the startup file for your Scheme
 189 implementation to `load' this initialization file.  SLIB is then
 190 installed.
 191
 192   Multiple implementations of Scheme can all use the same SLIB
 193 directory.  Simply configure each implementation's initialization file
 194 as outlined above.
 195
 196  - Implementation: SCM
 197      The SCM implementation does not require any initialization file as
 198      SLIB support is already built into SCM.  See the documentation
 199      with SCM for installation instructions.
 200
 201  - Implementation: VSCM
 202      From: Matthias Blume <blume@cs.Princeton.EDU>
 203      Date: Tue, 1 Mar 1994 11:42:31 -0500
 204
 205      Disclaimer: The code below is only a quick hack.  If I find some
 206      time to spare I might get around to make some more things work.
 207
 208      You have to provide `vscm.init' as an explicit command line
 209      argument.  Since this is not very nice I would recommend the
 210      following installation procedure:
 211
 212        1. run scheme
 213
 214        2. `(load "vscm.init")'
 215
 216        3. `(slib:dump "dumpfile")'
 217
 218        4. mv dumpfile place-where-vscm-standard-bootfile-resides e.g.
 219           mv dumpfile /usr/local/vscm/lib/scheme-boot (In this case
 220           vscm should have been compiled with flag
 221           -DDEFAULT_BOOTFILE='"/usr/local/vscm/lib/scheme-boot"'.  See
 222           Makefile (definition of DDP) for details.)
 223
 224
 225  - Implementation: Scheme48
 226      To make a Scheme48 image for an installation under `<prefix>',
 227
 228        1. `cd' to the SLIB directory
 229
 230        2. type `make prefix=<prefix> slib48'.
 231
 232        3. To install the image, type `make prefix=<prefix> install48'.
 233           This will also create a shell script with the name `slib48'
 234           which will invoke the saved image.
 235
 236  - Implementation: PLT Scheme
 237  - Implementation: DrScheme
 238  - Implementation: MzScheme
 239      Date: Mon, 2 Oct 2000 21:29:48 -0400 (EDT)
 240      From: Shriram Krishnamurthi <sk@cs.brown.edu>
 241
 242      We distribute an SLIB init file for our system.  If you have PLT
 243      Scheme (our preferred name for the entire suite, which includes
 244      DrScheme, MzScheme and other implementations) installed, you ought
 245      to be able to run "help-desk", or run `drscheme' and choose Help
 246      Desk from the Help menu; in Help Desk, type `slib'.  This will give
 247      instructions for how to load the SLIB init file.
 248
 249                          PORTING INSTRUCTIONS
 250
 251   If there is no initialization file for your Scheme implementation, you
 252 will have to create one.  Your Scheme implementation must be largely
 253 compliant with
 254   `IEEE Std 1178-1990',
 255   `Revised(4) Report on the Algorithmic Language Scheme', or
 256   `Revised(5) Report on the Algorithmic Language Scheme'
 257 in order to support SLIB.
 258
 259   `Template.scm' is an example configuration file.  The comments inside
 260 will direct you on how to customize it to reflect your system.  Give
 261 your new initialization file the implementation's name with `.init'
 262 appended.  For instance, if you were porting `foo-scheme' then the
 263 initialization file might be called `foo.init'.
 264
 265   Your customized version should then be loaded as part of your scheme
 266 implementation's initialization.  It will load `require.scm' from the
 267 library; this will allow the use of `provide', `provided?', and
 268 `require' along with the "vicinity" functions.  The rest of the
 269 library will then be accessible in a system independent fashion.
 270
 271   Please mail new working configuration files to `jaffer@ai.mit.edu' so
 272 that they can be included in the SLIB distribution.
 273
 274                           CODING GUIDELINES
 275
 276   All library packages are written in IEEE P1178 Scheme and assume that
 277 a configuration file and `require.scm' package have already been
 278 loaded.  Other versions of Scheme can be supported in library packages
 279 as well by using, for example, `(provided? 'rev3-report)' or `(require
 280 'rev3-report)'.
 281
 282   `require.scm' defines `*catalog*', an association list of module
 283 names and filenames.  When a new package is added to the library, an
 284 entry should be added to `require.scm'.  Local packages can also be
 285 added to `*catalog*' and even shadow entries already in the table.
 286
 287   The module name and `:' should prefix each symbol defined in the
 288 package.  Definitions for external use should then be exported by having
 289 `(define foo module-name:foo)'.
 290
 291   Submitted packages should not duplicate routines which are already in
 292 SLIB files.  Use `require' to force those features to be supported in
 293 your package.  Care should be taken that there are no circularities in
 294 the `require's and `load's between the library packages.
 295
 296   Documentation should be provided in Emacs Texinfo format if possible,
 297 But documentation must be provided.