On this page:
5.1 scribble/  lp2 Language
5.2 scribble/  lp Language
5.3 scribble/  lp-include Module

5 Literate Programming

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

For example, consider this program:

#lang scribble/lp2
@(require scribble/manual)
Literate programs have chunks of code, like this one:
       (define (f x)
and this one:
       (* 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)

and this one:

(* x x)

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

(define (f x)
  (* x x))

5.1 scribble/lp2 Language

The scribble/lp language provides core support for literate programming. It is read like a scribble/base program, but its bindings extend racket/base with two forms: chunk and CHUNK.

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.


(chunk id form ...)

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

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.


(CHUNK id form ...)

Like chunk, but typesets with RACKETBLOCK, so unsyntax can be used normally in each form. To escape, use UNSYNTAX.

5.2 scribble/lp Language

Programs written using the older scribble/lp language are similar to scribble/lp2 programs, except that the module cannot be provided directly to Scribble. Instead, the document content must be extracted using lp-include.

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

The scribble/lp-include library is normally used within a Scribble document—that is, a module that starts with something like #lang (racketmodname scribble/base) or #lang (racketmodname scribble/manual), instead of #lang (racketmodname racket).


(lp-include filename)

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