►Scribble:   The Racket Documentation Tool
▼6 Low-Level Scribble API
►6.6 Document Language
On this page:
6.6.1 scribble/  doclang
6.1.1
  top  ← 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, 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

6.6.1 scribble/doclang

 #lang scribble/doclang package: scribble-lib
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 →