fix docs for `multi-in'

because the previous documentation didn't actually define the form;
 the examples were good, but epecting a reader to infer meaning
 from examples wasn't good enough. The use of a `module-path?' contract
 in the old docs wasn't appropriate; contracts apply to values, while
 grammar productions should be used to document syntax constraints.
 Also, `module-path?' was too permissive (only literal strings and
 identifiers are actually allowed), while the actual syntax allows
 either a single path or a sequence.

collects/racket/require.rkt

@@ -126,9 +126,9 @@
 (provide multi-in)
 (define-require-syntax (multi-in stx)
   (syntax-case stx ()
-    [(_ elem ...)
+    [(_ elem0 elem ...)
      (quasisyntax/loc stx
-       (combine-in #,@(datum->syntax stx (multi (syntax->datum #'(elem ...)))
+       (combine-in #,@(datum->syntax stx (multi (syntax->datum #'(elem0 elem ...)))
                                      stx stx stx)))]))
 
 

collects/scribblings/reference/syntax.scrbl

@@ -1,6 +1,7 @@
 #lang scribble/doc
 @(require "mz.ss"
           scribble/bnf
+          scribble/core
           (for-label (only-in racket/require-transform
                               make-require-transformer)
                      racket/require-syntax
@@ -25,6 +26,25 @@
 @(define unquote-id (racket unquote))
 @(define unquote-splicing-id (racket unquote-splicing))
 
+@(define-syntax-rule (equiv-to-block b)
+    (tabular #:style (make-style #f (list (make-table-columns
+                                           (list (make-style #f '(baseline))
+                                                 (make-style #f '(baseline))))))
+             (list (list (para (hspace 2) " is equivalent to" (hspace 1))
+                         (racketblock0 b)))))
+
+@(define-syntax-rule (subeqivs [a0 b0] [a b] ...)
+   (tabular (map
+             list
+             (apply
+              append
+              (list (list (racketblock a0)
+                          (equiv-to-block b0))
+                    (list (para 'nbsp)
+                          (racketblock a)
+                          (equiv-to-block b))
+                    ...)))))
+
 @title[#:tag "syntax" #:style 'toc]{Syntactic Forms}
 
 This section describes the core syntax forms that appear in a fully
@@ -1161,35 +1181,35 @@ but then sub-directories that are called
 @filepath{utils} override the one in the project's root.
 In other words, the previous method requires only a single unique name.}
 
-@defform[(multi-in (dir ...) ...)
+@defform/subs[(multi-in subs ...+)
-         #:contracts ([dir module-path?])]{
+              ([subs sub-path
+                     (sub-path ...)]
+               [sub-path rel-string
+                         id])]{
+
 Specifies multiple files to be required from a hierarchy of
-directories or collects.
+directories or collections. The set of required module paths is computed
+as the cartesian product of the @racket[subs] groups, where each
+@racket[sub-path] is combined with other @racket[sub-path]s in order
+using a @litchar{/} separator. A @racket[sub-path] as a @racket[subs]
+is equivalent to @racket[(sub-path)]. All @racket[sub-path]s in a given
+@racket[multi-in] form must be either strings or identifiers.
 
-For example:
+Examples:
-@racketblock[(require (multi-in racket (list dict)))]
-is equivalent to:
-@racketblock[(require racket/list racket/dict)]
-Similarly:
-@racketblock[(require (multi-in "utils" ("math.rkt" "matrix.rkt")))]
-is equivalent to:
-@racketblock[(require "utils/math.rkt" "utils/matrix.rkt")]
 
-It is also possible to require to require files with identical names
+@subeqivs[
-located in different directories:
+[(require (multi-in racket (dict @#,schemeidfont{list})))
-@racketblock[(require (multi-in ("math" "matrix") "utils.rkt"))]
+ (require racket/dict racket/list)]
-which is equivalent to:
+[(require (multi-in "math" "matrix" "utils.rkt"))
-@racketblock[(require "math/utils.rkt" "matrix/utils.rkt")]
+ (require "math/matrix/utils.rkt")]
-or even:
+[(require (multi-in "utils" ("math.rkt" "matrix.rkt")))
-@racketblock[(require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt")))]
+ (require "utils/math.rkt" "utils/matrix.rkt")]
-which is equivalent to:
+[(require (multi-in ("math" "matrix") "utils.rkt"))
-@racketblock[(require "math/utils.rkt" "math/helpers.rkt" "matrix/utils.rkt" "matrix/helpers.rkt")]
+ (require "math/utils.rkt" "matrix/utils.rkt")]
-
+[(require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt")))
-Deeper nesting is also possible:
+ (require "math/utils.rkt" "math/helpers.rkt" 
-@racketblock[(require (multi-in "math" "matrix" "utils.rkt"))]
+          "matrix/utils.rkt" "matrix/helpers.rkt")]
-is equivalent to:
+]}
-@racketblock[(require "math/matrix/utils.rkt")]
-}
 
 @; --------------------