10.1.2 Module Structure🔗ℹ

The reader for #lang ricoeur/tei/spec-lang is a variant of the Scribble reader that uses ƒ as its command character (like the default for _-exp). The reader begins in text mode: the syntactic “outer” layer of a #lang ricoeur/tei/spec-lang module is the documentation-time phase, even though, in expanded form, the enclosing module contains the runtime phase, while the documentation-time code is placed in an implicit doc submodule (declared with module*).

The init-whitespace forms are literal strings consisting exclusively of whitespace: there are ignored, though they are permitted for convienience with the text-mode reader.

The spec-name-declaration (which may be empty) controls the binding of the module’s elements specification transformer.

The spec-module-body forms are the body of the module. They have meaning both at runtime and at documentation-time.

10.1.2.1 The spec-name-declaration🔗ℹ

An atomic-spec-name-declaration is the basic form of spec-name-declaration: it defines spec-id as an elements specification transformer that encapsulates the contract and tei element struct type information from all of the uses of define-element or define-elements-together in the module.

A compound-spec-name-declaration is a convienient way to combine elements specification transformers from multiple modules. In that case, the current module’s information is bound to local-spec-id (primarily for error-reporting purposes), then spec-id is defined as an elements specification transformer that combines local-spec-id with all of the extended-spec-ids, which must be bount to elements specification transformers (probably imported from other modules).

See also define-combined-elements-specification for a more general means of combining elements specification transformers. The expansion of a compound-spec-name-declaration is implemented using define-combined-elements-specification.

10.1.2.2 The spec-module-body Forms🔗ℹ

The spec-module-body forms are first partially expanded in the documentation-time environment to reveal uses of begin-for-runtime and related forms, prominently including define-element and define-elements-together. The details of expansion to these forms remain under development and are subject to change.

The documentation-time code from the spec-module-body forms is placed in an implicit doc submodule (declared with module*).

The body sub-forms are at the runtime phase. They are spliced into the module level of the enclosing runtime phase module, somewhat like (begin body ...).

As an expression in the documentation-time phase, a begin-for-runtime form evaluates to #<void>, and the body sub-forms are ignored.

A begin-for-runtime form may only appear at the module level or in an element definition prose context (see define-element and define-elements-together). Restrictions on the nesting of element definition prose contexts keeps the order of the synthesized runtime phase clear from the program’s source.

If a doctime-expr is given, it must be an expression at the documentation-time phase, and the value of the begin-for-runtime/derived expression at the documentation-time phase is the value of the doctime-expr expression. If no doctime-expr is given, the default is #<void>, as with begin-for-runtime.

The doctime-expr mechanism is useful because, as with begin-for-runtime, begin-for-runtime/derived may only be used at at the module level or in an element definition prose context. Because element definition prose contexts are expression contexts, macros that expand to begin-for-runtime/derived cannot easily use more general methods to expand to something other than #<void> at the documentation-time phase.

10.1.2.3 Runtime Submodules🔗ℹ