struct.scrbl (11290B)
1 #lang scribble/manual 2 @(require (except-in "utils.rkt" 3 make-part make-paragraph make-table make-itemization make-compound-paragraph 4 make-element make-toc-element make-target-element make-toc-target-element make-toc-target2-element 5 make-page-target-element make-redirect-target-element make-link-element 6 make-index-element 7 make-target-url target-url struct:target-url target-url? target-url-addr 8 toc-element-toc-content toc-target2-element-toc-content part-title-content paragraph-content 9 element? element-content element-style) 10 (for-label scribble/manual-struct 11 scribble/struct 12 setup/main-collects)) 13 14 @(define (compat) @italic{For backward compatibility.}) 15 @(define-syntax-rule (compat/comp id) 16 @elem{@compat[] Compared to the normal constructor for @racket[id]}) 17 18 @title[#:tag "struct"]{Compatibility Structures And Processing} 19 20 @defmodule[scribble/struct]{ 21 The @racket[scribble/struct] compatibility library mostly re-exports 22 @racket[scribble/core], but using some different names (e.g., 23 @racket[blockquote] instead of @racket[nested-flow]).} 24 25 The following structure types and functions are re-exported directly: 26 27 @racketblock[collect-info resolve-info tag? block? 28 delayed-block collected-info delayed-element ; delayed-element-content delayed-block-blocks current-serialize-resolve-info 29 part-relative-element collect-info-parents ; part-relative-element-content delayed-index-desc 30 collect-element render-element generated-tag ; generate-tag current-tag-prefixes add-current-tag-prefix 31 tag-key content->string element->string ; strip-aux 32 block-width element-width 33 info-key? part-collected-info collect-put! 34 resolve-get resolve-get/tentative resolve-get/ext? 35 resolve-search resolve-get-keys] 36 37 The following structure types are re-exported, but the constructors and some selectors 38 are replaced as documented further below: 39 40 @racketblock[part paragraph table itemization compound-paragraph 41 element toc-element target-element toc-target-element toc-target2-element 42 page-target-element redirect-target-element link-element 43 index-element] 44 45 Several additional compatibility functions and structure types are 46 also exported. 47 48 @defproc[(make-part [tag-prefix (or/c false/c string?)] 49 [tags (listof tag?)] 50 [title-content (or/c false/c list?)] 51 [style any/c] 52 [to-collect list?] 53 [blocks (listof block?)] 54 [parts (listof part?)]) 55 part?]{ 56 57 @compat/comp[part], parses @racket[style] to convert old formats to 58 the current one. Also, if @racket[title-content] is a list with a 59 single item, the item by itself is stored in the resulting 60 @racket[part].} 61 62 @defproc[(part-flow [p part?]) (listof block?)]{ 63 64 @compat[] An alias for @racket[part-blocks].} 65 66 @defproc[(part-title-content [p part?]) list?]{ 67 68 @compat[] Like the normal selector, but if the result would not be a list, it is 69 coerced to one.} 70 71 @deftogether[( 72 @defproc[(make-versioned-part [tag-prefix (or/c false/c string?)] 73 [tags (listof tag?)] 74 [title-content (or/c false/c list?)] 75 [style any/c] 76 [to-collect list?] 77 [blocks (listof block?)] 78 [parts (listof part?)] 79 [version string?]) 80 part?] 81 @defproc[(versioned-part? [v any/c]) boolean?] 82 )]{ 83 84 @compat[] Like @racket[make-part], but adds a the 85 @racket[document-version] @tech{style property} using the given 86 @racket[version]. The @racket[versioned-part?] predicate recognizes a 87 @racket[part] with a @racket[document-version] property.} 88 89 @deftogether[( 90 @defproc[(make-unnumbered-part [tag-prefix (or/c false/c string?)] 91 [tags (listof tag?)] 92 [title-content (or/c false/c list?)] 93 [style any/c] 94 [to-collect list?] 95 [blocks (listof block?)] 96 [parts (listof part?)]) 97 part?] 98 @defproc[(unnumbered-part? [v any/c]) boolean?] 99 )]{ 100 101 @compat[] Like @racket[make-part], but adds the @racket['unnumbered] 102 @tech{style property}. The @racket[unnumbered-part?] predicate 103 recognizes a @racket[part] with the @racket['unnumbered] property.} 104 105 106 @defproc[(make-paragraph [content list?]) paragraph?]{ 107 108 @compat/comp[paragraph], omits a style argument. Also, if 109 @racket[content] is a list containing a single item, the item by 110 itself is stored in the resulting @racket[paragraph].} 111 112 @defproc[(paragraph-content [p paragraph?]) list?]{ 113 114 @compat[] Like the normal selector, but if the result would not be a list, it is 115 coerced to one. 116 } 117 118 119 @deftogether[( 120 @defproc[(make-styled-paragraph [content list?] [style any/c]) paragraph?] 121 @defproc[(styled-paragraph? [v any/c]) boolean?] 122 @defproc[(styled-paragraph-style [p paragraph?]) style?] 123 )]{ 124 125 @compat/comp[paragraph], parses @racket[style] to convert old formats 126 to the current one. The @racket[styled-paragraph?] predicate and 127 @racket[styled-paragraph-style] accessor are aliases for 128 @racket[paragraph?] and @racket[paragraph-style].} 129 130 131 @deftogether[( 132 @defproc[(make-omitable-paragraph [content list?]) paragraph?] 133 @defproc[(omitable-paragraph? [v any/c]) boolean?] 134 )]{ 135 136 @compat[] Like @racket[make-paragraph], but adds the 137 @racket['omitable] @tech{style property}. The 138 @racket[omitable-paragraph?] predicate checks for a paragraph with the 139 property.} 140 141 142 @defproc[(make-table [style any/c] 143 [blocksss (listof (listof (or/c (listof block?) (one-of/c 'cont))))]) 144 table?]{ 145 146 @compat/comp[table], the style is converted, and each cell has a list 147 of blocks instead of a single block. If any such list has multiple 148 blocks, they are combined into a @racket[nested-flow].} 149 150 @defproc[(table-flowss [table table?]) 151 (listof (listof (or/c (listof block?) (one-of/c 'cont))))]{ 152 153 @compat[] Like @racket[table-blockss], but adds a list wrapper to be 154 consistent with @racket[make-table].} 155 156 @defproc[(make-itemization [blockss (listof (listof block?))]) itemization?]{ 157 158 @compat/comp[itemization], omits a style argument.} 159 160 @deftogether[( 161 @defproc[(make-styled-itemization [style any/c] 162 [blockss (listof (listof block?))]) itemization?] 163 @defproc[(styled-itemization? [v any/c]) boolean?] 164 @defproc[(styled-itemization-style [i itemization?]) style?] 165 )]{ 166 167 @compat/comp[itemization], parses @racket[style] to convert old 168 formats to the current one. The @racket[styled-itemization?] predicate 169 is an alias for @racket[itemization?], and 170 @racket[styled-itemization-style] is an alias for 171 @racket[itemization-style].} 172 173 @defproc[(make-blockquote [style any/c] [blocks (listof block?)]) 174 nested-flow?]{ 175 176 @compat[] Like @racket[make-nested-flow], but @racket[style] is 177 parsed to the current format.} 178 179 180 @deftogether[( 181 @defproc[(make-auxiliary-table [style any/c] 182 [blocksss (listof (listof (or/c (listof block?) (one-of/c 'cont))))]) 183 table?] 184 @defproc[(auxiliary-table? [v any/c]) boolean?] 185 )]{ 186 187 @compat[] Like @racket[make-table], but adds the @racket['aux] 188 @tech{style property}. The @racket[auxiliary-table?] predicate recognizes 189 tables with the @racket['aux] property.} 190 191 192 @defproc[(make-compound-paragraph [style any/c] 193 [blocks (listof block?)]) 194 compound-paragraph?]{ 195 196 @compat/comp[compound-paragraph], parses @racket[style] to convert old 197 formats to the current one.} 198 199 @deftogether[( 200 @defproc[(make-element [style any/c] [content list?]) element?] 201 @defproc[(make-toc-element [style any/c] [content list?] [toc-content list?]) toc-element?] 202 @defproc[(make-target-element [style any/c] [content list?] [tag tag?]) target-element?] 203 @defproc[(make-toc-target-element [style any/c] [content list?] [tag tag?]) toc-target-element?] 204 @defproc[(make-toc-target2-element [style any/c] [content list?] [tag tag?] [toc-content content?]) toc-target2-element?] 205 @defproc[(make-page-target-element [style any/c] [content list?] [tag tag?]) page-target-element?] 206 @defproc[(make-redirect-target-element [style any/c] [content list?] [tag tag?] 207 [alt-path path-string?] [alt-anchor string?]) redirect-target-element?] 208 @defproc[(make-link-element [style any/c] [content list?] [tag tag?]) link-element?] 209 @defproc[(make-index-element [style any/c] [content list?] [tag tag?] 210 [plain-seq (and/c pair? (listof string?))] 211 [entry-seq list?] [desc any/c]) index-element?] 212 )]{ 213 214 @compat[] Compared to the normal constructors, parses @racket[style] to convert old 215 formats to the current one.} 216 217 218 @deftogether[( 219 @defproc[(element? [v any/c]) boolean?] 220 @defproc[(element-content [e element?]) list?] 221 @defproc[(element-style [e element?]) element-style?] 222 )]{ 223 224 @compat[] A @tech{content} list is treated as an element by these functions, 225 and the result of @racket[element-content] is always a list.} 226 227 228 @defproc[(make-aux-element [style any/c] [content list?]) element?]{ 229 230 @compat[] Like @racket[make-element], but adds the @racket['aux] 231 @tech{style property}.} 232 233 234 @defproc[(make-hover-element [style any/c] [content list?] [text string?]) element?]{ 235 236 @compat[] Like @racket[make-element], but adds @racket[hover-property] 237 containing @racket[text] to the element's style.} 238 239 240 @defproc[(make-script-element [style any/c] [content list?] [type string?] 241 [script (or/c path-string? (listof string?))]) element?]{ 242 243 @compat[] Like @racket[make-element], but adds @racket[script-property] 244 containing @racket[type] and @racket[script] to the element's style.} 245 246 247 @defstruct[with-attributes ([style any/c] 248 [assoc (listof (cons/c symbol? string?))])]{ 249 250 @compat[] Used for an @racket[element]'s style to combine a base style with 251 arbitrary HTML attributes. When the @racket[style] field is itself an 252 instance of @racket[with-attributes], its content is automatically 253 flattened into the enclosing @racket[with-attributes] when it is used 254 (when, e.g., rendering an @racket[element] or @racket[paragraph]).} 255 256 257 @defstruct[target-url ([addr path-string?] 258 [style any/c])]{ 259 260 @compat[] Used as a style for an @racket[element]. The @racket[style] at this 261 layer is a style for the hyperlink.} 262 263 264 @defstruct[image-file ([path (or/c path-string? 265 (cons/c 'collects (listof bytes?)))] 266 [scale real?])]{ 267 268 @compat[] Used as a style for an @racket[element] to inline an image. The 269 @racket[path] field can be a result of 270 @racket[path->main-collects-relative].} 271 272 273 274 275 @defproc*[([(element->string (element content?)) string?] 276 [(element->string (element content?) (renderer any/c) (p part?) (info resolve-info?)) string?])]{ 277 278 @compat[] An alias for @racket[content->string]. 279 280 }