6.6 Document Language

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

▼ | 6 | Low-Level Scribble API

6.1 | Scribble Layers
6.2 | @ Reader Internals
6.3 | Structures And Processing
6.4 | Renderers
6.5 | Decoding Text
6.6 | Document Language
6.7 | Document Reader
6.8 | Cross-Reference Utilities
6.9 | Tag Utilities
6.10 | Blue Boxes Utilities
6.11 | Extending and Configuring Scribble Output

► | 6.6 | Document Language

6.6.1 | scribble/ doclang

On this page:

6.6.1`` scribble/ doclang

8.17
top contents ← prev up next →

#### 6.6`` Document Language🔗ℹ

#lang scribble/doclang2 | package: scribble-lib

The scribble/doclang2 language provides everything from racket/base, except that it replaces the #%module-begin form.
The scribble/doclang2 #%module-begin essentially packages the body of the module into a call to decode, binds the result to doc, and exports doc.
Any module-level form other than an expression (e.g., a require or define) remains at the top level, and the doc binding is put at the end of the module. As usual, a module-top-level begin slices into the module top level.

For example:

> #lang racket
> (module example scribble/doclang2
> "hello world, this is"
> " an example document")
> (require 'example)
> doc

The behavior of scribble/doclang2 can be customized by providing #:id, #:post-process, #:begin, and #:exprs arguments at the very beginning of the module.

- #:id names the top-level documentation binding. By default, this is doc.

- #:post-process processes the body of the module after decode. By default, this is values.

- #:begin prepends an additional sequence of expressions to the beginning of the module’s body outside of consideration for the document content. For example, the default configure-runtime submodule might be replaced using #:begin, because using #:exprs nests the replacement too deeply to work as an override. By default, this is the empty sequence ().

- #:exprs prepends an additional sequence of expressions to the beginning of the module’s body, but after #:begin. By default, this is the empty sequence ().

This example explicitly uses the defaults for all three keywords:

> #lang racket
> (module example scribble/doclang2
> #:id doc
> #:post-process values
> #:exprs ()
> "hello world, this is an example document")
> (require 'example)
> doc

The next toy example uses a different name for the documentation binding, and also adds an additional binding with a count of the parts in the document:

> #lang racket
> (module example scribble/doclang2
> #:id documentation
> #:post-process (lambda (decoded-doc)
> (set! number-of-parts (length (part-parts decoded-doc)))
> decoded-doc)
> #:exprs ((title "My first expression!"))
> (require scribble/core
> scribble/base)
> (define number-of-parts #f)
> (provide number-of-parts)
> (section "part 1")
> "hello world"
> (section "part 2")
> "this is another document")
> (require 'example)
> number-of-parts
> documentation

Changed in version 1.41 of package scribble-lib: Added #:begin.

##### 6.6.1`` scribble/doclang🔗ℹ

#lang scribble/doclang | package: scribble-lib

The scribble/doclang language provides most of the same functionality as scribble/doclang2, where the configuration options are positional and mandatory. The first three elements in the #%module-begin’s body must be the id, post-process, and exprs arguments.

Example:

> #lang racket
> (module* example scribble/doclang
> doc
> values
> ()
> (require scribble/base)
> (provide (all-defined-out))
> (define foo (para "hello again"))
> "hello world, this is an example document"
> (para "note the " (bold "structure")))
> (module+ main
> (require (submod ".." example))
> (printf "I see doc is: ~s\n\n" doc)
> (printf "I see foo is: ~s" foo))

top contents ← prev up next →