5 Literate Programming

▼ |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 5 | Literate Programming

5.1 | scribble/ lp2 Language
5.2 | scribble/ lp Language
5.3 | scribble/ lp-include Module

On this page:

<f>
<fs-body>
5.1`` scribble/ lp2 Language
chunk
CHUNK
5.2`` scribble/ lp Language
5.3`` scribble/ lp-include Module
lp-include

top ← prev up next →

### 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

#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.

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*.

To include a scribble/lp2 document named "file.scrbl" into another Scribble document, import the doc submodule:

> @include-section[(submod "file.scrbl" doc)]

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

> syntax (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.

> syntax (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

#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 scribble/base or #lang scribble/manual, instead of #lang racket.

> syntax (lp-include filename)

Includes the source of filename as the typeset version of the literate program.
top ← prev up next →