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.

The chunk and CHUNK content is discovered by first expanding the module as written. The content is collected into a new module, and then the original module content is placed into a doc submodule that is expanded (so that the content is effectively re-expanded). The doc submodule is declared with module*.

Added in version 1.8 of package scribble-lib.
Changed in version 1.17: Declared the doc submodule with module* instead of module.

When running the enclosing 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.

The forms are typeset using racketblock, so code:comment, etc., can be used to adjust the output. Those output-adjusting forms are stripped from each form for running the program.

Changed in version 1.17 of package scribble-lib: Strip code:comment, etc., for running.

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