5 Document Modules

Like all PLT Scheme programs, Scribble documents are organized into modules, each in its own file. A #lang line starts a module, and most PLT Scheme modules start with #lang scheme or #lang scheme/base. A Scribble document normally starts with #lang scribble/doc to use a prose-oriented notation with @ syntax, but a Scribble document can be written in any notation and using any helper functions and syntax, as long as it exports a doc binding whose value is an instance of the Scribble part structure type. For example,

#lang scheme

(require scribble/decode)

(define doc (decode ’("Hello, world!")))

(provide doc)

implements in Scheme notation a Scribble document that contains only the text “Hello, world!”

Larger documents are typically split across modules/files along section boundaries. Subsections are incorporated into a larger section using the include-section form, which expands to a require to import the sub-section module and an expression that produces the doc part exported by the module. Since document inclusion corresponds to module importing, all of the usual PLT Scheme tools for building and executing modules apply to Scribble documents.

When a large document source is split into multiple modules, most of the modules need the same basic typesetting functions as well as the same “standard” bindings for examples. In Scribble, both sets of bindings can be packaged together; since for-label declarations build on the module system’s import mechanisms, they work with the module system’s re-exporting mechanisms. For example, the documentation for a library that builds on the scheme/base library might use this "common.ss" library:

#lang scheme/base

(require scribble/manual

(for-label htdp-langs/beginner))

(provide (all-from-out scribble/manual)

(for-label

(all-from-out htdp-langs/beginner)))

Then, each part of the document can be implemented as

#lang scribble/doc

@(require "common.ss")

....

instead of separately requiring scribble/manual and (for-label htdp-langs/beginner) in every file.

The doc binding that a Scribble module produces is a description of a document. Various tools, such as the scribble command-line program, can take this description of a document and render it to a specific format, such as LaTeX or HTML.