layers.scrbl (8898B)
1 #lang scribble/doc 2 @(require scribble/manual scribble/bnf "utils.rkt") 3 4 @title[#:tag "layers"]{Scribble Layers} 5 6 Scribble is made of independently usable parts. For example, the 7 Scribble reader can be used in any situation that requires lots of 8 free-form text. You can also skip Scribble's special reader support, 9 and instead use the document-generation structure directly. 10 11 @; ---------------------------------------------------------------------- 12 13 @section{Typical Composition} 14 15 A Scribble document normally starts 16 17 @racketmod[ 18 scribble/manual 19 ] 20 21 but it could also start 22 23 @racketmod[ 24 scribble/base 25 ] 26 27 or 28 29 @racketmod[ 30 scribble/doc 31 ] 32 33 The last one introduces the smallest number of typesetting bindings in 34 the document body. Using @racketmodname[scribble/base] after 35 @hash-lang[] is the same as using @racketmodname[scribble/doc] plus 36 @racket[(require scribble/base)], and using 37 @racketmodname[scribble/manual] after @hash-lang[] is the same as using 38 @racketmodname[scribble/doc] plus @racket[(require scribble/manual)]. 39 40 Besides making the file a module, each of the @hash-lang[] 41 declarations selects the Scribble reader (instead of the usual Racket 42 reader), and it starts the body of the file in ``text'' mode. The 43 reader layer mostly leaves text alone, but @tech{@"@"-forms} escape 44 to S-expression mode. 45 46 A module written as 47 48 @verbatim[#:indent 2]|{ 49 #lang scribble/doc 50 @(require scribble/manual) 51 52 @(define to-be "To Be") 53 54 @title{@|to-be| or Not @|to-be|} 55 56 @bold{That} is the question. 57 Whether 'tis nobler... 58 }| 59 60 reads as 61 62 @racketblock[ 63 (module #,(nonterm "name") scribble/doc 64 (require scribble/manual) 65 "\n" 66 (define to-be "To Be") "\n" 67 "\n" 68 (title to-be " or Not " to-be) "\n" 69 "\n" 70 (bold "That") " is the question." "\n" 71 "Whether 'tis nobler..." "\n") 72 ] 73 74 As shown in this example, the read result is a module whose content 75 mingles text and definitions. The @racketmodname[scribble/doc] 76 language lifts definitions, @racket[require]s, and @racket[provide]s 77 to the beginning of the module, while everything else is collected 78 into a document bound to the provided identifier @racket[doc]. That 79 is, the module is transformed to something like this: 80 81 @racketblock[ 82 (module #,(nonterm "name") racket/base 83 (require scribble/decode 84 scribble/manual) 85 (define to-be "To Be") 86 (define doc 87 (decode 88 "\n" "\n" "\n" 89 (title to-be " or Not " to-be) "\n" 90 "\n" 91 (bold "That") " is the question." "\n" 92 "Whether 'tis nobler..." "\n")) 93 (provide doc)) 94 ] 95 96 The @racket[decode] function produces a @racket[part] structure 97 instance that represents the document. To build the @racket[part] 98 instance, it inspects its arguments to find a @racket[title-decl] 99 value created by @racket[title] to name the part, @racket[part-start] 100 values created by @racket[section] to designate sub-parts, etc. 101 102 A @racket[part] is the input to a rendering back-end, such as the HTML 103 renderer. All renderers recognize a fixed structure hierarchy: the 104 content of a part is a @defterm{flow}, which is a sequence of 105 @defterm{flow elements}, such as paragraphs and tables; a table, in 106 turn, consists of a list of list of flows; a paragraph is a list of 107 @defterm{elements}, which can be instances of the @racket[element] 108 structure type, plain strings, or certain special symbols. 109 110 The value bound to @racket[doc] in the example above is something like 111 112 @racketblock[ 113 (make-part .... 114 (list "To Be" " or Not " "To Be") (code:comment "title") 115 .... 116 (make-flow 117 (list 118 (make-paragraph 119 (list (make-element 'bold (list "That")) 120 " is the question." "\n" 121 "Whether " 'rsquo "tis nobler...")))) 122 ....) 123 ] 124 125 Notice that the @litchar{'} in the input's @litchar{'tis} has turned 126 into @racket['rsquo] (rendered as a curly apostrophe). The conversion to use 127 @racket['rsquo] was performed by @racket[decode] via 128 @racket[decode-flow] via @racket[decode-paragraph] via 129 @racket[decode-content] via @racket[decode-string]. 130 131 In contrast, @racket[(make-element 'bold (list "That"))] was produced 132 by the @racket[bold] function. The @racket[decode] operation is a 133 function, not a syntactic form, and so @racket[bold] has control over 134 its argument before @racket[decode] sees the result. Also, decoding 135 traverses only immediate string arguments. 136 137 As it turns out, @racket[bold] also decodes its argument, because the 138 @racket[bold] function is implemented as 139 140 @racketblock[ 141 (define (bold . strs) 142 (make-element 'bold (decode-content strs))) 143 ] 144 145 The @racket[verbatim] function, however, does not decode its content, 146 and instead typesets its text arguments directly. 147 148 A document module can construct elements directly using 149 @racket[make-element], but normally functions like @racket[bold] and 150 @racket[verbatim] are used to construct them. In particular, the 151 @racketmodname[scribble/manual] library provides many functions and 152 forms to typeset elements and flow elements. 153 154 The @racket[part] structure hierarchy includes built-in element types 155 for setting hyperlink targets and references. Again, this machinery is 156 normally packaged into higher-level functions and forms, such as 157 @racket[secref], @racket[defproc], and @racket[racket]. 158 159 @; ---------------------------------------------------------------------- 160 161 @section{Layer Roadmap} 162 163 Working roughly from the bottom up, the Scribble layers are: 164 165 @itemize[ 166 167 @item{@racketmodname[scribble/reader]: A reader that extends the 168 syntax of Racket with @tech{@"@"-forms} for conveniently embedding a 169 mixin of text and escapes. See @secref["reader"].} 170 171 @item{@racketmodname[scribble/core]: A set of document datatypes 172 and utilities that define the basic layout and processing of a 173 document. For example, the @racket[part] datatype is defined in 174 this layer. See @secref["core"].} 175 176 @item{@racketmodname[scribble/base-render] with 177 @racketmodname[scribble/html-render], 178 @racketmodname[scribble/latex-render], or 179 @racketmodname[scribble/text-render]: A base renderer and 180 mixins that generate documents in various formats from 181 instances of the @racketmodname[scribble/struct] datatypes. See 182 @secref["renderer"].} 183 184 @item{@racketmodname[scribble/decode]: Processes a stream of text, 185 section-start markers, etc. to produce instances of the 186 @racketmodname[scribble/core] datatypes. See 187 @secref["decode"].} 188 189 @item{@racketmodname[scribble/doclang]: A language to be used for the 190 initial import of a module; processes the module top level 191 through @racketmodname[scribble/decode], and otherwise provides 192 all of @racketmodname[racket/base]. See @secref["doclang"].} 193 194 @item{@racketmodname[scribble/doc]: A language that combines 195 @racketmodname[scribble/reader] with 196 @racketmodname[scribble/doclang]. See @secref["docreader"].} 197 198 @item{@racketmodname[scribble/base]: A library of basic document 199 operators---such as @racket[title], @racket[section], and 200 @racket[secref]---for use with @racketmodname[scribble/decode] 201 and a renderer. This library name also can be used as a 202 language, where it combines @racketmodname[scribble/doc] with 203 the exports of @racketmodname[scribble/base]. See 204 @secref["base"].} 205 206 @item{@racketmodname[scribble/racket]: A library of functions for 207 typesetting Racket code. See @secref["scheme"]. These functions 208 are not normally used directly, but instead used through 209 @racketmodname[scribble/manual].} 210 211 @item{@racketmodname[scribble/manual]: A library of functions for 212 writing Racket documentation; re-exports 213 @racketmodname[scribble/base]. Also, the 214 @racketmodname[scribble/manual-struct] library provides types 215 for index-entry descriptions created by functions in 216 @racketmodname[scribble/manual]. See @secref["manual"].} 217 218 @item{@racketmodname[scribble/eval]: A library of functions for 219 evaluating code at document-build time, especially for showing 220 examples. See @secref["eval"].} 221 222 @item{@racketmodname[scribble/bnf]: A library of support functions 223 for writing grammars. See @secref["bnf"].} 224 225 @item{@racketmodname[scribble/xref]: A library of support functions 226 for using cross-reference information, typically after a 227 document is rendered (e.g., to search). See @secref["xref"].} 228 229 @item{@racketmodname[scribble/text]: A language that uses 230 @racketmodname[scribble/reader] preprocessing text files.} 231 232 ] 233 234 The @exec{scribble} command-line utility generates output with a 235 specified renderer. More specifically, the executable installs a 236 renderer, loads the modules specified on the command line, extracts 237 the @racket[doc] export of each module (which must be an instance of 238 @racket[part]), and renders each---potentially with links that span 239 documents.