7.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 | Text Generation
7 | Low-Level Scribble API
8 | Running scribble
| Index

▼ | 7 | Low-Level Scribble API

7.1 | Scribble Layers
7.2 | @ Reader Internals
7.3 | Structures And Processing
7.4 | Renderers
7.5 | Decoding Text
7.6 | Document Language
7.7 | Document Reader
7.8 | Cross-Reference Utilities
7.9 | Tag Utilities
7.10 | Extending and Configuring Scribble Output

► | 7.6 | Document Language

7.6.1 | scribble/ doclang

On this page:

7.6.1`` scribble/ doclang

5.3.6
top ← prev up next →

#### 7.6`` Document Language

#lang scribble/doclang2

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, 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.

- #:exprs prepends an additional sequence of expressions to the beginning of the module’s body. 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

##### 7.6.1`` scribble/doclang

#lang scribble/doclang

The scribble/doclang language provides 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 ← prev up next →