base.scrbl (31318B)
1 #lang scribble/doc 2 @(require scribble/manual "utils.rkt" 3 (for-syntax racket/base) 4 (for-label setup/main-collects 5 racket/runtime-path)) 6 7 @(define-syntax def-section-like 8 (syntax-rules () 9 [(_ id result/c x ...) 10 (defproc (id [#:tag tag (or/c #f string? (listof string?)) #f] 11 [#:tag-prefix tag-prefix (or/c #f string? module-path?) #f] 12 [#:style style (or/c style? #f string? symbol? (listof symbol?)) #f] 13 [pre-content pre-content?] (... ...+)) 14 result/c 15 x ...)])) 16 17 @(define-syntax def-elem-proc 18 (syntax-rules () 19 [(_ id x ...) 20 (defproc (id [pre-content pre-content?] (... ...)) 21 element? 22 x ...)])) 23 @(define-syntax def-style-proc 24 (syntax-rules () 25 [(_ id) 26 @def-elem-proc[id]{Like @racket[elem], but with style @racket['id].}])) 27 28 @title[#:tag "base"]{Base Document Format} 29 30 @defmodulelang[scribble/base]{The @racketmodname[scribble/base] 31 language provides functions and forms that can be used from code 32 written either in Racket or with @elem["@"] expressions. It 33 essentially extends @racketmodname[racket/base], except that top-level 34 forms within a module using the @racketmodname[scribble/base] language 35 are treated as document content (like @racketmodname[scribble/doclang]). 36 37 The @racketmodname[scribble/base] name can also be used as a library 38 with @racket[require], in which case it provides only the bindings 39 defined in this section, and it also does not set the reader or 40 set the default rendering format to the Racket manual format.} 41 42 Functions provided by this library, such as @racket[title] and 43 @racket[italic], might be called from Racket as 44 45 @racketblock[ 46 (title #:tag "how-to" 47 "How to Design " (italic "Great") " Programs") 48 ] 49 50 They can also be called with @elem["@"] notation as 51 52 @verbatim[#:indent 2]|{ 53 @title[#:tag "how-to"]{How to Design @italic{Great} Programs} 54 }| 55 56 Although the procedures are mostly designed to be used from @elem["@"] 57 mode, they are easier to document in Racket mode (partly because we 58 have @racketmodname[scribble/manual]). 59 60 @; ------------------------------------------------------------------------ 61 62 @section{Document Structure} 63 64 @defproc[(title [#:tag tag (or/c #f string? (listof string?)) #f] 65 [#:tag-prefix tag-prefix (or/c #f string? module-path?) #f] 66 [#:style style (or/c style? #f string? symbol? (listof symbol?)) #f] 67 [#:version vers (or/c string? #f) #f] 68 [#:date date (or/c string? #f) #f] 69 [pre-content pre-content?] ...+) 70 title-decl?]{ 71 72 Generates a @racket[title-decl] to be picked up by @racket[decode] or 73 @racket[decode-part]. The @tech{decode}d @racket[pre-content] (i.e., 74 parsed with @racket[decode-content]) supplies the title content. If 75 @racket[tag] is @racket[#f], a tag string is generated automatically 76 from the content. The tag string is combined with the symbol 77 @racket['part] to form the full tag. 78 79 The @racket[style] argument can be a style structure, or it can be one 80 of the following: a @racket[#f] that corresponds to a ``plain'' style, 81 a string that is used as a @tech{style name}, a symbol that is used as 82 a @tech{style property}, or a list of symbols to be used as @tech{style properties}. 83 For information on styles, see @racket[part]. For example, a style of 84 @racket['toc] causes sub-sections to be generated as separate pages in 85 multi-page HTML output. 86 87 The @racket[tag-prefix] argument is propagated to the generated 88 structure (see @secref["tags"]). If @racket[tag-prefix] is a module 89 path, it is converted to a string using 90 @racket[module-path-prefix->string]. 91 92 The @racket[vers] argument is propagated to the @racket[title-decl] 93 structure. Use @racket[""] as @racket[vers] to suppress version 94 rendering in the output. 95 96 The @racket[date] argument is propagated to the @racket[title-decl] 97 structure via a @racket[document-date] @tech{style property}. Use 98 @racket[""] as @racket[date] to suppress date rendering in Latex 99 output. 100 101 The section title is automatically indexed by 102 @racket[decode-part]. For the index key, leading whitespace and a 103 leading ``A'', ``An'', or ``The'' (followed by more whitespace) is 104 removed.} 105 106 107 @def-section-like[section part-start?]{ Like @racket[title], but 108 generates a @racket[part-start] of depth @racket[0] to be picked up by 109 @racket[decode] or @racket[decode-part].} 110 111 @def-section-like[subsection part-start?]{ Like @racket[section], but 112 generates a @racket[part-start] of depth @racket[1].} 113 114 @def-section-like[subsubsection part-start?]{ Like @racket[section], but 115 generates a @racket[part-start] of depth @racket[2].} 116 117 @def-section-like[subsubsub*section paragraph?]{ Similar to 118 @racket[section], but merely generates a paragraph that looks like an 119 unnumbered section heading (for when the nesting gets too deep to 120 include in a table of contents).} 121 122 @defform[(include-section module-path)]{ Requires @racket[module-path] 123 and returns its @racket[doc] export (without making any imports 124 visible to the enclosing context). Since this form expands to 125 @racket[require], it must be used in a module or top-level context.} 126 127 @defproc[(author [auth content?] ...) block?]{ 128 129 Generates a @racket[paragraph] with style name @racket['author] to 130 show the author(s) of a document, where each author is represented by 131 @tech{content}. Normally, this function is used after 132 @racket[title] for the beginning of a document. See also 133 @racket[author+email]. 134 135 Examples: 136 137 @codeblock[#:keep-lang-line? #f]|{ 138 #lang scribble/base 139 @author{Alice P. Racketeer} 140 }|} 141 142 @defproc[(author+email [author-name content?] 143 [email string?] 144 [#:obfuscate? obfuscate? any/c #f]) 145 element?]{ 146 147 Combines an author name with an e-mail address. If @racket[obfuscate?] 148 is true, then the result obscures the e-mail address slightly to avoid 149 address-harvesting robots. 150 151 Note that @racket[author+email] is not a replacement for 152 @racket[author]. The @racket[author+email] function is often used in 153 combination with @racket[author]. 154 155 Examples: 156 157 @codeblock[#:keep-lang-line? #f]|{ 158 #lang scribble/base 159 @author[(author+email "Bob T. Scribbler" "bob@racket-lang.org")] 160 }|} 161 162 @; ------------------------------------------------------------------------ 163 164 @section{Blocks} 165 166 @defproc[(para [#:style style (or/c style? string? symbol? #f) #f] 167 [pre-content pre-content?] ...) paragraph?]{ 168 169 Creates a @tech{paragraph} containing the @tech{decode}d 170 @racket[pre-content] (i.e., parsed with @racket[decode-paragraph]). 171 172 The @racket[style] argument can be a style, @racket[#f] to indicate a 173 ``plain'' style, a string that is used as a @tech{style name}, or a 174 symbol that is used as a @tech{style name}. (Note that 175 @racket[section] and @racket[para] treat symbols differently as 176 @racket[style] arguments.)} 177 178 179 @defproc[(nested [#:style style (or/c style? string? symbol? #f) #f] 180 [pre-flow pre-flow?] ...) nested-flow?]{ 181 182 Creates a @tech{nested flow} containing the @tech{decode}d 183 @racket[pre-flow] (i.e., parsed with @racket[decode-flow]). 184 185 The @racket[style] argument is handled the same as @racket[para]. The 186 @racket['inset] and @racket['code-inset] styles cause the nested flow 187 to be inset compared to surrounding text, with the latter 188 particularly intended for insetting code. The default style is 189 specified by the output destination (and tends to inset text for HTML 190 output and not inset for Latex output).} 191 192 193 @defproc[(centered [pre-flow pre-flow?] ...) nested-flow?]{ 194 195 Produces a @tech{nested flow} whose content is centered.} 196 197 198 @defproc[(margin-note [pre-flow pre-flow?] ... 199 [#:left? left? any/c #f]) 200 block?]{ 201 202 Produces a @tech{nested flow} that is typeset in the margin, instead 203 of inlined. 204 205 If @racket[left?] is true, then the note is shown on the opposite as 206 it would normally be shown (which is the left-hand side for HTML 207 output). Beware of colliding with output for a table of contents.} 208 209 210 @defproc[(margin-note* [pre-content pre-content?] ... 211 [#:left? left? any/c #f]) 212 element?]{ 213 214 Produces an @racket[element] that is typeset in the margin, instead of 215 inlined. Unlike @racket[margin-note], @racket[margin-note*] can be 216 used in the middle of a paragraph; at the same time, its content is 217 constrained to form a single paragraph in the margin.} 218 219 220 @defproc[(itemlist [itm items/c] ... 221 [#:style style (or/c style? string? symbol? #f) #f]) 222 itemization?]{ 223 224 Constructs an @racket[itemization] given a sequence of items. Typical 225 each @racket[itm] is constructed by @racket[item], but an 226 @racket[itm] can be a @tech{block} that is coerced to an 227 @racket[item]. Finally, @racket[itm] can be a list or @racket[splice] 228 whose elements are spliced (recursively, if necessary) into the 229 @racket[itemlist] sequence. 230 231 The @racket[style] argument is handled the same as @racket[para]. The 232 @racket['ordered] style numbers items, instead of just using a 233 bullet.} 234 235 236 @defthing[items/c flat-contract?]{ 237 238 A contract that is equivalent to the following recursive 239 specification: 240 241 @racketblock[ 242 (or/c item? block? (listof items/c) (spliceof items/c)) 243 ]} 244 245 246 @defproc[(item [pre-flow pre-flow?] ...) item?]{ 247 248 Creates an item for use with @racket[itemlist]. The @tech{decode}d 249 @racket[pre-flow] (i.e., parsed with @racket[decode-flow]) is the item 250 content.} 251 252 253 @defproc[(item? [v any/c]) boolean?]{ 254 255 Returns @racket[#t] if @racket[v] is an item produced by 256 @racket[item], @racket[#f] otherwise.} 257 258 259 @defproc[(tabular [cells (listof (listof (or/c block? content? 'cont)))] 260 [#:style style (or/c style? string? symbol? #f) #f] 261 [#:sep sep (or/c block? content? #f) #f] 262 [#:column-properties column-properties (listof any/c) '()] 263 [#:row-properties row-properties (listof any/c) '()] 264 [#:cell-properties cell-properties (listof (listof any/c)) '()] 265 [#:sep-properties sep-properties (or/c list? #f) #f]) 266 table?]{ 267 268 Creates a @tech{table} with the given @racket[cells] content, which is 269 supplied as a list of rows, where each row has a list of cells. The 270 length of all rows must match. 271 272 Use @racket['cont] in @racket[cells] as a cell to continue the content 273 of the preceding cell in a row in the space that would otherwise be 274 used for a new cell. A @racket['cont] must not appear as the first 275 cell in a row. 276 277 The @racket[style] argument is handled the same as @racket[para]. 278 See @racket[table] for a list of recognized @tech{style names} and @tech{style properties}. 279 280 The default style places no space between table columns. If 281 @racket[sep] is not @racket[#f], it is inserted as a new column 282 between every column in the table; the new column's properties are the 283 same as the preceding column's, unless @racket[sep-properties] 284 provides a list of @tech{style properties} to use. When @racket[sep] 285 would be placed before a @racket['cont], a @racket['cont] is inserted, 286 instead. 287 288 The @racket[column-properties], @racket[row-properties], and 289 @racket[cell-properties] arguments specify @tech{style properties} for 290 the columns and cells of a table; see @racket[table-columns] and 291 @racket[table-cells] for a description of recognized properties. The 292 lists do not contain entries for columns potentially introduced for 293 @racket[sep], and when non-empty, they are extended as needed to match 294 the table size determined by @racket[cells]: 295 296 @itemlist[ 297 298 @item{If the length of @racket[column-properties] is less than the 299 length of each row in @racket[cells], the last item of the list 300 is duplicated to make the list long enough.} 301 302 @item{If the length of @racket[row-properties] is less than the 303 length of @racket[cells], the last item of the list is 304 duplicated to make the list long enough.} 305 306 @item{If the length of @racket[cell-properties] is less than the 307 number of rows in @racket[cells], then the last element is 308 duplicated to make the list long enough. Each list within 309 @racket[cell-properties] is treated like a 310 @racket[column-properties] list---expanded as needed to match 311 the number of columns in each row.} 312 313 ] 314 315 Each element of @racket[column-properties] or @racket[row-properties] 316 is either a list of @tech{style property} values or a non-list element 317 that is wrapped as a list. Similarly, for each list that is an element 318 of @racket[cell-properties], the list's non-list elements are wrapped 319 as nested lists. 320 321 If @racket[column-properties] is non-empty, then its list of property 322 lists is converted into a @racket[table-columns] @tech{style property} 323 that is added to the style specified by @racket[style]---or merged 324 with an existing @racket[table-columns] @tech{style property} that 325 matches the column shape of @racket[cells]. In addition, if either 326 @racket[row-properties] or @racket[cell-properties] is non-empty, the 327 property lists of @racket[column-properties] are merged 328 with the property lists of @racket[row-properties] and 329 @racket[cell-properties]. If @racket[row-properties] or 330 @racket[cell-properties] is non-empty, the merged lists are 331 converted into a @racket[table-cells] @tech{style property} that is 332 added to the style specified by @racket[style]---or merged with an 333 existing @racket[table-cells] @tech{style property} that matches the 334 shape of @racket[cells]. 335 336 @margin-note{If the style lists for @racket[column-properties] are 337 both merged with @racket[cell-properties] and converted to 338 @racket[table-columns], then @racket[style] will contain some 339 redundant information. In that case, @racket[column-attributes] 340 properties will be used from @racket[table-columns], while other 341 properties will be used from the merger into @racket[table-cells].} 342 343 @history[#:changed "1.1" @elem{Added the @racket[#:column-properties], 344 @racket[#:row-properties], 345 and @racket[#:cell-properties] arguments.} 346 #:changed "1.12" @elem{Changed @racket[sep] insertion before a 347 @racket['cont].} 348 #:changed "1.28" @elem{Added @racket[sep-properties] and made 349 the preceding column's properties used 350 consistently if not specified.}] 351 352 Examples: 353 @codeblock[#:keep-lang-line? #f]|{ 354 #lang scribble/manual 355 @tabular[#:sep @hspace[1] 356 (list (list "soup" "gazpacho") 357 (list "soup" "tonjiru"))] 358 359 @tabular[#:style 'boxed 360 #:column-properties '(left right) 361 #:row-properties '(bottom-border ()) 362 (list (list @bold{recipe} @bold{vegetable}) 363 (list "caldo verde" "kale") 364 (list "kinpira gobō" "burdock") 365 (list "makizushi" 'cont))] 366 }| 367 @doc-render-examples[ 368 @tabular[#:sep @hspace[1] 369 (list (list "soup" "gazpacho") 370 (list "soup" "tonjiru"))] 371 372 @tabular[#:style 'boxed 373 #:column-properties '(left right) 374 #:row-properties '(bottom-border ()) 375 (list (list @bold{recipe} @bold{vegetable}) 376 (list "caldo verde" "kale") 377 (list "kinpira gobō" "burdock") 378 (list "makizushi" 'cont))]] 379 } 380 381 @defproc[(verbatim [#:indent indent exact-nonnegative-integer? 0] [elem content?] ...+) 382 block?]{ 383 384 Typesets string @racket[elem]s in typewriter font with linebreaks 385 specified by newline characters in string @racket[elem]s. Consecutive spaces in 386 the string @racket[elem]s are converted to @racket[hspace] to ensure that they 387 are all preserved in the output. Additional space (via 388 @racket[hspace]) as specified by @racket[indent] is added to the 389 beginning of each line. A non-string @racket[elem] is treated as 390 content within a single line. 391 392 The string @racket[elem]s are @emph{not} decoded with @racket[decode-content], 393 so @racket[(verbatim "---")] renders with three hyphens instead of an 394 em dash. Beware, however, that @emph{reading} 395 @litchar["@"]@racket[verbatim] converts @litchar["@"] syntax 396 within the argument, and such reading occurs well before 397 arguments to @racket[verbatim] are delivered at run-time. To disable simple 398 @litchar["@"] notation within the @racket[verbatim] argument, 399 @racket[verbatim] is typically used with 400 @litchar["|{"]...@litchar["}|"] or similar brackets, like this: 401 402 @verbatim[#:indent 2]|{ 403 @verbatim|{ 404 Use @bold{---} like this... 405 }| 406 }| 407 408 which renders as 409 410 @verbatim[#:indent 2]|{ 411 Use @bold{---} like this... 412 }| 413 414 while 415 416 @verbatim[#:indent 2]||{ 417 @verbatim|{ 418 Use |@bold{---} like this... 419 }| 420 }|| 421 422 renders as 423 424 @verbatim[#:indent 2]|{ 425 Use |@bold{---} like this... 426 }| 427 428 Even with brackets like @litchar["|{"]...@litchar["}|"], beware that consistent 429 leading whitespace is removed by the parser; see 430 @secref["alt-body-syntax"] for more information. 431 432 See also @racket[literal].} 433 434 @; ------------------------------------------------------------------------ 435 436 @section{Text Styles and Content} 437 438 @defproc[(elem [pre-content pre-content?] ... 439 [#:style style (or/c style? string? symbol? #f) #f]) 440 element?]{ 441 442 Wraps the @tech{decode}d @racket[pre-content] as an element with style 443 @racket[style].} 444 445 446 @def-style-proc[italic] 447 @def-style-proc[bold] 448 449 @defproc[(tt [pre-content pre-content?] ...) element?]{ 450 451 Similar to @racket[elem], but the @racket['tt] style is used for 452 immediate strings and symbols among the @racket[pre-content] 453 arguments. 454 455 To apply the @racket['tt] style uniformly to all @racket[pre-content] 456 arguments, use @racket[(elem #:style 'tt pre-content ...)], instead.} 457 458 @def-style-proc[subscript] 459 @def-style-proc[superscript] 460 461 @def-elem-proc[smaller]{Like @racket[elem], but with style 462 @racket['smaller]. When uses of @racket[smaller] are nested, text 463 gets progressively smaller.} 464 465 @def-elem-proc[larger]{Like @racket[elem], but with style 466 @racket['larger]. When uses of @racket[larger] are nested, text 467 gets progressively larger.} 468 469 @defproc[(emph [pre-content pre-content?] ...) element?]{ 470 Like @racket[elem], but emphasised. Typically, italics are used for 471 emphasis. Uses of @racket[emph] can be nested; typically this causes 472 the text to alternate between italic and upright.} 473 474 @defproc[(literal [str string?] ...+) element?]{ 475 476 Produces an element containing literally @racket[str]s with no 477 decoding via @racket[decode-content]. 478 479 Beware that @litchar["@"] for a @racket[literal] call performs some 480 processing before delivering arguments to @racket[literal]. The 481 @racket[literal] form can be used with @litchar["|{"]...@litchar["}|"] 482 or similar brackets to disable @litchar["@"] notation within the 483 @racket[literal] argument, like this: 484 485 @verbatim[#:indent 2]|{ 486 @literal|{@bold{---}}| 487 }| 488 489 which renders as 490 491 @verbatim[#:indent 2]{ 492 @literal|{@bold{---}}| 493 } 494 495 See also @racket[verbatim].} 496 497 @; ------------------------------------------------------------------------ 498 @section[#:tag "images"]{Images} 499 500 501 @defproc[(image [path (or/c path-string? (cons/c 'collects (listof bytes?)))] 502 [#:scale scale real? 1.0] 503 [#:suffixes suffixes (listof #rx"^[.]") null] 504 [#:style style (or/c style? string? symbol? #f) #f] 505 [pre-content pre-content?] ...) 506 image-element?]{ 507 508 Creates an image element from the given path. The @tech{decode}d 509 @racket[pre-content] serves as the alternate text for contexts where 510 the image cannot be displayed. 511 512 If @racket[path] is a relative path, it is relative to the current 513 directory, which is set by @exec{raco setup} to 514 the directory of the main document file. (In general, however, it's 515 more reliable to express relative paths using 516 @racket[define-runtime-path].) Instead of a path or string, 517 the @racket[path] argument can be a result of 518 @racket[path->main-collects-relative]. 519 520 The @racket[scale] argument sets the images scale relative to its 521 default size as determined by the content of @racket[path]. For HTML 522 output, the resulting @racket[image-element] is rendered with an 523 @tt{img} or @tt{object} (for SVG) tag, and @racket[scale] adjusts the 524 @tt{width} and @tt{height} attributes; a class name or other 525 attributes in @racket[style] can effectively override that size. 526 527 The strings in @racket[suffixes] are filtered to those supported by 528 given renderer, and then the acceptable suffixes are tried in 529 order. The HTML renderer supports @racket[".png"], 530 @racket[".gif"], and @racket[".svg"], while the Latex renderer supports @racket[".png"], 531 @racket[".pdf"], and @racket[".ps"] (but @racket[".ps"] works only 532 when converting Latex output to DVI, and @racket[".png"] and 533 @racket[".pdf"] work only for converting Latex output to PDF). 534 535 Note that when the @racket[suffixes] list is non-empty, then 536 the @racket[path] argument should not have a suffix. 537 538 @history[#:changed "1.3" @elem{Added the @racket[#:style] argument.}]} 539 540 @; ------------------------------------------------------------------------ 541 @section[#:tag "spacing"]{Spacing} 542 543 @defproc[(linebreak) element?]{ 544 Produces an element that forces a line break.} 545 546 547 @def-elem-proc[nonbreaking]{Like @racket[elem], but line breaks are 548 suppressed while rendering the content.} 549 550 551 @defproc[(hspace [n exact-nonnegative-integer?]) element?]{ 552 553 Produces an element containing @racket[n] spaces and style 554 @racket['hspace].} 555 556 557 @defthing[~ string?]{ 558 559 A string containing the non-breaking space character, 560 which is equivalent to @racket['nbsp] as an element.} 561 562 563 @defthing[-~- string?]{ 564 565 A string containing the non-breaking hyphen character.} 566 567 568 @defthing[?- string?]{ 569 570 A string containing the soft-hyphen character (i.e., a suggestion of 571 where to hyphenate a word to break it across lines when rendering).} 572 573 574 @defthing[._ element?]{ 575 576 Generates a period that ends an abbreviation in the middle of a 577 sentence, as opposed to a period that ends a sentence (since the 578 latter may be typeset with extra space). Use @litchar|{@._}| in a 579 document instead of just @litchar{.} for an abbreviation-ending period 580 that is preceded by a lowercase letter and followed by a space. 581 582 See @racket[.__] for an example.} 583 584 585 @defthing[.__ element?]{ 586 587 Generates a period that ends a sentence (which may be typeset with 588 extra space), as opposed to a period that ends an abbreviation in the 589 middle of a sentence. Use @litchar|{@.__}| in a document instead of just 590 @litchar{.} for a sentence-ending period that is preceded by an 591 uppercase letter. 592 593 The following example illustrates both @racket[._] and @racket[.__]: 594 595 @codeblock|{ 596 #lang scribble/base 597 My name is Mr@._ T@.__ I pity the fool who can't typeset punctuation. 598 }|} 599 600 601 @; ------------------------------------------------------------------------ 602 @section[#:tag "base-links"]{Links} 603 604 @defproc[(hyperlink [url string?] [pre-content pre-content?] ... 605 [#:underline? underline? any/c #t] 606 [#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")]) 607 element?]{ 608 609 The @tech{decode}d @racket[pre-content] is hyperlinked to 610 @racket[url]. If @racket[style] is not supplied, then 611 @racket[underline?] determines how the link is rendered.} 612 613 614 @defproc[(url [dest string?]) element?]{ 615 616 Generates a literal hyperlinked URL.} 617 618 619 @defproc[(secref [tag string?] 620 [#:doc module-path (or/c module-path? #f) #f] 621 [#:tag-prefixes prefixes (or/c (listof string?) #f) #f] 622 [#:underline? underline? any/c #t] 623 [#:link-render-style ref-style (or/c link-render-style? #f)]) 624 element?]{ 625 626 Inserts a reference to the section tagged @racket[tag]. 627 628 If @racket[#:doc module-path] is provided, the @racket[tag] refers to 629 a tag with a prefix determined by @racket[module-path]. When 630 @exec{raco setup} renders documentation, it automatically adds a tag 631 prefix to the document based on the source module. Thus, for example, 632 to refer to a section of the Racket reference, 633 @racket[module-path] would be @racket['(lib 634 "scribblings/reference/reference.scrbl")]. 635 636 The @racket[#:tag-prefixes prefixes] argument similarly supports 637 selecting a particular section as determined by a path of tag 638 prefixes. When a @racket[#:doc] argument is provided, then 639 @racket[prefixes] should trace a path of tag-prefixed subsections to 640 reach the @racket[tag] section. When @racket[#:doc] is not provided, 641 the @racket[prefixes] path is relative to any enclosing section (i.e., 642 the youngest ancestor that produces a match). 643 644 For the result @racket[link-element], if @racket[ref-style] is not 645 @racket[#f], then it is attached as a @tech{style property} and 646 affects the rendering of the link. Alternatively, an enclosing 647 @racket[part] can have a link-render style that adjusts the rendering 648 style for all links within the @tech{part}. See @racket[link-element] 649 for more information about the rendering of section references. 650 651 If @racket[underline?] is @racket[#f], then a @tech{style} is attached 652 to the result @racket[link-element] so that the hyperlink is rendered 653 in HTML without an underline 654 655 In Racket documentation that is rendered to HTML, clicking on a 656 section title normally shows the @racket[secref] call that is needed 657 to link to the section. 658 659 @history[#:changed "1.25" @elem{Added the @racket[#:link-render-style] argument.}]} 660 661 662 @defproc[(Secref [tag string?] 663 [#:doc module-path (or/c module-path? #f) #f] 664 [#:tag-prefixes prefixes (or/c (listof string?) #f) #f] 665 [#:underline? underline? any/c #t] 666 [#:link-render-style ref-style (or/c link-render-style? #f)]) 667 element?]{ 668 669 Like @racket[secref], but if the rendered form of the reference starts 670 with a word (e.g., ``section''), then the word is capitalized. 671 672 @history[#:changed "1.25" @elem{Added the @racket[#:link-render-style] argument.}]} 673 674 675 @defproc[(seclink [tag string?] 676 [#:doc module-path (or/c module-path? #f) #f] 677 [#:tag-prefixes prefixes (or/c (listof string?) #f) #f] 678 [#:underline? underline? any/c #t] 679 [#:indirect? indirect? any/c #f] 680 [pre-content pre-content?] ...) element?]{ 681 682 Like @racket[secref], but the link label is the @tech{decode}d 683 @racket[pre-content] instead of the target section's name. 684 685 In addition to @racket[secref]'s arguments, @racket[seclink] supports 686 a @racket[indirect?] argument. When @racket[indirect?] is true, then 687 the section hyperlink's resolution in HTML is potentially delayed; see 688 @racket['indirect-link] for @racket[link-element].} 689 690 691 @defproc[(other-doc [module-path module-path?] 692 [#:underline? underline? any/c #t] 693 [#:indirect indirect (or/c #f content?) #f]) 694 element?]{ 695 696 Like @racket[secref] for the document's implicit @racket["top"] 697 tag. Use this function to refer to a whole manual instead of 698 @racket[secref], in case a special style in the future is used for 699 manual titles. 700 701 If @racket[indirect] is not @racket[#f], then the link's resolution in 702 HTML can be delayed, like @racket[seclink] with @racket[#:indirect? 703 #t]. The @racket[indirect] content is prefixed with ``the'' and 704 suffixed with ``documentation'' to generate the rendered text of the 705 link. For example: 706 707 @verbatim[#:indent 2]|{ 708 @other-doc['(lib "parsack/parsack/parsack.scrbl") 709 #:indirect "Parsec implementation in Racket"] 710 }| 711 712 renders as a hyperlink with the text: 713 714 @verbatim[#:indent 2]|{ 715 the Parsec implementation in Racket documentation 716 }|} 717 718 719 @defproc[(elemtag [t (or/c taglet? generated-tag?)] [pre-content pre-content?] ...) element?]{ 720 721 The tag @racket[t] refers to the content form of 722 @racket[pre-content].} 723 724 725 @defproc[(elemref [t (or/c taglet? generated-tag?)] [pre-content pre-content?] ... 726 [#:underline? underline? any/c #t]) element?]{ 727 728 The @tech{decode}d @racket[pre-content] is hyperlinked to @racket[t], 729 which is normally defined using @racket[elemtag].} 730 731 @; ------------------------------------------------------------------------ 732 733 @section[#:tag "base-indexing"]{Indexing} 734 735 @defproc[(index [words (or/c string? (listof string?))] 736 [pre-content pre-content?] ...) 737 index-element?]{ 738 739 Creates an index element given a plain-text string---or list of 740 strings for a hierarchy, such as @racket['("strings" "plain")] for a 741 ``plain'' entry below a more general ``strings'' entry. As index keys, 742 the strings are ``cleaned'' using @racket[clean-up-index-string]. The 743 strings (without clean-up) also serve as the text to render in the 744 index. The @tech{decode}d @racket[pre-content] is the text to appear 745 inline as the index target. 746 747 Use @racket[index] when an index entry should point to a specific word 748 or phrase within the typeset document (i.e., the 749 @racket[pre-content]). Use @racket[section-index], instead, to create 750 an index entry that leads to a section, instead of a specific word or 751 phrase within the section.} 752 753 754 @defproc[(index* [words (listof string?)] 755 [word-contents (listof list?)] 756 [pre-content pre-content?] ...) 757 index-element?]{ 758 Like @racket[index], except that @racket[words] must be a list, and 759 the list of contents render in the index (in parallel to 760 @racket[words]) is supplied as @racket[word-contents]. 761 } 762 763 @defproc[(as-index [pre-content pre-content?] ...) 764 index-element?]{ 765 766 Like @racket[index], but the word to index is determined by applying 767 @racket[content->string] on the @tech{decode}d @racket[pre-content].} 768 769 770 @defproc[(section-index [word string?] ...) 771 part-index-decl?]{ 772 773 Creates a @racket[part-index-decl] to be associated with the enclosing 774 section by @racket[decode]. The @racket[word]s serve as both the keys 775 and as the rendered forms of the keys within the index.} 776 777 778 @defproc[(index-section [#:tag tag (or/c #f string?) "doc-index"]) 779 part?]{ 780 781 Produces a part that shows the index the enclosing document. The 782 optional @racket[tag] argument is used as the index section's tag.} 783 784 785 @; ------------------------------------------------------------------------ 786 787 @section{Tables of Contents} 788 789 @defproc[(table-of-contents) delayed-block?]{ 790 791 Returns a delayed flow element that expands to a table of contents for 792 the enclosing section. For Latex output, however, the table of 793 contents currently spans the entire enclosing document.} 794 795 796 @defproc[(local-table-of-contents [#:style style (or/c symbol? #f) #f]) 797 delayed-block?]{ 798 799 Returns a delayed flow element that may expand to a table of contents 800 for the enclosing section, depending on the output type. For 801 multi-page HTML output, the flow element is a table of contents; for 802 Latex output, the flow element is empty. 803 804 The meaning of the @racket[style] argument depends on the output type, 805 but @racket['immediate-only] normally creates a table of contents that 806 contains only immediate sub-sections of the enclosing section. See 807 also the @racket['quiet] style of @racket[part] (i.e., in a 808 @racket[part] structure, not supplied as the @racket[style] argument 809 to @racket[local-table-of-contents]), which normally suppresses 810 sub-part entries in a table of contents.} 811 812 @; ------------------------------------------------------------------------ 813 814 @section{Tags} 815 816 The exports of @racketmodname[scribble/tag] are all re-exported by 817 @racketmodname[scribble/base]. 818