[racket] two scribble/srcdoc questions: using scribble/eval examples and in-file provide-extracted

At Fri, 18 May 2012 13:47:54 +0100, Uri Zarfaty wrote:
> I've been trying to use scribble/srcdoc for in-source documentation, and
> have a couple of hopefully straightforward questions.
> 
> 1) Is it possible to use scribble/eval examples in proc-doc/names? Trying
> this naively results in an undefined identifier error, presumably since the
> function binding was not introduced to the source file that defines it
> using a require.

When you use `scribble/eval', the default sandboxed evaluator has only
`racket/base' bindings. Use `interaction-eval' to require other
modules --- even if it's the enclosing module.

Matthias's code does that in `define-module-local-eval'. See "ex.rkt"
below for a more primitive example.

> 2) Is it possible to use include-previously-extracted without requiring an
> additional file for provide-extracted (e.g. by having the provide-extracted
> in either the source or documentation file)?

You can use a submodule for this, but only with the repair that I've
just pushed to the `scribble' languages to recognize `module' and
`module*' submodule forms and not treat them as a expressions (i.e.,
treat the them same as `require's or `define's).

See "ex.scrbl" below for an example.

----------------------------------------
ex.rkt:
----------------------------------------
#lang at-exp racket/base
(require scribble/srcdoc
         racket/contract
         (for-doc racket/base
                  scribble/manual
                  scribble/eval
                  (for-label racket/base)))

(define (negate x) (- x))

(provide
 (proc-doc/names negate
                 (-> number? number?)
                 (x)
                 @{Negates @racket[x].

                   @(let ([e (make-base-eval)])
                     (interaction-eval #:eval e (require "ex.rkt"))
                     @examples[
                      #:eval e
                      (negate 7)
                     ])}))

----------------------------------------
ex.scrbl:
----------------------------------------
#lang scribble/manual
@(require scribble/extract)

@(module extracted racket/base
   (require scribble/extract)
   (provide-extracted "ex.rkt"))

@(include-previously-extracted (submod "." extracted) #rx"negate")