doclang.scrbl (3204B)
1 #lang scribble/manual 2 @(require "utils.rkt") 3 4 @title[#:tag "doclang"]{Document Language} 5 6 @defmodulelang[scribble/doclang2]{The @racketmodname[scribble/doclang2] 7 language provides everything from @racket[racket/base], except that it 8 replaces the @racket[#%module-begin] form. 9 10 The @racketmodname[scribble/doclang2] @racket[#%module-begin] 11 essentially packages the body of the module into a call to 12 @racket[decode], binds the result to @racket[doc], and exports 13 @racket[doc]. 14 15 Any module-level form other than an expression (e.g., a 16 @racket[require] or @racket[define]) remains at the top level, and 17 the @racket[doc] binding is put at the end of the module. As usual, a 18 module-top-level @racket[begin] slices into the module top level. 19 20 For example: 21 @codeblock|{ 22 #lang racket 23 (module example scribble/doclang2 24 "hello world, this is" 25 " an example document") 26 (require 'example) 27 doc 28 }| 29 30 The behavior of @racketmodname[scribble/doclang2] can be customized by 31 providing @racket[#:id], @racket[#:post-process], and @racket[#:exprs] 32 arguments at the very beginning of the module. 33 34 @itemize[ 35 36 @item{@racket[#:id] names the top-level documentation binding. By default, this 37 is @racket[doc].} 38 39 @item{@racket[#:post-process] processes the body of the module after 40 @racket[decode]. By default, this is @racket[values].} 41 42 @item{@racket[#:exprs] prepends an additional sequence of expressions to the 43 beginning of the module's body. By default, this is the empty sequence 44 @racket[()].} 45 46 ] 47 48 This example explicitly uses the defaults for all three keywords: 49 50 @codeblock|{ 51 #lang racket 52 (module example scribble/doclang2 53 #:id doc 54 #:post-process values 55 #:exprs () 56 "hello world, this is an example document") 57 (require 'example) 58 doc 59 }| 60 61 62 The next toy example uses a different name for the documentation binding, and 63 also adds an additional binding with a count of the parts in the document: 64 65 @codeblock|{ 66 #lang racket 67 (module example scribble/doclang2 68 #:id documentation 69 #:post-process (lambda (decoded-doc) 70 (set! number-of-parts (length (part-parts decoded-doc))) 71 decoded-doc) 72 #:exprs ((title "My first expression!")) 73 74 (require scribble/core 75 scribble/base) 76 77 (define number-of-parts #f) 78 (provide number-of-parts) 79 (section "part 1") 80 "hello world" 81 (section "part 2") 82 "this is another document") 83 84 (require 'example) 85 number-of-parts 86 documentation 87 }| 88 } 89 90 91 92 @section{@racketmodname[scribble/doclang]} 93 @defmodulelang[scribble/doclang]{The @racketmodname[scribble/doclang] language 94 provides the same functionality as @racketmodname[scribble/doclang2], where the 95 configuration options are positional and mandatory. The first three elements 96 in the @racket[#%module-begin]'s body must be the @racket[id], 97 @racket[post-process], and @racket[exprs] arguments. 98 99 Example: 100 @codeblock|{ 101 #lang racket 102 (module* example scribble/doclang 103 doc 104 values 105 () 106 (require scribble/base) 107 (provide (all-defined-out)) 108 (define foo (para "hello again")) 109 "hello world, this is an example document" 110 (para "note the " (bold "structure"))) 111 112 (module+ main 113 (require (submod ".." example)) 114 (printf "I see doc is: ~s\n\n" doc) 115 (printf "I see foo is: ~s" foo)) 116 }| 117 }