5 Literate Programming

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

• When the program is run, all of the chunk expressions are collected and stitched together into a program, and the rest of the module is discarded.

• When the program is provided to Scribble—or used through include-section in another Scribble document with a (submod ... doc) module path—the entire contents of the module are treated like an ordinary Scribble document, where chunks are typeset in a manner similar to codeblock.

For example, consider this program:

#lang scribble/lp2

@(require scribble/manual)

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 rendered as a Scribble document, the output 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/lp2 Language

More precisely, a module in scribble/lp2 has its racket/base-like content in a doc submodule, which is recognized by tools such as raco scribble. The content of the chunk and CHUNK forms is stitched together as the immediate content of the module.

Added in version 1.8 of package scribble-lib.

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 Language

The scribble/lp language effectively binds only chunk and CHUNK, while all other bindings for documentation are taken from the context where lp-include is used.

5.3 scribble/lp-include Module