                The Edinburgh Standard ML Program Library

                            Implementer's Guide

                                Dave Berry

                                 10/11/89


                -----------------------------------------

			       Introduction.

                -----------------------------------------

	The Edinburgh Standard ML Program Library is a library of modules
developed at Edinburgh for the Standard ML programming language.  An overview
of the library and an example entry are given in the User's Guide.  This
document describes what an implementer must provide with a library entry.


	Each entry must have a signature in the format described in the
User's Guide.  Some additional points about this format are described later
in this document.

	Each entry must also have a reference implementation.  This may also
be the actual implementation.  It must follow the simple format described
later in this document.

	The conventions described in the User's Guide must be observed in
new entries.  The User's Guide also mentions several standard names for
features; these names should be used where appropriate.

	Look at the existing entries before writing your own; this may
help focus your ideas.  The library includes two skeleton files, one for
signatures and one for functors.

	Don't use the identifiers "import" and "abstraction".  These are
keywords in Standard ML of New Jersey, so using them as identifiers will
make your code non-portable.


                -----------------------------------------

			  Format of Signatures.

                -----------------------------------------

	The format of signatures is that described in the User's Guide.
The following comments apply.

	The title of the entry and the heading for each section should be
entirely in upper case.

	The creation details should look like this:

  Created by:   Dave Berry, LFCS, University of Edinburgh
                db@lfcs.ed.ac.uk
  Date:         21 Sep 1989

  <Notes, e.g. acknowledgements>

	The maintenance details (if any) should look like this:

  Maintenance:  Author
or
  Maintenance:  Jo Bloggs, somewhere else.

	There may be more than one Maintenance line, but they should all
appear before the list of changes, and old entries should be deleted.  Any or
all Maintenance lines may be followed by notes.

	Each change (if any) should look like this:

  Modified by:  Jo Bloggs, Somewhere else
  Date:         29 Jun 1989

  <Brief description of change>

	New changes should be added at the end of the HEADER section.  Detailed
descriptions of the changes to an entry may be provided in a separate log.

	Throughout the HEADER section, the strings "Created by:", "Date:",
"Maintenance:" and "Modified by:" should only appear in the places above.
Addresses may take any number of lines, but should not include blank lines.
Dates should be in the format given here.  (Using one convention for dates
partly avoids confusion between different conventions and partly makes it
easier to write software tools for manipulating library entries.  If you want
to minimise the risk of typos, abbreviate March to Mch and June to Jne;
software tools should still recognise Mar and Jun).
 

	The DESCRIPTION section should be a general description of what the
signature provides and how to use it.  It should not include a description of
each function, but it may include notes on how to use particular functions.

	In a signature, the combination of this section and the descriptions
of each function should make suitable contents for an on-line "manual page".
Substantial library entries may have more detailed documentation available
separately.

                -----------------------------------------

			Format of Implementations.

                -----------------------------------------

	An implementation must include a HEADER section with the above
format.  It may also include DESCRIPTION, SEE ALSO or NOTES sections.
The DESCRIPTION section, if included, should give a brief discussion of
the implementation strategy.

	Functors should always use the derived form for arguments.  Each
functor that is intended to be visible to users should have argument and
result signatures that meet the requirements of the previous section.  The
HEADER and related sections should come between the name of the functor 
and the arguments.  For example:

  functor MonoVector (

  (* CONSTANT VECTORS OF A GIVEN TYPE

     Created by:  Dave Berry, LFCS, University of Edinburgh
                  db@lfcs.ed.ac.uk
     Date:        21 Dec 1989

     Maintenance: Author


     DESCRIPTION

     A constant vector is a unique sequence of objects that can't be changed.
     Vector is an equality type.  There is only one empty Vector.

     This is a reference implementation.  Most systems will provide most of
     the following as built-in functions.  Any sensible implementation will
     provide constant time access to each element.


     SEE ALSO

     Vector, RefVector.
  *)

    structure Object: Object
  ): MonoVector =
  struct

  ...

  end

	The definitions in the functor body should be grouped under the same
headings as those in the corresponding signature.  The heading LOCAL should
be used for auxiliary definitions that are used throughout the functor but
that aren't in the signature.


                -----------------------------------------

			     A note on files.

                -----------------------------------------

	The library conventions don't specify how entries should be divided
between files; this is system-specific.  You should use whatever conventions
are appropriate to your system.
