scheme/splicing: updated reference for new splicing forms

svn: r14189

collects/scribblings/reference/splicing.scrbl

@@ -1,7 +1,8 @@
 #lang scribble/doc
 @(require "mz.ss"
           (for-label scheme/splicing
-                     scheme/stxparam))
+                     scheme/stxparam
+                     scheme/local))
 
 @(define splice-eval (make-base-eval))
 @interaction-eval[#:eval splice-eval (require scheme/splicing 
@@ -21,17 +22,16 @@
 @defidform[splicing-letrec-syntax]
 @defidform[splicing-let-syntaxes]
 @defidform[splicing-letrec-syntaxes]
+@defidform[splicing-letrec-syntaxes+values]
+@defidform[splicing-local]
 )]{
 
 Like @scheme[let], @scheme[letrec], @scheme[let-values],
 @scheme[letrec-values], @scheme[let-syntax], @scheme[letrec-syntax],
-@scheme[let-syntaxes], and @scheme[letrec-syntaxes], except that in a
+@scheme[let-syntaxes], @scheme[letrec-syntaxes],
+@scheme[letrec-syntaxes+values], and @scheme[local], except that in a
 definition context, the body forms are spliced into the enclosing
-definition context (in the same as as for @scheme[begin]). Also, for
-@scheme[splicing-letrec] and @scheme[splicing-letrec-values], a
-reference to a bound identifiers before is initialized is treated in
-the same way as definition in the enclosing context, which may be
-different than for @scheme[letrec] and @scheme[letrec-values].
+definition context (in the same way as for @scheme[begin]).
 
 @examples[
 #:eval splice-eval
@@ -39,7 +39,23 @@ different than for @scheme[letrec] and @scheme[letrec-values].
   (define o one))
 o
 one
-]}
+]
+
+When a splicing binding form occurs in a @tech{top-level context} or
+@tech{module context}, its local bindings are treated similarly to
+definitions. In particular, if a reference to one of the splicing
+form's bound variables is evaluated before the variable is
+initialized, an unbound variable error is raised, instead of the
+variable evaluating to the undefined value.  Also, syntax bindings are
+evaluated every time the module is @tech{visit}ed, instead of only
+once during compilation as in @scheme[let-syntax], etc.
+
+@examples[
+#:eval splice-eval
+(splicing-letrec ([x bad]
+                  [bad 1])
+  x)]
+}
 
 @defidform[splicing-syntax-parameterize]{