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

 #lang scribble/lp2 package: scribble-lib
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.

Added in version 1.8 of package scribble-lib.


(chunk id form ...)

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

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.


(CHUNK id form ...)

Like chunk, but allows the use of unsyntax in the code part. If you want to use unsyntax to escape to Scribble, use UNSYNTAX.

5.2 scribble/lp Language

 #lang scribble/lp package: scribble-lib
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

 (require scribble/lp-include) package: scribble-lib
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.