15 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:

@schemeblock[(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))

15.1 scribble/lp Language

#lang scribble/lp

The scribble/lp language provides core support for literate programming.

(chunk id form ...)

Introduces a chunk, binding id for use in other chunks. Normally, id starts with < and ends with >.

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.

15.2 scribble/lp-include Module

(require scribble/lp-include)

(lp-include filename)

Includes the source of filename as the typeset version of the literate program.