doc work on modules, new big collection

svn: r6732

collects/big/define-struct.ss

@@ -4,7 +4,7 @@
 ;; though, strangely and embarassingly, Matthew didn't know that until
 ;; after he had mostly re-implemented it.
 
-(module new-struct mzscheme
+(module define-struct mzscheme
   (require (lib "stxparam.ss"))
 
   (provide define-struct*

collects/big/info.ss

@@ -0,0 +1,3 @@
+(module info (lib "infotab.ss" "setup")
+  (define name "Big Scheme"))
+

collects/big/lang.ss

@@ -0,0 +1,16 @@
+(module lang mzscheme
+  (require "define-struct.ss"
+           "new-lambda.ss")
+
+  (provide (all-from-except mzscheme #%datum lambda define #%app define-struct)
+           (rename new-datum #%datum)
+           (rename new-lambda lambda)
+           (rename new-define define)
+           (rename new-app #%app)
+           make-keyword-procedure
+           keyword-apply
+           procedure-keywords
+           (rename define-struct* define-struct)
+           struct-field-index))
+
+

collects/big/new-lambda.ss

@@ -1,18 +1,14 @@
 (module new-lambda mzscheme
   (require-for-syntax (lib "name.ss" "syntax")
                       (lib "define.ss" "syntax"))
-  (require "new-struct.ss")
 
-  (provide (all-from-except mzscheme #%datum lambda define #%app define-struct)
+  (provide new-datum 
-           (rename new-datum #%datum)
+           new-lambda
-           (rename new-lambda lambda)
+           new-define
-           (rename new-define define)
+           new-app
-           (rename new-app #%app)
            (rename *make-keyword-procedure make-keyword-procedure)
            keyword-apply
-           procedure-keywords
+           procedure-keywords)
-           (rename define-struct* define-struct)
-           struct-field-index)
   
   ;; ----------------------------------------
   

collects/mzlib/big/lang.ss

@@ -0,0 +1,5 @@
+
+;; Temporary hack for building "scribblings" doc examples.
+
+(module lang (lib "lang.ss" "big")
+  (provide (all-from (lib "lang.ss" "big"))))

collects/scribble/basic.ss

@@ -1,5 +1,5 @@
 
-(module basic (lib "new-lambda.ss" "scribblings")
+(module basic (lib "lang.ss" "big")
   (require "decode.ss"
            "struct.ss"
            "config.ss"

collects/scribble/doclang.ss

@@ -1,11 +1,11 @@
 
-(module doclang (lib "new-lambda.ss" "scribblings") ; <--- temporary
+(module doclang (lib "lang.ss" "big")
   (require "struct.ss"
            "decode.ss"
            (lib "kw.ss"))
   (require-for-syntax (lib "kerncase.ss" "syntax"))
 
-  (provide (all-from-except (lib "new-lambda.ss" "scribblings") #%module-begin)
+  (provide (all-from-except (lib "lang.ss" "big") #%module-begin)
            (rename *module-begin #%module-begin))
 
   ;; Module wrapper ----------------------------------------

collects/scribble/eval.ss

@@ -1,5 +1,5 @@
 
-(module eval (lib "new-lambda.ss" "scribblings")
+(module eval (lib "lang.ss" "big")
   (require "manual.ss"
            "struct.ss"
            "scheme.ss"
@@ -171,7 +171,15 @@
 
   (define (do-plain-eval s catching-exns?)
     (parameterize ([current-namespace (current-int-namespace)])
-        (call-with-values (lambda () ((scribble-eval-handler) catching-exns? (strip-comments s))) list)))
+        (call-with-values (lambda () 
+                            ((scribble-eval-handler) 
+                             catching-exns? 
+                             (let ([s (strip-comments s)])
+                               (syntax-case s (module)
+                                 [(module . _rest)
+                                  (syntax-object->datum s)]
+                                 [_else s]))))
+          list)))
 
   (define-syntax interaction-eval
     (syntax-rules ()

collects/scribble/manual.ss

@@ -1,5 +1,5 @@
 
-(module manual (lib "new-lambda.ss" "scribblings")
+(module manual (lib "lang.ss" "big")
   (require "decode.ss"
            "struct.ss"
            "scheme.ss"
@@ -182,7 +182,7 @@
 
   (provide defproc defproc* defstruct defthing defform defform* defform/subs defform*/subs defform/none
            specform specform/subs 
-           specsubform specspecsubform specsubform/inline
+           specsubform specsubform/subs specspecsubform specsubform/inline
            schemegrammar schemegrammar*
            var svar void-const undefined-const)
 
@@ -294,6 +294,18 @@
        (*specsubform 'spec #f '(lit ...) (lambda () (schemeblock0 spec)) null null (lambda () (list desc ...)))]
       [(_ spec desc ...)
        (*specsubform 'spec #f null (lambda () (schemeblock0 spec)) null null (lambda () (list desc ...)))]))
+  (define-syntax specsubform/subs
+    (syntax-rules ()
+      [(_ #:literals (lit ...) spec ([non-term-id non-term-form ...] ...) desc ...)
+       (*specsubform 'spec #f '(lit ...) (lambda () (schemeblock0 spec)) 
+                     '((non-term-id non-term-form ...) ...)
+                     (list (list (lambda () (scheme non-term-id))
+                                 (lambda () (schemeblock0 non-term-form))
+                                 ...)
+                           ...)
+                     (lambda () (list desc ...)))]
+      [(_ spec subs desc ...)
+       (specsubform/subs #:literals () spec subs desc ...)]))
   (define-syntax specspecsubform
     (syntax-rules ()
       [(_ spec desc ...)

collects/scribblings/guide/guide-utils.ss

@@ -1,4 +1,4 @@
-(module guide-utils (lib "new-lambda.ss" "scribblings")
+(module guide-utils (lib "lang.ss" "big")
   (require (lib "manual.ss" "scribble")
            (lib "struct.ss" "scribble")
            (lib "decode.ss" "scribble")

collects/scribblings/guide/module-basics.scrbl

@@ -61,20 +61,5 @@ big
         (date->string (seconds->date (current-seconds))))
 ]
 
-Additional third-party libraries that are distributed through
+We discuss more forms of module reference later in
-@|PLaneT| can be imported using a @scheme[planet] form:
+@secref["guide:module-paths"].
-
-@schememod[
-big
-
-(require "cake.ss"
-         (planet "random.ss" ("schematics" "random.plt" 1 0)))
-
-(print-cake (inexact->exact
-             (round (* 30 (random-gaussian)))))
-]
-
-A @|PLaneT| reference starts like a @scheme[lib] reference, with a
-relative path, but the path is followed by information about the
-producer, archive, and version of the library. The specified archive
-is downloaded and installed on demand.

collects/scribblings/guide/module-paths.scrbl

@@ -0,0 +1,105 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@title[#:tag "guide:module-paths"]{Module Paths}
+
+A @deftech{module path} is a reference to a module, as used with
+@scheme[require] or as the @scheme[_initial-module-path] in a
+@scheme[module] form. It can be any of several forms:
+
+@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@specsubform[id]{
+
+A @tech{module path} that is just an identifier refers to a
+@scheme[module] declaration using the identifier. This form of module
+reference makes the most sense in a REPL, where a module can be
+declared independent of any file.
+
+@examples[
+(module m (lib "big/lang.ss")
+  (provide color)
+  (define color "blue"))
+(module n (lib "big/lang.ss")
+  (require m)
+  (printf "my favorite color is ~a\n" color))
+(require n)
+]}
+
+@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@specsubform[rel-string]{
+
+A string @tech{module path} is a relative path using Unix-style
+conventions: @litchar{/} is the path separator, @litchar{..} refers to
+the parent directory, and @litchar{.} refers to the same
+directory. The @scheme[rel-string] must not start or end with a path
+separator.
+
+The path is relative to the enclosing file, if any, or it is relative
+to the current directory. (More precisely, it is relative to the value
+of @scheme[(current-load-relative-directory)], which is set while
+loading a file.)
+
+@secref["guide:module-basics"] shows examples using relative paths.
+}
+
+@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@specsubform[#:literals (lib)
+             (lib rel-string)]{
+
+Like a plain-string @scheme[rel-path], but the elements of
+@scheme[rel-path] refer to @tech{collection}s and
+sub-@tech{collections}, instead of directories and sub-directories. A
+collection is represented by a directory in one of several
+installation-specific locations.
+
+The common initial import @scheme[(lib "big/lang.ss")] uses this form;
+it refers to the module whose source is the @file{lang.ss} file in the
+@file{big} collection, which is installed as part of PLT Scheme.
+
+@examples[
+(module m (lib "big/lang.ss")
+  (require (lib "mzlib/date.ss"))
+
+  (printf "Today is ~s\n" 
+          (date->string (seconds->date (current-seconds)))))
+(require m)
+]}
+
+@; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@specsubform/subs[#:literals (planet)
+                  (planet rel-string (user-string pkg-string vers ...))                  
+                  ([vers nat
+                         (nat nat)
+                         (= nat)
+                         (+ nat)
+                         (- nat)])]{
+
+Accesses a third-party library that is distributed through the
+@|PLaneT| server. The specified package is downloaded and installed on
+demand. A @|PLaneT| reference starts like a @scheme[lib] reference,
+with a relative path, but the path is followed by information about
+the producer, package, and version of the library.
+
+The version is expressed as a constraint on the acceptable version,
+where a version number is a sequence of non-negative integers, and the
+constraints determine the allowable values for each element in the
+sequence. If no constraint is provided for a particular component,
+then any version is allowed; in particular, omitting all
+@scheme[vers]es means that any version is acceptable. Specifying at
+least one @scheme[vers] is strongly recommended.
+
+For a version constraint, a plain @scheme[nat] is the same as
+@scheme[(+ nat)], which matches @scheme[nat] or higher for the
+corresponding component of the version number.  A @scheme[(_start-nat
+_end-nat)] matches any number in the range @scheme[_start-nat] to
+@scheme[_end-nat] inclusive. A @scheme[(= nat)] matches only exactly
+@scheme[nat]. A @scheme[(- nat)] matches @scheme[nat] or lower.
+
+@examples[
+(module m (lib "big/lang.ss")
+  (require (planet "random.ss" ("schematics" "random.plt" 1 0)))
+  (display (random-gaussian)))
+]
+}

collects/scribblings/guide/module-provide.scrbl

@@ -0,0 +1,7 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@title[#:tag "guide:module-provide"]{Module Exports: @scheme[provide]}
+

collects/scribblings/guide/module-require.scrbl

@@ -0,0 +1,7 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@title[#:tag "guide:module-require"]{Module Imports: @scheme[require]}
+

collects/scribblings/guide/modules.scrbl

@@ -16,3 +16,6 @@ more than a few seconds belongs in a module.
 
 @include-section["module-basics.scrbl"]
 @include-section["module-syntax.scrbl"]
+@include-section["module-paths.scrbl"]
+@include-section["module-require.scrbl"]
+@include-section["module-provide.scrbl"]

collects/scribblings/reference/reader-example.ss

@@ -1,5 +1,5 @@
 
-(module reader-example (lib "new-lambda.ss" "scribblings")
+(module reader-example (lib "lang.ss" "big")
   (require (lib "struct.ss" "scribble")
            (lib "decode.ss" "scribble")
            (lib "manual.ss" "scribble")

collects/scribblings/reference/syntax.scrbl

@@ -661,6 +661,18 @@ information} and source-location information attached to
 ]
 }
 
+@;------------------------------------------------------------------------
+@section[#:tag "mz:module"]{Modules: @scheme[module]}
+
+@defform[(module id require-spec form ...)]{
+
+Declares a module named by @scheme[id]. The @scheme[require-spec] must
+be as for @scheme[require] (see @secref["mz:require"]), and it
+supplies the initial bindings for the body @scheme[form]s. Each
+@scheme[form] is expanded in a @tech{module context}.
+
+}
+
 @;------------------------------------------------------------------------
 @section[#:tag "mz:require"]{Importing: @scheme[require], @scheme[require-for-syntax], @scheme[require-for-template]}
 
@@ -739,7 +751,7 @@ can trigger automatic loading of the module declaration:
  @scheme[rel-string] is always parsed as a Unix-format relative path:
  @litchar{/} is the path delimiter (multiple adjacent @litchar{/}s are
  treated as a single delimiter), @litchar{..} accesses the parent
- directory, and @litchar{.}  accesses the current directory. The path
+ directory, and @litchar{.} accesses the current directory. The path
  cannot be empty or contain a leading or trailing slash.}
 
  @specsubform[#:literals (lib) (lib rel-string)]{Like the plain