[MLton-commit] r6181

[Vesa Karvonen]

Updated documentation.
----------------------------------------------------------------------

U   mltonlib/trunk/org/mlton/vesak/use-lib/unstable/README
U   mltonlib/trunk/org/mlton/vesak/use-lib/unstable/public/use-lib.sig

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

Modified: mltonlib/trunk/org/mlton/vesak/use-lib/unstable/README
===================================================================
--- mltonlib/trunk/org/mlton/vesak/use-lib/unstable/README	2007-11-19 17:25:35 UTC (rev 6180)
+++ mltonlib/trunk/org/mlton/vesak/use-lib/unstable/README	2007-11-19 22:05:56 UTC (rev 6181)
@@ -1,9 +1,9 @@
 Use Library
 -----------
 
-   This library implements a simple library and program definition
-   framework based on the de facto standard use-function provided by most
-   SML implementations with a REPL.
+   This is a simple library for defining separately loadable program
+   components based on the de facto standard use -function provided by
+   most Standard ML implementations with a REPL.
 
 
 Info
@@ -11,7 +11,7 @@
 
    License:         MLton license (a BSD-style license)
    Portability:     requires the use-function
-   Ported to:       Moscow ML, Poly/ML, and SML/NJ
+   Ported to:       Alice ML, Moscow ML, Poly/ML, and SML/NJ
    Stability:       experimental
    Maintainer:      Vesa Karvonen <vesa.a.j.k at gmail.com>
 
@@ -35,7 +35,14 @@
 
       This directory contains the implementation details of the library.
 
+   detail/ml/$(SML_COMPILER)/workarounds.sml
 
+      These files contain compiler specific workarounds.  On a fully
+      conforming compiler this file is not needed.  You can help by
+      implementing missing Basis library features and fixing bugs and
+      deviations in compilers.
+
+
 Motivation
 ----------
 

Modified: mltonlib/trunk/org/mlton/vesak/use-lib/unstable/public/use-lib.sig
===================================================================
--- mltonlib/trunk/org/mlton/vesak/use-lib/unstable/public/use-lib.sig	2007-11-19 17:25:35 UTC (rev 6180)
+++ mltonlib/trunk/org/mlton/vesak/use-lib/unstable/public/use-lib.sig	2007-11-19 22:05:56 UTC (rev 6181)
@@ -6,18 +6,54 @@
 
 (**
  * Signature for the {UseLib} module that provides a simple {use} based
- * library definition framework.
+ * library for defining separately loadable program components.
+ *
+ * A program component is defined by creating a SML source file with the
+ * "use" suffix and calling the {lib} function exactly once in it.  Such a
+ * component can then be loaded either explicitly from the top-level by
+ * calling {use}, or implicitly by loading some other component that
+ * refers to it through {lib}.  Files specified to {lib} are loaded in the
+ * specified order, but each component (file with suffix "use") is loaded
+ * at most once.
+ *
+ * Paths given to the {lib} and {use} functions may contain references to
+ * environment variables, e.g. "${VARIABLE}".  The predefined variable
+ * "${SML_COMPILER}" gives the mnemonic name of the SML compiler.
+ *
+ * For example, suppose you have the file "foo.sig" containing the code:
+ *
+ *> signature FOO = sig val bar : unit -> unit end
+ *
+ * and the file "foo.sml" containing the code:
+ *
+ *> structure Foo : FOO = struct fun bar () = print "Foo.bar ()\n" end
+ *
+ * You could then define the component "foo.use" as:
+ *
+ *> lib ["foo.sig", "foo.sml"] ;
+ *
+ * You can then load it from the top-level by calling:
+ *
+ *> use "foo.use" ;
+ *
+ * or refer to it from other components:
+ *
+ *> lib [..., "path-to/foo.use", ...] ;
  *)
 signature USE_LIB = sig
    val lib : string list -> unit
    (**
-    * Defines a library composed of the specified libraries and source
-    * files.
+    * Defines a single program component composed of the specified
+    * components (files with the suffix "use") and source files (files
+    * with suffix other than "use").  Each call to {lib} must be in a
+    * unique "use" file.  Relative paths given to {lib} are relative to
+    * the directory of the "use" file containing the {lib} call.
     *)
 
    val use : string -> unit
    (**
-    * Loads the specified library or uses the specified source file.
-    * Environment variable references are allowed within the path.
+    * Used from the top-level to load a specified program component or
+    * source file.  Program components, with the "use" suffix, are loaded
+    * at most once.
     *)
 end