KludgeCode

is Ben Rudgers

A Literate Programming Example in Racket

This post is based on an extended example. The source files for it are available on Github

The weaved output from those source files can be seen here on the project page.

Racket’s scribble/lp language allows programs to be written in the Literate Programming Idiom. The documentation, however, is not very clear. This should not be particularly surprising because Racket’s documentation is sometimes lacking when it comes to features outside the core and when something between very basic material and detailed reference is needed.

The process of weaving is where scribble/lp is a bit confusing. Unlike documents in scribble/base or scribble/manual, documents written in scribble/lp cannot be directly rendered to HTML or LaTeX. This is why DrRacket does not provide “the easy button” when it sees a scribble/lp document because documents written using #lang scribble/lp use the file extension .rkt not .scrbl.

This means that a Racket Literate Program requires a second document written in either scribble/base or scribble/manual. It can be very simple:

#lang scribble/manual
@require[scribble/lp-include]
@title{Literate Programming Example}

The file for weaving has a file extension of .scrbl. To weave LPexample.rkt we run the scribble command on its corresponding .scrbl file. In this case: LPexample.scrbl.

A scribble/lp file contains both the code for tangling into a program or library and the text for weaving into a document. Like its parent scribble, scribble/lp allows direct input of text. The code to be tangled is delineated:

@chunk[<example_main>
       <example_requires>
       <example_exports>
       <example_body>]

Because this is the first @chunk it is treated as the main chunk. This is mentioned briefly near the bottom of the scribble/lp documentation. If you don’t want the first@chunkto serve as the main chunk, then use:

@chunk[<*>
   <example_requires>
   <example_exports>
   <example_body>]

It can be placed anywhere in the document to serve as the main chunk. However, I have tried it, and it really doesn’t add anything for clarity.

The two items which should be taken away because they effort to tease out of the documentation are:

  • Weaving requires a second file where a file with a .rkt file extension is referenced using lp-include.
  • Tangling treats the first chunk differently unless the <*> special name is used.