5 Literate Programming

Programs written using scribble/lp are simultaneously two things: a program and a document describing the program.

Programs in scribble/lp are viewed in two different ways, either by running the program directly or by including it with lp-include. When running the program, all of the chunk expressions are collected and stitched together into a program, and the rest of the module is discarded. When using lp-include, the entire contents of the module are preserved and are treated like an ordinary Scribble document, where chunks are typeset in a manner similar to codeblock.

For example, consider this program:

#lang scribble/lp

Literate programs have chunks of code, like this one:

@chunk[<f>

(define (f x)

<fs-body>)]

and this one:

@chunk[<fs-body>

(* x x)]

that, when assembled, produce a complete program, in this case:

@racketblock[(define (f x)

(* x x))]

When this file is required in the normal manner, it defines a function f that squares its argument, and the documentation is ignored. When it is included with lp-include, it looks like this:

Literate programs have chunks of code, like this one:

<f> ::=

(define (f x)

<fs-body>)

and this one:

<fs-body> ::=

(* x x)

that, when assembled, produce a complete program, in this case:

(define (f x)

(* x x))

5.1 scribble/lp Language

When running a scribble program only the code inside the chunks is run; the rest is ignored.

If id is <*>, then this chunk is used as the main chunk in the file. If <*> is never used, then the first chunk in the file is treated as the main chunk. If some chunk is not referenced from the main chunk (possibly indirectly via other chunks that the main chunk references), then it is not included in the program and thus is not run.

5.2 scribble/lp-include Module