Usage of code-examples in scribble

Questions & Answers
1

Hello everyone,

I have been recently working on SICP with Chez Scheme. I was using Emacs with org-mode to organize my solutions using literate programming, and then exporting them to HTML. Then I read about Racket, DrRacket, scribble, which I think is really awesome software. So my goal is to have a similar workflow in DrRacket + scribble, as that of Emacs + org-mode.

Here is a simple example that doesn't quite work:

#lang scribble/base

@(require scribble/manual
          scribble-code-examples)

A minimal example, I would like to use the A procedure in the code-example
block.
 
@racketblock[
   (define (A x y)
    (cond ((= y 0) 0)
          ((= x 0) (* 2 y))
          ((= y 1) 2)
          (else (A (- x 1) (A x (- y 1))))))
 ]

@code-examples[#:lang "sicp" #:context #'here]|{
  (A 1 10)
}|

which gives the error:

racket-8.7/share/racket/collects/racket/private/more-scheme.rkt:148:2: A: undefined; cannot reference an identifier before its definition

How can this code be fixed?

Also, is there any way in which I could evaluate a particular (or several) S-expression when writing a scribble document? For instance, testing the A procedure without creating a new file or tab?

Thanks in advance.

1 Like
2

Sounds like you are attempting to something similar to what Jay did in his blog posts.

Here is an example:
2013-06-03: Towers of Hanoi in Racket

And here is the source used to produce that blog post:
jeapostrophe.github.com/2013-06-03-hanoi.rkt at source · jeapostrophe/jeapostrophe.github.com · GitHub

It uses scribble/lp where lp is short for literate programming.

1 Like
3

This works for me:

#lang scribble/manual

@(require scribble/examples)

A minimal example, I would like to use the A procedure in the example block.

@(define my-eval
   (make-base-eval #:lang 'sicp))

@examples[#:eval my-eval #:hidden
  (define (A x y)
    (cond ((= y 0) 0)
          ((= x 0) (* 2 y))
          ((= y 1) 2)
          (else (A (- x 1) (A x (- y 1))))))
]

@examples[#:eval my-eval
  (A 1 10)
  inc ;; test that sicp is loaded
]

Roughly, for the evaluations that you want them to be displayed, use (examples #:eval <evaluator> <code> ...). For the evaluations that you don’t want them to be displayed, use (examples #:eval <evaluator> #:hidden <code> ...). The evaluator specified in these examples should be the same so that the state gets carried over.

Note that I use scribble/examples, which is from core Scribble. I don’t think you need to use scribble-code-examples, as that package's intended use-case is for showing non S-exp syntax examples.

2 Likes
4

Thanks a lot for your reply! That is what I wanted. Quick question, how can I remove (or modify) the "Example:" header that @example generates?

5

Specify #:label #f after #:eval <evaluator>. The full documentation of examples is here.

1 Like