Brush: Literate Programming Without Tangling (original) (raw)

8.15

Brush is a language for doing semi-literate programming in the style of Literate Haskell, rather than full Knuth-style literate programming. For that, see scribble/lp2.

A Brush module is written in Scribble, with program fragments written in any Racket language that can be typeset usingracketblock. In practice, this is almost any language with an S-expression syntax.

1 Reference🔗ℹ

The brush language.

The first form in a brush module may be an option list of the form(#:program-lang LANG). In this case, LANG is used as the language for program fragments.

The resulting module has two submodules: doc, which contains the Scribble document, and program, which contains the program. All exports of program are then re-provided by the containing module. This means that, when requiring a Brush document as Racket, it can be required directly, while including it as a section in a Scribble document involves including the docsubmodule.

(program form ...)
(program #:hide form ...)

Introduces a program fragment that is part of the resulting Racket module. The forms are typeset using racketblock.

If #:hide is specified, then the Racket fragment is included in the Racket module, but not in the Scribble output.

Like chunk from scribble/lp2, it is possible to escape from program using unsyntaxwithout affecting the resulting Racket program. Unlikechunk, program fragments are not named. They occur in the resulting Racket module in the order in which they are written.

(PROGRAM form ...)
(PROGRAM #:hide form ...)

Just like program, except UNSYNTAX is used to escape to Scribble.