I guess this documentation got lost at some point during the various branch

moves, so add it back.

svn: r12888

collects/mzlib/scribblings/contract.scrbl

@@ -110,24 +110,4 @@ provided by @scheme[provide/contract], because
 @scheme[define/contract] cannot detect the name of the definition
 where the reference to the defined variable occurs. Instead, it uses
 the source location of the reference to the variable as the name of
-that definition.
+that definition.}
-
-@examples[#:eval (parameterize ([sandbox-output 'string]
-                                [sandbox-error-output 'string]
-                                [sandbox-eval-limits #f])
-                   (make-evaluator 'mzscheme))
-                 (require mzlib/contract)
-                 (define/contract f
-                   (-> number? number?)
-                   (lambda (x) (+ x 1)))
-                 (define/contract g
-                   (-> number? number?)
-                   (lambda (x) (f #t)))
-                 (define/contract i
-                   (-> number? number?)
-                   (lambda (x)
-                     (if (number? x) (i #t) 0)))
-                 (f 4)
-                 (f #t)
-                 (g 4)
-                 (i 3)]}

collects/scribblings/reference/contracts.scrbl

@@ -661,23 +661,36 @@ contract on the fields that the sub-struct shares with its parent are
 only used in the contract for the sub-struct's maker, and the selector
 or mutators for the super-struct are not provided.}
 
-@defform[(define/contract id contract-expr init-value-expr)]{
+@defform/subs[
+ (with-contract blame-id (wc-export ...) body ...+)
+ ([wc-export
+   id
+   (id contract-expr)])]{
+Generates a local contract boundary.  The @scheme[contract-expr]
+form cannot appear in expression position.  The @scheme[body] of the
+form allows definition/expression interleaving like a @scheme[module]
+body.  Names bound within the @scheme[body] must be exported to be
+accessible from outside the @scheme[with-contract] form.  Such
+@scheme[id]s can either be paired with a @scheme[contract-expr] or
+exported without a contract.
 
-Attaches the contract @scheme[contract-expr] to
+The @scheme[blame-id] is used for the positive positions of
-@scheme[init-value-expr] and binds that to @scheme[id].
+contracts paired with exported @scheme[id]s.  Contracts broken
+within the @scheme[with-contract] @scheme[body] will use the
+@scheme[blame-id] for their negative position.}
+
+@defform*[[(define/contract id contract-expr init-value-expr)
+ (define/contract (head args) contract-expr body ...+)]]{
+Works like @scheme[define], except that the contract
+@scheme[contract-expr] is attached to the bound value.
 
 The @scheme[define/contract] form treats individual definitions as
 units of blame. The definition itself is responsible for positive
 (co-variant) positions of the contract and each reference to
 @scheme[id] (including those in the initial value expression) must
-meet the negative positions of the contract.
+meet the negative positions of the contract.  It is equivalent to
-
+wrapping a single @scheme[define] with a @scheme[with-contract] form
-Error messages with @scheme[define/contract] are not as clear as those
+that pairs the @scheme[contract-expr] with the bound identifier.}
-provided by @scheme[provide/contract], because
-@scheme[define/contract] cannot detect the name of the definition
-where the reference to the defined variable occurs. Instead, it uses
-the source location of the reference to the variable as the name of
-that definition.}
 
 @defform*[[(contract contract-expr to-protect-expr
                      positive-blame-expr negative-blame-expr)