fix overview documentation for scribble/eval

scribble-doc/scribblings/scribble/how-to.scrbl

@@ -301,38 +301,39 @@ on forms to document Racket bindings.
 @; ----------------------------------------
 @section{Showing Racket Examples}
 
-The @racket[examples] form from @racket[scribble/eval]
+The @racket[examples] form from @racket[scribble/eval] helps you
-helps you generate examples in your documentation.
+generate examples in your documentation. To use @racket[examples], the
-
+procedures to document must be suitable for use at documentation time,
-To use @racket[examples], the procedures to document must be suitable
+but the @racket[examples] form does not use any binding introduced
-for use at documentation time; in fact, @racket[examples] uses
+into the document source by @racket[require]. Instead, create a new
-bindings introduced into the document source by
+evaluator with its own namespace using @racket[make-base-eval], and
-@racket[require]. Thus, to generate examples using @racket[my-helper]
+use @racket[interaction-eval] to require @filepath{helper.rkt} in that
-from the previous section, @filepath{helper.rkt} must be imported both
+evaluator. Finally, supply the same evaluator to @racket[examples]:
-via @racket[(require (for-label ....))] and @racket[require]:
 
 @codeblock|{
   #lang scribble/manual
-  @(require scribble/eval    ; <--- added
+  @(require scribble/eval
-            "helper.rkt"     ; <--- added
             (for-label racket
                        "helper.rkt"))
 
   @title{My Library}
 
-  @defmodule[my-lib/helper]{The @racketmodname[my-lib/helper]
+  @defmodule[my-lib/helper]
-  module---now with extra cows!}
 
   @defproc[(my-helper [lst list?])
-           (listof (not/c (one-of/c 'cow)))]{
+           (listof
-
+            (not/c (one-of/c 'cow)))]{
    Replaces each @racket['cow] in @racket[lst] with
    @racket['aardvark].
 
+   @(define helper-eval (make-base-eval))
+   @interaction-eval[#:eval helper-eval
+                     (require "helper.rkt")]
    @examples[
-     (my-helper '())
+       #:eval helper-eval
-     (my-helper '(cows such remarkable cows))
+       (my-helper '())
-   ]}
+       (my-helper '(cows such remarkable cows))
+     ]}
 }|
 
 @;----------------------------------------