From a7ae3b807ea1c8991e7101393efe23fe832ce03d Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 30 May 2011 08:43:03 -0600
Subject: [PATCH] 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                 |  4 +-
 collects/scribblings/reference/syntax.scrbl | 72 +++++++++++++--------
 2 files changed, 48 insertions(+), 28 deletions(-)

diff --git a/collects/racket/require.rkt b/collects/racket/require.rkt
index c17c08697e..51d8f51c63 100644
--- a/collects/racket/require.rkt
+++ b/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)))]))
 
 
diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl
index 86509aed8c..476a5c3390 100644
--- a/collects/scribblings/reference/syntax.scrbl
+++ b/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 ...) ...)
-         #:contracts ([dir module-path?])]{
+@defform/subs[(multi-in subs ...+)
+              ([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:
-@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")]
+Examples:
 
-It is also possible to require to require files with identical names
-located in different directories:
-@racketblock[(require (multi-in ("math" "matrix") "utils.rkt"))]
-which is equivalent to:
-@racketblock[(require "math/utils.rkt" "matrix/utils.rkt")]
-or even:
-@racketblock[(require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt")))]
-which is equivalent to:
-@racketblock[(require "math/utils.rkt" "math/helpers.rkt" "matrix/utils.rkt" "matrix/helpers.rkt")]
-
-Deeper nesting is also possible:
-@racketblock[(require (multi-in "math" "matrix" "utils.rkt"))]
-is equivalent to:
-@racketblock[(require "math/matrix/utils.rkt")]
-}
+@subeqivs[
+[(require (multi-in racket (dict @#,schemeidfont{list})))
+ (require racket/dict racket/list)]
+[(require (multi-in "math" "matrix" "utils.rkt"))
+ (require "math/matrix/utils.rkt")]
+[(require (multi-in "utils" ("math.rkt" "matrix.rkt")))
+ (require "utils/math.rkt" "utils/matrix.rkt")]
+[(require (multi-in ("math" "matrix") "utils.rkt"))
+ (require "math/utils.rkt" "matrix/utils.rkt")]
+[(require (multi-in ("math" "matrix") ("utils.rkt" "helpers.rkt")))
+ (require "math/utils.rkt" "math/helpers.rkt" 
+          "matrix/utils.rkt" "matrix/helpers.rkt")]
+]}
 
 @; --------------------