[racket] help with scribble/manual

Thank you, Danny: right both times.

On Mon, May 21, 2012 at 05:00:08PM -0400, Danny Yoo wrote:
> On Mon, May 21, 2012 at 3:36 PM, Danny Heap <heap at cs.toronto.edu> wrote:
> > I am trying to include a small manual page with my (also small)
> > PLaneT module.  Scribble doesn't see the bindings for the functions
> > introduced in my module, judging by the warnings generated by 'raco
> > setup...' --- errors which are also generated when the module is
> > required from the PLanet repository.
> 
> Hmmm... I'm looking at the error messages, and I think they're
> referring to the red-underlined items shown in:
> 
>     http://planet.racket-lang.org/package-source/dsheap/color-utils.plt/1/1/planet-docs/manual/index.html
> 
> 
> The red underlines are legitimate, as they refer to things that you've
> defined in dsheap/color-utils/main.rkt that have not been documented.
> 
> 
> > I was also unable to use @examples[], presumably for the same reason.
> 
> I think this is a separate reason.  If I remember correctly, the
> "examples" form uses some dynamic evaluation, and you may need to give
> it a customized evaluator that knows your library.
> 
> Checking...
> 
>     http://docs.racket-lang.org/scribble/eval.html#(form._((lib._scribble/eval..rkt)._examples))
> 
> ... yes, I think you may need to provide an additional argument to the
> examples that specifies the #:eval argument.
> 
> For example, say that we have a foo-utils.rkt file in my PLanet package:
> 
> ########################
> $ cat foo-utils.rkt
> #lang racket/base
> (define (foo x) x)
> ########################
> 
> Then we can refer to it in our Scribble examples like this:
> 
> 
> 
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> #lang scribble/base
> 
> @(require scribble/eval planet/version)
> 
> @(define my-eval (make-base-eval))
> @(my-eval `(require (planet ,(this-package-version-symbol foo-utils))))
> 
> @examples[#:eval my-eval
> (foo 42)]
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> 
> 
> I hope this helps!

-- 
Danny Heap
BA4270			416-978-5899
heap at cs.utoronto.ca	http://www.cs.utoronto.ca/~heap