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 lang/htdp-beginner))

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


           (all-from-out lang/htdp-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 lang/htdp-beginner) in every file.