[racket] help with scribble/manual

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!