[racket] Cannot reproduce example in "Getting Started with Documentation"

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Mon Dec 29 18:18:26 EST 2014

At Mon, 29 Dec 2014 22:56:36 +0000, Stuart McLuckie wrote:
> I can't to reproduce the Scribble example  in section 4.1.4 of "Getting 
> Started with Documentation".  The procedure 'my-helper' is undefined in 
> the html output:
> "....
>      Examples:
> >(my-helper'())
>      my-helper: undefined;
> cannot reference undefined identifier
>      >(my-helper'(cowssuchremarkablecows))
>      my-helper: undefined;
> cannot reference undefined identifier ..."
> 
> I put 'manual.scrbl', 'helper.rkt' in a local collection directory 
> '~/.racket/6.1.1/collects/my-lib/' and ran
> 'raco setup -l my-lib' to produce index.html in my-lib/doc/manual.
> 
> I've attached the two files. Can anyone please help?

That prose and example in section 4.1.5 are wrong, and they must have
been wrong for a long time.

Below is a corrected example. The `examples` form does not obtain any
bindings from the enclosing module, so a direct `require` of
"helper.rkt" is not needed or useful. Instead, an evaluator is created
with its own namespace using `make-base-eval`. Then, "helper.rkt"
should be `require`d in that evaluator using `interaction-eval`, and
the same evaluator should used with `examples`.

I'll fix the docs, of course.

----------------------------------------

#lang scribble/manual
@(require scribble/eval
          (for-label racket
                     "helper.rkt"))

@(define helper-eval (make-base-eval))
@interaction-eval[#:eval helper-eval
                  (require "helper.rkt")]

@title{My Library}

@defmodule[my-lib/helper]

@defproc[(my-helper [lst list?])
         (listof
          (not/c (one-of/c 'cow)))]{
 Replaces each @racket['cow] in @racket[lst] with
 @racket['aardvark].
 
 @examples[
     #:eval helper-eval
     (my-helper '())
     (my-helper '(cows such remarkable cows))
   ]}

Posted on the users mailing list.