8.12
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:
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))