diff --git a/collects/scribblings/scribble/base.scrbl b/collects/scribblings/scribble/base.scrbl index 7daf57a3..ed20b5a3 100644 --- a/collects/scribblings/scribble/base.scrbl +++ b/collects/scribblings/scribble/base.scrbl @@ -1,7 +1,7 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label setup/main-collects)) @(define-syntax def-section-like @@ -23,23 +23,23 @@ @(define-syntax def-style-proc (syntax-rules () [(_ id) - @def-elem-proc[id]{Like @scheme[elem], but with style @scheme['id].}])) + @def-elem-proc[id]{Like @racket[elem], but with style @racket['id].}])) @title[#:tag "base"]{Base Document Format} -@defmodulelang[scribble/base]{The @schememodname[scribble/base] language +@defmodulelang[scribble/base]{The @racketmodname[scribble/base] language provides functions and forms that can be used from code written either -in Scheme or with @elem["@"] expressions. +in Racket or with @elem["@"] expressions. -The @schememodname[scribble/base] name can also be used as a -library with @scheme[require], in which case it provides all of the same +The @racketmodname[scribble/base] name can also be used as a +library with @racket[require], in which case it provides all of the same bindings, but without setting the reader or setting the default -rendering format to the PLT Scheme manual format.} +rendering format to the Racket manual format.} -Functions provided by this library, such as @scheme[title] and -@scheme[italic], might be called from Scheme as +Functions provided by this library, such as @racket[title] and +@racket[italic], might be called from Racket as -@schemeblock[ +@racketblock[ (title #:tag "how-to" "How to Design " (italic "Great") " Programs") ] @@ -51,8 +51,8 @@ They can also be called with @elem["@"] notation as }| Although the procedures are mostly design to be used from @elem["@"] -mode, they are easier to document in Scheme mode (partly because we -have @schememodname[scribble/manual]). +mode, they are easier to document in Racket mode (partly because we +have @racketmodname[scribble/manual]). @; ------------------------------------------------------------------------ @@ -65,70 +65,70 @@ have @schememodname[scribble/manual]). [pre-content pre-content?] ...+) title-decl?]{ -Generates a @scheme[title-decl] to be picked up by @scheme[decode] or -@scheme[decode-part]. The @tech{decode}d @scheme[pre-content] (i.e., -parsed with @scheme[decode-content]) supplies the title content. If -@scheme[tag] is @scheme[#f], a tag string is generated automatically +Generates a @racket[title-decl] to be picked up by @racket[decode] or +@racket[decode-part]. The @tech{decode}d @racket[pre-content] (i.e., +parsed with @racket[decode-content]) supplies the title content. If +@racket[tag] is @racket[#f], a tag string is generated automatically from the content. The tag string is combined with the symbol -@scheme['part] to form the full tag. +@racket['part] to form the full tag. -The @scheme[style] argument can be a style structure, or it can be one -of the following: a @scheme[#f] that corresponds to a ``plain'' style, +The @racket[style] argument can be a style structure, or it can be one +of the following: a @racket[#f] that corresponds to a ``plain'' style, a string that is used as a @tech{style name}, a symbol that is used as a @tech{style property}, or a list of symbols to be used as @tech{style properties}. -For information on styles, see @scheme[part]. For example, a style of -@scheme['toc] causes sub-sections to be generated as separate pages in +For information on styles, see @racket[part]. For example, a style of +@racket['toc] causes sub-sections to be generated as separate pages in multi-page HTML output. -The @scheme[tag-prefix] argument is propagated to the generated -structure (see @secref["tags"]). If @scheme[tag-prefix] is a module +The @racket[tag-prefix] argument is propagated to the generated +structure (see @secref["tags"]). If @racket[tag-prefix] is a module path, it is converted to a string using -@scheme[module-path-prefix->string]. +@racket[module-path-prefix->string]. -The @scheme[vers] argument is propagated to the @scheme[title-decl] -structure. Use @scheme[""] as @scheme[vers] to suppress version +The @racket[vers] argument is propagated to the @racket[title-decl] +structure. Use @racket[""] as @racket[vers] to suppress version rendering in the output. The section title is automatically indexed by -@scheme[decode-part]. For the index key, leading whitespace and a +@racket[decode-part]. For the index key, leading whitespace and a leading ``A'', ``An'', or ``The'' (followed by more whitespace) is removed.} -@def-section-like[section part-start?]{ Like @scheme[title], but - generates a @scheme[part-start] of depth @scheme[0] to be by - @scheme[decode] or @scheme[decode-part].} +@def-section-like[section part-start?]{ Like @racket[title], but + generates a @racket[part-start] of depth @racket[0] to be by + @racket[decode] or @racket[decode-part].} -@def-section-like[subsection part-start?]{ Like @scheme[section], but - generates a @scheme[part-start] of depth @scheme[1].} +@def-section-like[subsection part-start?]{ Like @racket[section], but + generates a @racket[part-start] of depth @racket[1].} -@def-section-like[subsubsection part-start?]{ Like @scheme[section], but - generates a @scheme[part-start] of depth @scheme[2].} +@def-section-like[subsubsection part-start?]{ Like @racket[section], but + generates a @racket[part-start] of depth @racket[2].} @def-section-like[subsubsub*section paragraph?]{ Similar to - @scheme[section], but merely generates a paragraph that looks like an + @racket[section], but merely generates a paragraph that looks like an unnumbered section heading (for when the nesting gets too deep to include in a table of contents).} -@defform[(include-section module-path)]{ Requires @scheme[module-path] - and returns its @scheme[doc] export (without making any imports +@defform[(include-section module-path)]{ Requires @racket[module-path] + and returns its @racket[doc] export (without making any imports visible to the enclosing context). Since this form expands to - @scheme[require], it must be used in a module or top-level context.} + @racket[require], it must be used in a module or top-level context.} @defproc[(author [auth content?] ...) block?]{ -Generates a @scheme[paragraph] with style name @scheme['author] to +Generates a @racket[paragraph] with style name @racket['author] to show the author(s) of a document, where each author is represented by @tech{content}. Normally, this function is used after -@scheme[title] for the beginning of a document. See also -@scheme[author+email].} +@racket[title] for the beginning of a document. See also +@racket[author+email].} @defproc[(author+email [author elem] [email string?] [#:obfuscate? obfuscate? any/c #f]) element?]{ -Combines an author name with an e-mail address. If @scheme[obfuscate?] +Combines an author name with an e-mail address. If @racket[obfuscate?] is true, then the result obscures the e-mail address slightly to avoid address-harvesting robots.} @@ -140,23 +140,23 @@ address-harvesting robots.} [pre-content pre-content?] ...) paragraph?]{ Creates a @tech{paragraph} containing the @tech{decode}d - @scheme[pre-content] (i.e., parsed with @scheme[decode-paragraph]). + @racket[pre-content] (i.e., parsed with @racket[decode-paragraph]). - The @scheme[style] argument can be a style, @scheme[#f] to indicate a + The @racket[style] argument can be a style, @racket[#f] to indicate a ``plain'' style, a string that is used as a @tech{style name}, or a symbol that is used as a @tech{style name}. (Note that - @scheme[section] and @scheme[para] treat symbols differently as - @scheme[style] arguments.)} + @racket[section] and @racket[para] treat symbols differently as + @racket[style] arguments.)} @defproc[(nested [#:style style (or/c style? string? symbol? #f)] [pre-flow pre-flow?] ...) nested-flow?]{ Creates a @tech{nested flow} containing the @tech{decode}d - @scheme[pre-flow] (i.e., parsed with @scheme[decode-flow]). + @racket[pre-flow] (i.e., parsed with @racket[decode-flow]). - The @scheme[style] argument is handled the same as @scheme[para]. - The @scheme['inset] style causes the nested flow to be inset compared + The @racket[style] argument is handled the same as @racket[para]. + The @racket['inset] style causes the nested flow to be inset compared to surrounding text.} @@ -175,25 +175,25 @@ of inlined.} [#:style style (or/c style? string? symbol? #f) #f]) itemization?]{ - Constructs an @scheme[itemization] given a sequence of items - constructed by @scheme[item]. + Constructs an @racket[itemization] given a sequence of items + constructed by @racket[item]. - The @scheme[style] argument is handled the same as @scheme[para]. The - @scheme['ordered] style numbers items, instead of just using a + The @racket[style] argument is handled the same as @racket[para]. The + @racket['ordered] style numbers items, instead of just using a bullet.} @defproc[(item [pre-flow pre-flow?] ...) item?]{ -Creates an item for use with @scheme[itemlist]. The @tech{decode}d -@scheme[pre-flow] (i.e., parsed with @scheme[decode-flow]) is the item +Creates an item for use with @racket[itemlist]. The @tech{decode}d +@racket[pre-flow] (i.e., parsed with @racket[decode-flow]) is the item content.} @defproc[(item? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is an item produced by -@scheme[item], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is an item produced by +@racket[item], @racket[#f] otherwise.} @defproc[(tabular [cells (listof (listof (or/c block? content? 'cont)))] @@ -204,29 +204,29 @@ Creates a @tech{table} with the given content, which is supplies as a list of rows, where each row has a list of cells. The length of all rows must match. -Use @scheme['cont] as a cell to continue the content of the preceding +Use @racket['cont] as a cell to continue the content of the preceding cell in a row in the space that would otherwise be used for a new -cell. A @scheme['cont] must not appear as the first cell in a row. +cell. A @racket['cont] must not appear as the first cell in a row. -The @scheme[style] argument is handled the same as @scheme[para].} +The @racket[style] argument is handled the same as @racket[para].} @defproc[(verbatim [#:indent indent exact-nonnegative-integer? 0] [str string?] ...+) block?]{ -Typesets @scheme[str]s in typewriter font with the linebreaks -specified by newline characters in @scheme[str]. Consecutive spaces in -the @scheme[str]s are converted to @scheme[hspace] to ensure that they +Typesets @racket[str]s in typewriter font with the linebreaks +specified by newline characters in @racket[str]. Consecutive spaces in +the @racket[str]s are converted to @racket[hspace] to ensure that they are all preserved in the output. Additional space (via -@scheme[hspace]) as specified by @scheme[indent] is added to the +@racket[hspace]) as specified by @racket[indent] is added to the beginning of each line. -The @scheme[str]s are @emph{not} decoded with @scheme[decode-content], -so @scheme[(verbatim "---")] renders with three hyphens instead of an -em-dash. Beware, however, that @litchar["@"] for a @scheme[verbatim] +The @racket[str]s are @emph{not} decoded with @racket[decode-content], +so @racket[(verbatim "---")] renders with three hyphens instead of an +em-dash. Beware, however, that @litchar["@"] for a @racket[verbatim] call performs some processing before delivering arguments to -@scheme[verbatim]. The @scheme[verbatim] form is typically used with +@racket[verbatim]. The @racket[verbatim] form is typically used with @litchar["|{"]...@litchar["}|"] or similar brackets to disable -@litchar["@"] notation within the @scheme[verbatim] argument, like +@litchar["@"] notation within the @racket[verbatim] argument, like this: @verbatim[#:indent 2]|{ @@ -245,7 +245,7 @@ Even with @litchar["|{"]...@litchar["}|"], beware that consistent leading whitespace is removed; see @secref["alt-body-syntax"] for more information. -See also @scheme[literal].} +See also @racket[literal].} @; ------------------------------------------------------------------------ @@ -255,8 +255,8 @@ See also @scheme[literal].} [#:style style (or style? string? symbol? #f) #f]) element?]{ -Wraps the @tech{decode}d @scheme[pre-content] as an element with style -@scheme[style].} +Wraps the @tech{decode}d @racket[pre-content] as an element with style +@racket[style].} @def-style-proc[italic] @@ -265,35 +265,35 @@ Wraps the @tech{decode}d @scheme[pre-content] as an element with style @def-style-proc[subscript] @def-style-proc[superscript] -@def-elem-proc[smaller]{Like @scheme[elem], but with style -@scheme['smaller]. When uses of @scheme[smaller] are nested, text +@def-elem-proc[smaller]{Like @racket[elem], but with style +@racket['smaller]. When uses of @racket[smaller] are nested, text gets progressively smaller.} -@def-elem-proc[larger]{Like @scheme[elem], but with style -@scheme['larger]. When uses of @scheme[larger] are nested, text +@def-elem-proc[larger]{Like @racket[elem], but with style +@racket['larger]. When uses of @racket[larger] are nested, text gets progressively larger.} @defproc[(emph [pre-content pre-content?] ...) element?]{ -The same as @scheme[italic].} +The same as @racket[italic].} @defproc[(linebreak) element?]{ Produces an element that forces a line break.} @defproc[(hspace [n exact-nonnegative-integer?]) element?]{ -Produces an element containing @scheme[n] spaces and style -@scheme['hspace].} +Produces an element containing @racket[n] spaces and style +@racket['hspace].} @defproc[(literal [str string?] ...+) element?]{ -Produces an element containing literally @scheme[str]s with no -decoding via @scheme[decode-content]. +Produces an element containing literally @racket[str]s with no +decoding via @racket[decode-content]. -Beware that @litchar["@"] for a @scheme[literal] call performs some -processing before delivering arguments to @scheme[literal]. The -@scheme[literal] form can be used with @litchar["|{"]...@litchar["}|"] +Beware that @litchar["@"] for a @racket[literal] call performs some +processing before delivering arguments to @racket[literal]. The +@racket[literal] form can be used with @litchar["|{"]...@litchar["}|"] or similar brackets to disable @litchar["@"] notation within the -@scheme[literal] argument, like this: +@racket[literal] argument, like this: @verbatim[#:indent 2]|{ @literal|{@bold{---}}| @@ -305,7 +305,7 @@ which renders as @literal|{@bold{---}}| }| -See also @scheme[verbatim].} +See also @racket[verbatim].} @defproc[(image [path (or/c path-string? (cons/c 'collects (listof bytes?)))] @@ -315,21 +315,21 @@ See also @scheme[verbatim].} element?]{ Creates an image element from the given path. The @tech{decode}d - @scheme[pre-content] serves as the alternate text for contexts where + @racket[pre-content] serves as the alternate text for contexts where the image cannot be displayed. The path is relative to the current directory, which is set by @exec{setup-plt} and @exec{scribble} to the directory of the main - document file. The @scheme[path] argument also can be a result of - @scheme[path->main-collects-relative]. + document file. The @racket[path] argument also can be a result of + @racket[path->main-collects-relative]. - The strings in @scheme[suffixes] are filtered to those supported by + The strings in @racket[suffixes] are filtered to those supported by given renderer, and then the acceptable suffixes are tried in - order. The HTML renderer supports @scheme[".png"] and - @scheme[".gif"], while the Latex renderer supports @scheme[".png"], - @scheme[".pdf"], and @scheme[".ps"] (but @scheme[".ps"] works only - when converting Latex output to DVI, and @scheme[".png"] and - @scheme[".pdf"] work only for converting Latex output to PDF).} + order. The HTML renderer supports @racket[".png"] and + @racket[".gif"], while the Latex renderer supports @racket[".png"], + @racket[".pdf"], and @racket[".ps"] (but @racket[".ps"] works only + when converting Latex output to DVI, and @racket[".png"] and + @racket[".pdf"] work only for converting Latex output to PDF).} @; ------------------------------------------------------------------------ @@ -340,9 +340,9 @@ See also @scheme[verbatim].} [#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")]) element?]{ -The @tech{decode}d @scheme[pre-content] is hyperlinked to -@scheme[url]. If @scheme[style] is not supplied, then -@scheme[underline?] determines how the link is rendered.} +The @tech{decode}d @racket[pre-content] is hyperlinked to +@racket[url]. If @racket[style] is not supplied, then +@racket[underline?] determines how the link is rendered.} @defproc[(url [dest string?]) element?]{ @@ -356,27 +356,27 @@ Generates a literal hyperlinked URL.} [#:underline? underline? any/c #t]) element?]{ -Inserts the hyperlinked title of the section tagged @scheme[tag], but -elements in the title content with the @scheme['aux] @tech{style property} +Inserts the hyperlinked title of the section tagged @racket[tag], but +elements in the title content with the @racket['aux] @tech{style property} are omitted in the hyperlink label. -If @scheme[#:doc module-path] is provided, the @scheme[tag] refers to -a tag with a prefix determined by @scheme[module-path]. When +If @racket[#:doc module-path] is provided, the @racket[tag] refers to +a tag with a prefix determined by @racket[module-path]. When @exec{setup-plt} renders documentation, it automatically adds a tag prefix to the document based on the source module. Thus, for example, -to refer to a section of the PLT Scheme reference, -@scheme[module-path] would be @scheme['(lib +to refer to a section of the Racket reference, +@racket[module-path] would be @racket['(lib "scribblings/reference/reference.scrbl")]. -The @scheme[#:tag-prefixes prefixes] argument similarly supports +The @racket[#:tag-prefixes prefixes] argument similarly supports selecting a particular section as determined by a path of tag -prefixes. When a @scheme[#:doc] argument is provided, then -@scheme[prefixes] should trace a path of tag-prefixed subsections to -reach the @scheme[tag] section. When @scheme[#:doc] is not provided, -the @scheme[prefixes] path is relative to any enclosing section (i.e., +prefixes. When a @racket[#:doc] argument is provided, then +@racket[prefixes] should trace a path of tag-prefixed subsections to +reach the @racket[tag] section. When @racket[#:doc] is not provided, +the @racket[prefixes] path is relative to any enclosing section (i.e., the youngest ancestor that produces a match). -If @scheme[underline?] is @scheme[#f], then the hyperlink is rendered +If @racket[underline?] is @racket[#f], then the hyperlink is rendered in HTML without an underline.} @@ -386,37 +386,37 @@ in HTML without an underline.} [#:underline? underline? any/c #t] [pre-content pre-content?] ...) element?]{ -Like @scheme[secref], but the link label is the @tech{decode}d -@scheme[pre-content] instead of the target section's name.} +Like @racket[secref], but the link label is the @tech{decode}d +@racket[pre-content] instead of the target section's name.} @defproc[(other-doc [module-path module-path?] [#:underline? underline? any/c #t]) element?]{ -Like @scheme[secref] for the document's implicit @scheme["top"] +Like @racket[secref] for the document's implicit @racket["top"] tag. Use this function to refer to a whole manual instead of -@scheme[secref], in case a special style in the future is used for +@racket[secref], in case a special style in the future is used for manual titles.} @defproc[(elemtag [t (or/c tag? string?)] [pre-content pre-content?] ...) element?]{ -The tag @scheme[t] refers to the content form of -@scheme[pre-content].} +The tag @racket[t] refers to the content form of +@racket[pre-content].} @defproc[(elemref [t (or/c tag? string?)] [pre-content pre-content?] ... [#:underline? underline? any/c #t]) element?]{ -The @tech{decode}d @scheme[pre-content] is hyperlinked to @scheme[t], -which is normally defined using @scheme[elemtag].} +The @tech{decode}d @racket[pre-content] is hyperlinked to @racket[t], +which is normally defined using @racket[elemtag].} @defproc[(module-path-prefix->string [mod-path module-path?]) string?]{ Converts a module path to a string by resolving it to a path, and -using @scheme[path->main-collects-relative].} +using @racket[path->main-collects-relative].} @; ------------------------------------------------------------------------ @@ -427,16 +427,16 @@ using @scheme[path->main-collects-relative].} index-element?]{ Creates an index element given a plain-text string---or list of -strings for a hierarchy, such as @scheme['("strings" "plain")] for a +strings for a hierarchy, such as @racket['("strings" "plain")] for a ``plain'' entry below a more general ``strings'' entry. As index keys, -the strings are ``cleaned'' using @scheme[clean-up-index-strings]. The +the strings are ``cleaned'' using @racket[clean-up-index-strings]. The strings (without clean-up) also serve as the text to render in the -index. The @tech{decode}d @scheme[pre-content] is the text to appear +index. The @tech{decode}d @racket[pre-content] is the text to appear inline as the index target. -Use @scheme[index] when an index entry should point to a specific word +Use @racket[index] when an index entry should point to a specific word or phrase within the typeset document (i.e., the -@scheme[pre-content]). Use @scheme[section-index], instead, to create +@racket[pre-content]). Use @racket[section-index], instead, to create an index entry that leads to a section, instead of a specific word or phrase within the section.} @@ -445,23 +445,23 @@ phrase within the section.} [word-contents (listof list?)] [pre-content pre-content?] ...) index-element?]{ -Like @scheme[index], except that @scheme[words] must be a list, and +Like @racket[index], except that @racket[words] must be a list, and the list of contents render in the index (in parallel to -@scheme[words]) is supplied as @scheme[word-contents]. +@racket[words]) is supplied as @racket[word-contents]. } @defproc[(as-index [pre-content pre-content?] ...) index-element?]{ -Like @scheme[index], but the word to index is determined by applying -@scheme[content->string] on the @tech{decode}d @scheme[pre-content].} +Like @racket[index], but the word to index is determined by applying +@racket[content->string] on the @tech{decode}d @racket[pre-content].} @defproc[(section-index [word string?] ...) part-index-decl?]{ -Creates a @scheme[part-index-decl] to be associated with the enclosing -section by @scheme[decode]. The @scheme[word]s serve as both the keys +Creates a @racket[part-index-decl] to be associated with the enclosing +section by @racket[decode]. The @racket[word]s serve as both the keys and as the rendered forms of the keys within the index.} @@ -469,7 +469,7 @@ and as the rendered forms of the keys within the index.} part?]{ Produces a part that shows the index the enclosing document. The -optional @scheme[tag] argument is used as the index section's tag.} +optional @racket[tag] argument is used as the index section's tag.} @; ------------------------------------------------------------------------ @@ -491,10 +491,10 @@ for the enclosing section, depending on the output type. For multi-page HTML output, the flow element is a table of contents; for Latex output, the flow element is empty. -The meaning of the @scheme[style] argument depends on the output type, -but @scheme['immediate-only] normally creates a table of contents that +The meaning of the @racket[style] argument depends on the output type, +but @racket['immediate-only] normally creates a table of contents that contains only immediate sub-sections of the enclosing section. See -also the @scheme['quiet] style of @scheme[part] (i.e., in a -@scheme[part] structure, not supplied as the @scheme[style] argument -to @scheme[local-table-of-contents]), which normally suppresses +also the @racket['quiet] style of @racket[part] (i.e., in a +@racket[part] structure, not supplied as the @racket[style] argument +to @racket[local-table-of-contents]), which normally suppresses sub-part entries in a table of contents.} diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl index 8eebd3de..2b94d9f6 100644 --- a/collects/scribblings/scribble/basic.scrbl +++ b/collects/scribblings/scribble/basic.scrbl @@ -7,15 +7,15 @@ @title[#:tag "basic"]{Compatibility Basic Functions} -@defmodule[scribble/basic]{The @schememodname[scribble/basic] +@defmodule[scribble/basic]{The @racketmodname[scribble/basic] compatibility library mostly just re-exports -@schememodname[scribble/base].} +@racketmodname[scribble/base].} @defproc[(span-class [style-name string?] [pre-content any/c] ...) element?]{ @compat[] Wraps the @tech{decode}d -@scheme[pre-content] as an element with style @scheme[style-name].} +@racket[pre-content] as an element with style @racket[style-name].} @@ -23,5 +23,5 @@ compatibility library mostly just re-exports [#:style style (or/c style? string? symbol? #f) #f]) itemization?]{ -@compat[] Like @scheme[itemlist], but whitespace strings among the -@scheme[itm]s are ignored.} +@compat[] Like @racket[itemlist], but whitespace strings among the +@racket[itm]s are ignored.} diff --git a/collects/scribblings/scribble/bnf.scrbl b/collects/scribblings/scribble/bnf.scrbl index a8dc78af..46509979 100644 --- a/collects/scribblings/scribble/bnf.scrbl +++ b/collects/scribblings/scribble/bnf.scrbl @@ -5,17 +5,17 @@ @title[#:tag "bnf"]{BNF Grammars} -@defmodule[scribble/bnf]{The @scheme[scribble/bnf] library +@defmodule[scribble/bnf]{The @racket[scribble/bnf] library provides utilities for typesetting grammars.} -See also @scheme[schemegrammar]. +See also @racket[racketgrammar]. @defproc[(BNF [prod (cons element? (listof element?))] ...) table?]{ Typesets a grammar table. Each production starts with an element -(typically constructed with @scheme[nonterm]) for the non-terminal +(typically constructed with @racket[nonterm]) for the non-terminal being defined, and then a list of possibilities (typically constructed -with @scheme[BNF-seq], etc.) to show on separate lines.} +with @racket[BNF-seq], etc.) to show on separate lines.} @defproc[(nonterm (pre-content any/c) ...) element?]{ @@ -44,15 +44,15 @@ Typesets a 1-or-more repetition.} @defproc[(kleenerange [n any/c] [m any/c] [pre-content any/c] ...) element?]{ -Typesets a @scheme[n]-to-@scheme[m] repetition. The @scheme[n] and -@scheme[m] arguments are converted to a string using @scheme[(format -"~a" n)] and @scheme[(format "~a" m)].} +Typesets a @racket[n]-to-@racket[m] repetition. The @racket[n] and +@racket[m] arguments are converted to a string using @racket[(format +"~a" n)] and @racket[(format "~a" m)].} @defproc[(BNF-alt [elem element?] ...) element?]{ Typesets alternatives for a production's right-hand side to appear on a single line. The result is normally used as a single possibility in -a production list for @scheme[BNF].} +a production list for @racket[BNF].} @defthing[BNF-etc string?]{ diff --git a/collects/scribblings/scribble/core.scrbl b/collects/scribblings/scribble/core.scrbl index a1e34162..321e14a7 100644 --- a/collects/scribblings/scribble/core.scrbl +++ b/collects/scribblings/scribble/core.scrbl @@ -22,17 +22,17 @@ A document is processed in three passes. The first pass is the contribute new hyperlink targets). The final pass is the @deftech{render pass}, which generates the resulting document. None of the passes mutate the document, but instead collect information in - side @scheme[collect-info] and @scheme[resolve-info] tables. + side @racket[collect-info] and @racket[resolve-info] tables. @; ------------------------------------------------------------------------ @section[#:tag "parts"]{Parts} -A @deftech{part} is an instance of @scheme[part]; among other things, +A @deftech{part} is an instance of @racket[part]; among other things, it has a title @techlink{content}, an initial @techlink{flow}, and a list of subsection @techlink{parts}. There is no difference between a part and a full document; a particular source module just as easily - defines a subsection (incorporated via @scheme[include-section]) as a + defines a subsection (incorporated via @racket[include-section]) as a document. A @deftech{flow} is a list of @techlink{blocks}. @@ -43,25 +43,25 @@ A @deftech{block} is either a @techlink{table}, an @itemize[ - @item{A @deftech{table} is an instance of @scheme[table]; it + @item{A @deftech{table} is an instance of @racket[table]; it has a list of list of @techlink{blocks} corresponding to table cells.} - @item{A @deftech{itemization} is an instance of @scheme[itemization]; + @item{A @deftech{itemization} is an instance of @racket[itemization]; it has a list of @techlink{flows}.} @item{A @deftech{nested flow} is an instance of - @scheme[nested-flow]; it has a @tech{flow} that + @racket[nested-flow]; it has a @tech{flow} that is typeset as sub-flow.} @item{A @deftech{paragraph} is an instance of - @scheme[paragraph]; it has a @tech{content}: + @racket[paragraph]; it has a @tech{content}: @itemize[ @item{An @deftech{content} can be a string, one of a few - symbols, an instance of @scheme[element] (possibly - @scheme[link-element], etc.), a @scheme[multiarg-element], a + symbols, an instance of @racket[element] (possibly + @racket[link-element], etc.), a @racket[multiarg-element], a @techlink{part-relative element}, a @techlink{delayed element}, or a list of content. @@ -70,62 +70,62 @@ A @deftech{block} is either a @techlink{table}, an @item{A string is included in the result document verbatim, except for space, and unless the content's enclosing @tech{style} is - @scheme['hspace]. In a style other than - @scheme['hspace], consecutive spaces in the + @racket['hspace]. In a style other than + @racket['hspace], consecutive spaces in the output may be collapsed togther or replaced with a line break. In the style - @scheme['hspace], all text is converted to + @racket['hspace], all text is converted to uncollapsable spaces that cannot be broken across lines.} - @item{A symbol content is either @scheme['mdash], - @scheme['ndash], @scheme['ldquo], - @scheme['lsquo], @scheme['rsquo], @scheme['larr], - @scheme['rarr], or @scheme['prime]; it is + @item{A symbol content is either @racket['mdash], + @racket['ndash], @racket['ldquo], + @racket['lsquo], @racket['rsquo], @racket['larr], + @racket['rarr], or @racket['prime]; it is rendered as the corresponding HTML entity (even for Latex output).} - @item{An instance of @scheme[element] has a + @item{An instance of @racket[element] has a @techlink{content} plus a @tech{style}. The style's interpretation depends on the renderer, but it can be one of a few special symbols (such as - @scheme['bold]) that are recognized by all + @racket['bold]) that are recognized by all renderers.} - @item{An instance of @scheme[link-element] has a + @item{An instance of @racket[link-element] has a @techlink{tag} for the target of the link.} - @item{An instance of @scheme[target-element] has a + @item{An instance of @racket[target-element] has a @techlink{tag} to be referenced by - @scheme[link-element]s. An instance of the - subtype @scheme[toc-target-element] is + @racket[link-element]s. An instance of the + subtype @racket[toc-target-element] is treated like a kind of section label, to be shown in the ``on this page'' table for HTML output.} - @item{An instance of @scheme[index-element] has a + @item{An instance of @racket[index-element] has a @techlink{tag} (as a target), a list of strings for the keywords (for sorting and search), and a list of @techlink{contents} to appear in the end-of-document index.} - @item{An instance of @scheme[image-element] + @item{An instance of @racket[image-element] incorporates an image from a file into the rendered document.} - @item{An instance of @scheme[multiarg-element] + @item{An instance of @racket[multiarg-element] combines a style with a list of content, where the style corresponds to a rendered command that takes multiple arguments.} - @item{An instance of @scheme[collect-element] has a + @item{An instance of @racket[collect-element] has a procedure that is called in the @techlink{collect pass} of document processing to record information used by later passes.} @item{A @deftech{part-relative element} is an - instance of @scheme[part-relative-element], + instance of @racket[part-relative-element], which has a procedure that is called in the @techlink{collect pass} of document processing to obtain @defterm{content}. When the @@ -135,12 +135,12 @@ A @deftech{block} is either a @techlink{table}, an available.} @item{A @deftech{delayed element} is an instance of - @scheme[delayed-element], which has a + @racket[delayed-element], which has a procedure that is called in the @techlink{resolve pass} of document processing to obtain @defterm{content}.} - @item{An instance of @scheme[render-element] has a + @item{An instance of @racket[render-element] has a procedure that is called in the @techlink{render pass} of document processing.} @@ -148,13 +148,13 @@ A @deftech{block} is either a @techlink{table}, an ]}]} @item{A @deftech{compound paragraph} is an instance of - @scheme[compound-paragraph]; like @scheme[blockquote], it + @racket[compound-paragraph]; like @racket[blockquote], it has list of @tech{blocks}, but the blocks are typeset as a single paragraph (e.g., no indentation after the first block) instead of inset.} @item{A @deftech{delayed block} is an instance of - @scheme[delayed-block], which has a procedure that + @racket[delayed-block], which has a procedure that is called in the @techlink{resolve pass} of document processing to obtain a @defterm{block}.} @@ -165,20 +165,20 @@ A @deftech{block} is either a @techlink{table}, an @section[#:tag "tags"]{Tags} A @deftech{tag} is a list containing a symbol and either a string, a -@scheme[generated-tag] instance, or an arbitrary list. The symbol -effectively identifies the type of the tag, such as @scheme['part] for -a tag that links to a part, or @scheme['def] for a Scheme function +@racket[generated-tag] instance, or an arbitrary list. The symbol +effectively identifies the type of the tag, such as @racket['part] for +a tag that links to a part, or @racket['def] for a Racket function definition. The symbol also effectively determines the interpretation of the second half of the tag. A part can have a @deftech{tag prefix}, which is effectively added onto the second item within each tag whose first item is -@scheme['part] or @scheme['tech]. The prefix is added to a string +@racket['part] or @racket['tech]. The prefix is added to a string value by creating a list containing the prefix and string, and it is -added to a list value using @scheme[cons]; a prefix is not added to a -@scheme[generated-tag] instance. The prefix is used for reference +added to a list value using @racket[cons]; a prefix is not added to a +@racket[generated-tag] instance. The prefix is used for reference outside the part, including the use of tags in the part's -@scheme[tags] field. Typically, a document's main part has a tag +@racket[tags] field. Typically, a document's main part has a tag prefix that applies to the whole document; references to sections and defined terms within the document from other documents must include the prefix, while references within the same document omit the prefix. Part @@ -187,18 +187,18 @@ references within the document. Some procedures accept a ``tag'' that is just the string part of the full tag, where the symbol part is supplied automatically. For -example, @scheme[section] and @scheme[secref] both accept a string -``tag'', where @scheme['part] is implicit. +example, @racket[section] and @racket[secref] both accept a string +``tag'', where @racket['part] is implicit. @; ------------------------------------------------------------------------ @section[#:tag "style"]{Styles} A @deftech{style} combines a @tech{style name} with a list of -@tech{style properties} in a @scheme[style] structure. A @deftech{style name} -is either a string, symbol, of @scheme[#f]. A @deftech{style property} can be +@tech{style properties} in a @racket[style] structure. A @deftech{style name} +is either a string, symbol, of @racket[#f]. A @deftech{style property} can be anything, including a symbol a structure such as -@scheme[color-property]. +@racket[color-property]. A style has a single @tech{style name}, because the name typically corresponds to a configurable instruction to a renderer. For example, @@ -207,14 +207,14 @@ or environment. For more information on how string style names interact with configuration of a renderer, see @secref["config"]. Symbolic style names, meanwhile, provide a simple layer of abstraction between the renderer and documents for widely -supported style; for example, the @scheme['italic] style name is +supported style; for example, the @racket['italic] style name is supported by all renderers. @tech{Style properties} within a style compose with style names and other properties. Again, symbols are often used for properties that are directly -supported by renderers. For example, @scheme['unnumbered] style +supported by renderers. For example, @racket['unnumbered] style property for a @tech{part} renders the part without a section number. -Many properties are renderer-specific, such as a @scheme[hover-property] +Many properties are renderer-specific, such as a @racket[hover-property] structure that associates text with an element to be shown in an HTML display when the mouse hovers over the text. @@ -225,35 +225,35 @@ HTML display when the mouse hovers over the text. The @techlink{collect pass}, @techlink{resolve pass}, and @techlink{render pass} processing steps all produce information that is specific to a rendering mode. Concretely, the operations are all -represented as methods on a @scheme[render%] object. +represented as methods on a @racket[render%] object. The result of the @method[render% collect] method is a -@scheme[collect-info] instance. This result is provided back as an +@racket[collect-info] instance. This result is provided back as an argument to the @method[render% resolve] method, which produces a -@scheme[resolve-info] value that encapsulates the results from both -iterations. The @scheme[resolve-info] value is provided back to the +@racket[resolve-info] value that encapsulates the results from both +iterations. The @racket[resolve-info] value is provided back to the @method[render% resolve] method for final rendering. Optionally, before the @method[render% resolve] method is called, serialized information from other documents can be folded into the -@scheme[collect-info] instance via the @method[render% +@racket[collect-info] instance via the @method[render% deserialize-info] method. Other methods provide serialized information out of the collected and resolved records. During the @techlink{collect pass}, the procedure associated with a -@scheme[collect-element] instance can register information with -@scheme[collect-put!]. +@racket[collect-element] instance can register information with +@racket[collect-put!]. During the @techlink{resolve pass}, collected information for a part -can be extracted with @scheme[part-collected-info], which includes a -part's number and its parent part (or @scheme[#f]). More generally, -the @scheme[resolve-get] method looks up information previously +can be extracted with @racket[part-collected-info], which includes a +part's number and its parent part (or @racket[#f]). More generally, +the @racket[resolve-get] method looks up information previously collected. This resolve-time information is normally obtained by the procedure associated with a @techlink{delayed block} or @techlink{delayed element}. -The @scheme[resolve-get] information accepts both a @scheme[part] and -a @scheme[resolve-info] argument. The @scheme[part] argument enables +The @racket[resolve-get] information accepts both a @racket[part] and +a @racket[resolve-info] argument. The @racket[part] argument enables searching for information in each enclosing part before sibling parts. @; ------------------------------------------------------------------------ @@ -268,20 +268,20 @@ searching for information in each enclosing part before sibling parts. [blocks (listof block?)] [parts (listof part?)])]{ -The @scheme[tag-prefix] field determines the optional @techlink{tag +The @racket[tag-prefix] field determines the optional @techlink{tag prefix} for the part. -The @scheme[tags] indicates a list of @techlink{tags} that each link +The @racket[tags] indicates a list of @techlink{tags} that each link to the section. -The @scheme[title-content] field holds the part's title, if any. +The @racket[title-content] field holds the part's title, if any. -For the @scheme[style] field, the currently recognized symbolic style +For the @racket[style] field, the currently recognized symbolic style names are as follows: @itemize[ - @item{@scheme['index] --- The part represents an index.} + @item{@racket['index] --- The part represents an index.} ] @@ -289,63 +289,63 @@ The recognized @tech{style properties} are as follows: @itemize[ - @item{@scheme['unnumbered] --- A section number is computed for an + @item{@racket['unnumbered] --- A section number is computed for an unnumbered section during the @techlink{collect pass}, but the number is not rendered.} - @item{@scheme['toc] --- Sub-parts of the part are rendered on separate + @item{@racket['toc] --- Sub-parts of the part are rendered on separate pages for multi-page HTML mode.} - @item{@scheme['non-toc] --- Initial sub-parts of the part are + @item{@racket['non-toc] --- Initial sub-parts of the part are @emph{not} rendered on separate pages for multi-page HTML mode; this style applies only to the main part.} - @item{@scheme['reveal] --- Shows sub-parts when this part is + @item{@racket['reveal] --- Shows sub-parts when this part is displayed in a table-of-contents panel in HTML output (which normally shows only the top-level sections).} - @item{@scheme['hidden] --- The part title is not shown in rendered + @item{@racket['hidden] --- The part title is not shown in rendered HTML output.} - @item{@scheme['quiet] --- In HTML output and most other output modes, + @item{@racket['quiet] --- In HTML output and most other output modes, hides entries for sub-parts of this part in a - @scheme[table-of-contents] or @scheme[local-table-of-contents] + @racket[table-of-contents] or @racket[local-table-of-contents] listing except when those sub-parts are top-level entries in the listing.} - @item{@scheme['no-toc] --- As a style for the main part of a + @item{@racket['no-toc] --- As a style for the main part of a document, causes the HTML output to not include a margin box for the main table of contents; the ``on this page'' box that - contains @scheme[toc-element] and @scheme[toc-target-element] + contains @racket[toc-element] and @racket[toc-target-element] links (and that only includes an ``on this page'' label for multi-page documents) takes on the location and color of the main table of contents, instead.} - @item{@scheme[document-version] structure --- A version number for + @item{@racket[document-version] structure --- A version number for this part and its sub-parts (except as overridden). When it is - not @scheme[""] may be used when rendering a document; at a - minimum, a non-@scheme[""] version is rendered when it is + not @racket[""] may be used when rendering a document; at a + minimum, a non-@racket[""] version is rendered when it is attached to a part representing the whole document. The default - version for a document is @scheme[(version)].} + version for a document is @racket[(version)].} - @item{@scheme[body-id] structure --- Generated HTML uses the given + @item{@racket[body-id] structure --- Generated HTML uses the given string @tt{id} attribute of the @tt{body} tag; this style can be set separately for parts that start different HTML pages, otherwise it is effectively inherited by sub-parts; the - default is @scheme["scribble-plt-scheme.org"], but - @exec{setup-plt} installs @scheme["doc-plt-scheme.org"] as the + default is @racket["scribble-plt-scheme.org"], but + @exec{setup-plt} installs @racket["doc-plt-scheme.org"] as the @tt{id} for any document that it builds.} ] -The @scheme[to-collect] field contains @techlink{content} that is +The @racket[to-collect] field contains @techlink{content} that is inspected during the @techlink{collect pass}, but ignored in later passes (i.e., it doesn't directly contribute to the output). -The @scheme[blocks] field contains the part's initial flow (before +The @racket[blocks] field contains the part's initial flow (before sub-parts). -The @scheme[parts] field contains sub-parts. +The @racket[parts] field contains sub-parts. } @@ -354,16 +354,16 @@ The @scheme[parts] field contains sub-parts. A @techlink{paragraph} has a @tech{style} and a @tech{content}. -For the @scheme[style] field, a string @tech{style name} corresponds +For the @racket[style] field, a string @tech{style name} corresponds to a CSS class for HTML output or a macro for Latex output (see @secref["extra-style"]). The following symbolic @tech{style names} are recognized: @itemize[ - @item{@scheme['author] --- Typeset as the author of a document. Such + @item{@racket['author] --- Typeset as the author of a document. Such paragraphs normally should appear only in the initial flow of a - @scheme[part] for a document, where they are treated specially + @racket[part] for a document, where they are treated specially by the Latex renderer by moving the author information to the title.} @@ -373,21 +373,21 @@ The currently recognized @tech{style properties} are as follows: @itemize[ - @item{@scheme['omitable] --- When a table cell contains a single - @scheme[omitable-paragraph], then when rendering to HTML, no + @item{@racket['omitable] --- When a table cell contains a single + @racket[omitable-paragraph], then when rendering to HTML, no @tt{p} tag wraps the cell content.} - @item{@scheme['div] --- Generates @tt{
} HTML output instead of + @item{@racket['div] --- Generates @tt{
} HTML output instead of @tt{

}.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{

} or @tt{

} tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{

} or @tt{

} tag.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ]} @@ -396,20 +396,20 @@ The currently recognized @tech{style properties} are as follows: [blockss (listof (listof (or/c block? (one-of/c 'cont))))])]{ A @techlink{table} has, roughly, a list of list of blocks. A cell in -the table can span multiple columns by using @scheme['cont] instead of +the table can span multiple columns by using @racket['cont] instead of a block in the following columns (i.e., for all but the first in a set of cells that contain a single block). -Within @scheme[style], a string @tech{style name} corresponds to a CSS +Within @racket[style], a string @tech{style name} corresponds to a CSS class for HTML output or an environment for Latex output (see @secref["extra-style"]). The following symbolic style names are also recognized: @itemize[ - @item{@scheme['boxed] --- Renders as a definition.} + @item{@racket['boxed] --- Renders as a definition.} - @item{@scheme['centered] --- Centers HTML output horizontally.} + @item{@racket['centered] --- Centers HTML output horizontally.} ] @@ -417,36 +417,36 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme[table-columns] structure --- Provides column-specific - styles, but only if a @scheme[table-cells] structure is not + @item{@racket[table-columns] structure --- Provides column-specific + styles, but only if a @racket[table-cells] structure is not included as a @tech{style property}.} - @item{@scheme[table-cells] structure --- Provides cell-specific + @item{@racket[table-cells] structure --- Provides cell-specific styles.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{} tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{
} tag.} - @item{@scheme['aux] --- For HTML, include the table in the + @item{@racket['aux] --- For HTML, include the table in the table-of-contents display for the enclosing part.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ] For Latex output, a paragraph as a cell value is not automatically line-wrapped, unless a vertical alignment is specified for the cell -through a @scheme[table-cells] or @scheme[table-columns] +through a @racket[table-cells] or @racket[table-columns] @tech{style property}. To get a line-wrapped paragraph, use a -@scheme[compound-paragraph] or use an element with a string style and +@racket[compound-paragraph] or use an element with a string style and define a corresponding Latex macro in terms of @tt{parbox}. For Latex -output of blocks in the flow that are @scheme[nested-flow]s, -@scheme[itemization]s, @scheme[compound-paragraph]s, or -@scheme[delayed-block]s, the block is wrapped with @tt{minipage} using +output of blocks in the flow that are @racket[nested-flow]s, +@racket[itemization]s, @racket[compound-paragraph]s, or +@racket[delayed-block]s, the block is wrapped with @tt{minipage} using @tt{linewidth} divided by the column count as the width.} @@ -455,16 +455,16 @@ output of blocks in the flow that are @scheme[nested-flow]s, A @techlink{itemization} has a @tech{style} and a list of @tech{flows}. -In @scheme[style], a string @tech{style name} corresponds to a CSS +In @racket[style], a string @tech{style name} corresponds to a CSS class for HTML output or a macro for Latex output (see @secref["extra-style"]). In addition, the following symbolic style names are recognized: @itemize[ - @item{@scheme['compact] --- Reduces space between items.} + @item{@racket['compact] --- Reduces space between items.} - @item{@scheme['ordered] --- Generates @tt{
    } HTML output instead + @item{@racket['ordered] --- Generates @tt{
      } HTML output instead of @tt{
        } or an Latex enumeration instead of an itemization.} ] @@ -473,14 +473,14 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{
          } or @tt{
            } tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{
              } or @tt{
                } tag.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ]} @@ -490,14 +490,14 @@ The following @tech{style properties} are currently recognized: A @techlink{nested flow} has a style and a @tech{flow}. -In @scheme[style], the @scheme{style name} is normally a string that +In @racket[style], the @racket{style name} is normally a string that corresponds to a CSS class for HTML @tt{blockquote} output or a Latex environment (see @secref["extra-style"]). The following symbolic style names are recognized: @itemize[ - @item{@scheme['inset] --- Insets the nested flow relative to + @item{@racket['inset] --- Insets the nested flow relative to surrounding text.} ] @@ -506,18 +506,18 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme['command] --- For Latex output, a string @tech{style + @item{@racket['command] --- For Latex output, a string @tech{style name} is used as a command name instead of an environment name.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{
                } tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{
                } tag.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ]} @@ -528,33 +528,33 @@ The following @tech{style properties} are currently recognized: A @techlink{compound paragraph} has a @tech{style} and a list of @tech{blocks}. -For HTML, a @scheme[paragraph] block in @scheme[blocks] is rendered +For HTML, a @racket[paragraph] block in @racket[blocks] is rendered without a @tt{

                } tag, unless the paragraph has a style with a -non-@scheme[#f] @tech{style name}. For Latex, each @tech{block} in -@scheme[blocks] is rendered with a preceding @tt{\noindent}, unless -the block has the @scheme['never-indents] property (checking -recursively in a @scheme[nested-flow] or @scheme[compound-paragraph] -if the @scheme[nested-flow] or @scheme[compound-paragraph] itself has -no @scheme['never-indents] property). +non-@racket[#f] @tech{style name}. For Latex, each @tech{block} in +@racket[blocks] is rendered with a preceding @tt{\noindent}, unless +the block has the @racket['never-indents] property (checking +recursively in a @racket[nested-flow] or @racket[compound-paragraph] +if the @racket[nested-flow] or @racket[compound-paragraph] itself has +no @racket['never-indents] property). -The @scheme[style] field of a compound paragraph is normally a string +The @racket[style] field of a compound paragraph is normally a string that corresponds to a CSS class for HTML output or Latex environment for Latex output (see @secref["extra-style"]). The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme['command] --- For Latex output, a string @tech{style + @item{@racket['command] --- For Latex output, a string @tech{style name} is used as a command name instead of an environment name.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{

                } tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{

                } tag.} - @item{@scheme['never-indents] --- For Latex within another + @item{@racket['never-indents] --- For Latex within another @tech{compound paragraph}; see above.} ]} @@ -562,9 +562,9 @@ for Latex output (see @secref["extra-style"]). The following @defstruct[delayed-block ([resolve (any/c part? resolve-info? . -> . block?)])]{ -The @scheme[resolve] procedure is called during the @techlink{resolve +The @racket[resolve] procedure is called during the @techlink{resolve pass} to obtain a normal @tech{block}. The first argument to -@scheme[resolve] is the renderer. +@racket[resolve] is the renderer. } @@ -574,26 +574,26 @@ pass} to obtain a normal @tech{block}. The first argument to Styled @tech{content} within an enclosing @tech{paragraph} or other content. -The @scheme[style] field can be a @scheme[style] structure, but it can +The @racket[style] field can be a @racket[style] structure, but it can also be just a @tech{style name}. -In @scheme[style], a string @tech{style name} corresponds to a CSS +In @racket[style], a string @tech{style name} corresponds to a CSS class for HTML output and a macro name for Latex output (see @secref["extra-style"]). The following symbolic style names are recognized: @itemize[ - @item{@scheme['tt], @scheme['italic], @scheme['bold], @scheme['sf], - @scheme['url], @scheme['subscript], @scheme['superscript], - @scheme['smaller], @scheme['larger] --- + @item{@racket['tt], @racket['italic], @racket['bold], @racket['sf], + @racket['url], @racket['subscript], @racket['superscript], + @racket['smaller], @racket['larger] --- Basic styles recognized by all renders.} - @item{@scheme['hspace] --- Renders its @scheme[content] as monospace + @item{@racket['hspace] --- Renders its @racket[content] as monospace blanks.} - @item{@scheme['newline] --- Renders a line break independent of - the @scheme[content].} + @item{@racket['newline] --- Renders a line break independent of + the @racket[content].} ] @@ -601,39 +601,39 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme[target-url] structure --- Generates a hyperlink.} + @item{@racket[target-url] structure --- Generates a hyperlink.} - @item{@scheme[url-anchor] structure --- For HTML, inserts a hyperlink - target before @scheme[content].} + @item{@racket[url-anchor] structure --- For HTML, inserts a hyperlink + target before @racket[content].} - @item{@scheme[color-property] structure --- Applies a color to the - text of @scheme[content].} + @item{@racket[color-property] structure --- Applies a color to the + text of @racket[content].} - @item{@scheme[background-color-property] structure --- Applies a color to the - background of @scheme[content].} + @item{@racket[background-color-property] structure --- Applies a color to the + background of @racket[content].} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for a @tt{} tag.} - @item{@scheme[hover-property] structure --- For HTML, adds a text + @item{@racket[hover-property] structure --- For HTML, adds a text label to the content to be shown when the mouse hovers over it.} - @item{@scheme[script-property] structure --- For HTML, supplies a - script alternative to @scheme[content].} + @item{@racket[script-property] structure --- For HTML, supplies a + script alternative to @racket[content].} - @item{@scheme[body-id] structure --- For HTML uses the given + @item{@racket[body-id] structure --- For HTML uses the given string as an @tt{id} attribute of the @tt{span} tag.} - @item{@scheme['aux] --- Intended for use in titles, where the + @item{@racket['aux] --- Intended for use in titles, where the auxiliary part of the title can be omitted in hyperlinks. See, - for example, @scheme[secref].} + for example, @racket[secref].} - @item{@scheme['tt-chars] --- For Latex output, when the @tech{style + @item{@racket['tt-chars] --- For Latex output, when the @tech{style name} is a string, render the element's content with escapes suitable for Latex @tt{tt} mode.} - @item{@scheme['exact-chars] --- For Latex output, when the @tech{style + @item{@racket['exact-chars] --- For Latex output, when the @tech{style name} is a string, render the elements content exactly (without escapes).} @@ -645,65 +645,65 @@ The following @tech{style properties} are currently recognized: [suffixes (listof #rx"^[.]")] [scale real?])]{ -Used as a style for an @scheme[element] to inline an image. The -@scheme[path] field can be a result of -@scheme[path->main-collects-relative]. +Used as a style for an @racket[element] to inline an image. The +@racket[path] field can be a result of +@racket[path->main-collects-relative]. -For each string in @scheme[suffixes], if the rendered works with the -corresponding suffix, the suffix is added to @scheme[path] and used if +For each string in @racket[suffixes], if the rendered works with the +corresponding suffix, the suffix is added to @racket[path] and used if the resulting path refers to a file that exists. The order in -@scheme[suffixes] determines the order in which suffixes are -tried. The HTML renderer supports @scheme[".png"] and @scheme[".gif"], -while the Latex renderer supports @scheme[".png"], @scheme[".pdf"], -and @scheme[".ps"] (but rendering Latex output to PDF will not work -with @scheme[".ps"] files, while rendering to Latex DVI output works -only with @scheme[".ps"] files). If @scheme[suffixes] is empty or if -none of the suffixes lead to files that exist, @scheme[path] is used +@racket[suffixes] determines the order in which suffixes are +tried. The HTML renderer supports @racket[".png"] and @racket[".gif"], +while the Latex renderer supports @racket[".png"], @racket[".pdf"], +and @racket[".ps"] (but rendering Latex output to PDF will not work +with @racket[".ps"] files, while rendering to Latex DVI output works +only with @racket[".ps"] files). If @racket[suffixes] is empty or if +none of the suffixes lead to files that exist, @racket[path] is used as-is. -The @scheme[scale] field scales the image in its rendered form.} +The @racket[scale] field scales the image in its rendered form.} @defstruct[(target-element element) ([tag tag?])]{ -Declares the content as a hyperlink target for @scheme[tag].} +Declares the content as a hyperlink target for @racket[tag].} @defstruct[(toc-target-element target-element) ()]{ -Like @scheme[target-element], the content is also a kind of section +Like @racket[target-element], the content is also a kind of section label to be shown in the ``on this page'' table for HTML output.} @defstruct[(page-target-element target-element) ()]{ -Like @scheme[target-element], but a link to the element goes to the +Like @racket[target-element], but a link to the element goes to the top of the containing page.} @defstruct[(redirect-target-element target-element) ([alt-path path-string?] [alt-anchor string?])]{ -Like @scheme[target-element], but a link to the element is redirected +Like @racket[target-element], but a link to the element is redirected to the given URL.} @defstruct[(toc-element element) ([toc-content content?])]{ -Similar to @scheme[toc-target-element], but with specific content for -the ``on this page'' table specified in the @scheme[toc-content] +Similar to @racket[toc-target-element], but with specific content for +the ``on this page'' table specified in the @racket[toc-content] field.} @defstruct[(link-element element) ([tag tag?])]{ -Hyperlinks the content to @scheme[tag]. +Hyperlinks the content to @racket[tag]. -When @scheme[tag] is a part tag and the content of the element is -@scheme[null], then the hyperlink uses the target part's number and/or +When @racket[tag] is a part tag and the content of the element is +@racket[null], then the hyperlink uses the target part's number and/or title as the content. In that case, if the section number is preceded by a word, the word starts in uppercase if the element's style includes a -@scheme['uppercase] property.} +@racket['uppercase] property.} @defstruct[(index-element element) ([tag tag?] @@ -711,57 +711,57 @@ by a word, the word starts in uppercase if the element's style includes a [entry-seq (listof content?)] [desc any/c])]{ -The @scheme[plain-seq] specifies the keys for sorting, where the first +The @racket[plain-seq] specifies the keys for sorting, where the first string is the main key, the second is a sub-key, etc. For example, an ``night'' portion of an index might have sub-entries for ``night, things that go bump in'' and ``night, defender of the''. The -former would be represented by @scheme[plain-seq] @scheme['("night" -"things that go bump in")], and the latter by @scheme['("night" +former would be represented by @racket[plain-seq] @racket['("night" +"things that go bump in")], and the latter by @racket['("night" "defender of the")]. Naturally, single-string -@scheme[plain-seq] lists are the common case, and at least one word is +@racket[plain-seq] lists are the common case, and at least one word is required, but there is no limit to the word-list length. The strings in -@scheme[plain-seq] must not contain a newline character. +@racket[plain-seq] must not contain a newline character. -The @scheme[entry-seq] list must have the same length as -@scheme[plain-seq]. It provides the form of each key to render in the +The @racket[entry-seq] list must have the same length as +@racket[plain-seq]. It provides the form of each key to render in the final document. -The @scheme[desc] field provides additional information about the +The @racket[desc] field provides additional information about the index entry as supplied by the entry creator. For example, a reference -to a procedure binding can be recognized when @scheme[desc] is an -instance of @scheme[procedure-index-desc]. See -@schememodname[scribble/manual-struct] for other typical types of -@scheme[desc] values. +to a procedure binding can be recognized when @racket[desc] is an +instance of @racket[procedure-index-desc]. See +@racketmodname[scribble/manual-struct] for other typical types of +@racket[desc] values. -See also @scheme[index].} +See also @racket[index].} @defstruct[multiarg-element ([style element-style?] [content (listof content?)])]{ -Like @scheme[element] with a list for content, except that for Latex -output, if the @tech{style name} in @scheme[style] is a string, then +Like @racket[element] with a list for content, except that for Latex +output, if the @tech{style name} in @racket[style] is a string, then it corresponds to a Latex command that accepts as many arguments (each -in curly braces) as elements of @scheme[content].} +in curly braces) as elements of @racket[content].} @defstruct[delayed-element ([resolve (any/c part? resolve-info? . -> . list?)] [sizer (-> any/c)] [plain (-> any/c)])]{ -The @scheme[render] procedure's arguments are the same as for -@scheme[delayed-block], but the result is @techlink{content}. -Unlike @scheme[delayed-block], the -result of the @scheme[render] procedure's argument is remembered on +The @racket[render] procedure's arguments are the same as for +@racket[delayed-block], but the result is @techlink{content}. +Unlike @racket[delayed-block], the +result of the @racket[render] procedure's argument is remembered on the first call for re-use for a particular resolve pass. -The @scheme[sizer] field is a procedure that produces a substitute +The @racket[sizer] field is a procedure that produces a substitute @techlink{content} for the delayed element for the purposes of -determining the delayed element's width (see @scheme[element-width]). +determining the delayed element's width (see @racket[element-width]). -The @scheme[plain] field is a procedure that produces a substitute +The @racket[plain] field is a procedure that produces a substitute @techlink{content} when needed before the @techlink{collect pass}, -such as when @scheme[element->string] is used before the @tech{collect +such as when @racket[element->string] is used before the @tech{collect pass}.} @@ -769,35 +769,35 @@ pass}.} [sizer (-> any/c)] [plain (-> any/c)])]{ -Similar to @scheme[delayed-block], but the replacement +Similar to @racket[delayed-block], but the replacement @techlink{content} is obtained in the @techlink{collect pass} by -calling the function in the @scheme[resolve] field. +calling the function in the @racket[resolve] field. -The @scheme[resolve] function can call @scheme[collect-info-parents] +The @racket[resolve] function can call @racket[collect-info-parents] to obtain a list of @techlink{parts} that enclose the element, starting with the nearest enclosing section. Functions like -@scheme[part-collected-info] and @scheme[collected-info-number] can +@racket[part-collected-info] and @racket[collected-info-number] can extract information like the part number.} @defstruct[(collect-element element) ([collect (collect-info . -> . any)])]{ -Like @scheme[element], but the @scheme[collect] procedure is called -during the @techlink{collect pass}. The @scheme[collect] procedure -normally calls @scheme[collect-put!]. +Like @racket[element], but the @racket[collect] procedure is called +during the @techlink{collect pass}. The @racket[collect] procedure +normally calls @racket[collect-put!]. -Unlike @scheme[delayed-element] or @scheme[part-relative-element], the +Unlike @racket[delayed-element] or @racket[part-relative-element], the element remains intact (i.e., it is not replaced) by either the @tech{collect pass} or @tech{resolve pass}.} @defstruct[(render-element element) ([render (any/c part? resolve-info? . -> . any)])]{ -Like @scheme[delayed-element], but the @scheme[render] procedure is called +Like @racket[delayed-element], but the @racket[render] procedure is called during the @techlink{render pass}. -If a @scheme[render-element] instance is serialized (such as when -saving collected info), it is reduced to a @scheme[element] instance.} +If a @racket[render-element] instance is serialized (such as when +saving collected info), it is reduced to a @racket[element] instance.} @defstruct[collected-info ([number (listof (or/c false/c integer?))] @@ -809,35 +809,35 @@ Computed for each part by the @techlink{collect pass}.} @defstruct[target-url ([addr path-string?])]{ -Used as a @tech{style property} for an @scheme[element]. A path is -allowed for @scheme[addr], but a string is interpreted as a URL rather +Used as a @tech{style property} for an @racket[element]. A path is +allowed for @racket[addr], but a string is interpreted as a URL rather than a file path.} @defstruct[document-version ([text (or/c string? false/c)])]{ -Used as a @tech{style property} for a @scheme[path] to indicate a +Used as a @tech{style property} for a @racket[path] to indicate a version number.} @defstruct[color-property ([color (or/c string? (list/c byte? byte? byte?))])]{ -Used as a @tech{style property} for an @scheme[element] to set its -color. Recognized string names for @scheme[color] depend on the +Used as a @tech{style property} for an @racket[element] to set its +color. Recognized string names for @racket[color] depend on the renderer, but at the recognized set includes at least -@scheme["white"], @scheme["black"], @scheme["red"], @scheme["green"], -@scheme["blue"], @scheme["cyan"], @scheme["magenta"], and -@scheme["yellow"]. When @scheme[color] is a list of bytes, the values +@racket["white"], @racket["black"], @racket["red"], @racket["green"], +@racket["blue"], @racket["cyan"], @racket["magenta"], and +@racket["yellow"]. When @racket[color] is a list of bytes, the values are used as RGB levels.} @defstruct[background-color-property ([color (or/c string? (list/c byte? byte? byte?))])]{ -Like @scheme[color-property], but sets the background color.} +Like @racket[color-property], but sets the background color.} @defstruct[table-cells ([styless (listof (listof style?))])]{ -Used as a @tech{style property} for a @scheme[table] to set its cells' +Used as a @tech{style property} for a @racket[table] to set its cells' styles. If a cell style has a string name, it is used as an HTML class for the @@ -847,44 +847,44 @@ The following symbols are recognized as cell-@tech{style properties}: @itemize[ - @item{@scheme['left] --- Left-align the cell content.} + @item{@racket['left] --- Left-align the cell content.} - @item{@scheme['right] --- Right-align the cell content top baselines.} + @item{@racket['right] --- Right-align the cell content top baselines.} - @item{@scheme['center] --- Center the cell content horizontally.} + @item{@racket['center] --- Center the cell content horizontally.} - @item{@scheme['top] --- Top-align the cell content.} + @item{@racket['top] --- Top-align the cell content.} - @item{@scheme['baseline] --- Align the cell content top baselines.} + @item{@racket['baseline] --- Align the cell content top baselines.} - @item{@scheme['bottom] --- bottom-align the cell content.} + @item{@racket['bottom] --- bottom-align the cell content.} - @item{@scheme['vcenter] --- Center the cell content vertically.} + @item{@racket['vcenter] --- Center the cell content vertically.} ] -In addition, for HTML output, @scheme[attributes] structures as +In addition, for HTML output, @racket[attributes] structures as @tech{style properties} can add arbitrary attributes to a cell's @tt{

} tag.} @defstruct[table-columns ([styles (listof style?)])]{ -Like @scheme[table-cells], but the @scheme[styles] list is duplicated +Like @racket[table-cells], but the @racket[styles] list is duplicated for each row in the table. This @tech{style property} is used only when a -@scheme[table-cells] is not present in a style's list of properties.} +@racket[table-cells] is not present in a style's list of properties.} @defproc[(block? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @scheme[paragraph], -@scheme[table], @scheme[itemization], @scheme[nested-flow], or -@scheme[delayed-block], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @racket[paragraph], +@racket[table], @racket[itemization], @racket[nested-flow], or +@racket[delayed-block], @racket[#f] otherwise.} @defproc[(content? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a string, symbol, -@scheme[element], @scheme[multiarg-element], @scheme[delayed-element], -@scheme[part-relative-element], or list of @tech{content}, @scheme[#f] +Returns @racket[#t] if @racket[v] is a string, symbol, +@racket[element], @racket[multiarg-element], @racket[delayed-element], +@racket[part-relative-element], or list of @tech{content}, @racket[#f] otherwise.} @@ -896,28 +896,28 @@ Represents a @techlink{style}.} @defthing[plain style?]{ -A style @scheme[(make-style #f null)].} +A style @racket[(make-style #f null)].} @defproc[(element-style? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a string, symbol, @scheme[#f], -or @scheme[style] structure.} +Returns @racket[#t] if @racket[v] is a string, symbol, @racket[#f], +or @racket[style] structure.} @defproc[(tag? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is acceptable as a link +Returns @racket[#t] if @racket[v] is acceptable as a link @techlink{tag}, which is a list containing a symbol and either a -string, a @scheme[generated-tag] instance, or a list (of arbitrary +string, a @racket[generated-tag] instance, or a list (of arbitrary values).} @defstruct[generated-tag ()]{ A placeholder for a tag to be generated during the @techlink{collect - pass}. Use @scheme[tag-key] to convert a tag containing a - @scheme[generated-tag] instance to one containing a string. + pass}. Use @racket[tag-key] to convert a tag containing a + @racket[generated-tag] instance to one containing a string. } @@ -928,7 +928,7 @@ A placeholder for a tag to be generated during the @techlink{collect Converts @tech{content} to a single string (essentially rendering the content as ``plain text''). -If @scheme[p] and @scheme[info] arguments are not supplied, then a +If @racket[p] and @racket[info] arguments are not supplied, then a pre-``collect'' substitute is obtained for @tech{delayed elements}. Otherwise, the two arguments are used to force the @tech{delayed element} (if it has not been forced already).} @@ -952,7 +952,7 @@ Returns the width in characters of the given @tech{block}.} Encapsulates information accumulated (or being accumulated) from the @techlink{collect pass}. The fields are exposed, but not currently -intended for external use, except that @scheme[collect-info-parents] +intended for external use, except that @racket[collect-info-parents] is intended for external use. } @@ -967,13 +967,13 @@ intended for external use. @defproc[(info-key? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is an @deftech{info key}: a list of +Returns @racket[#t] if @racket[v] is an @deftech{info key}: a list of at least two elements whose first element is a symbol. The result is -@scheme[#f] otherwise. +@racket[#f] otherwise. For a list that is an info tag, the interpretation of the second element of the list is effectively determined by the leading symbol, -which classifies the key. However, a @scheme[#f] value as the second +which classifies the key. However, a @racket[#f] value as the second element has an extra meaning: collected information mapped by such info keys is not propagated out of the part where it is collected; that is, the information is available within the part and its @@ -986,7 +986,7 @@ Note that every @techlink{tag} is an info key. @defproc[(collect-put! [ci collect-info?] [key info-key?] [val any/c]) void?]{ -Registers information in @scheme[ci]. This procedure should be called +Registers information in @racket[ci]. This procedure should be called only during the @techlink{collect pass}. } @@ -995,13 +995,13 @@ only during the @techlink{collect pass}. any/c]{ Extract information during the @techlink{resolve pass} or -@techlink{render pass} for @scheme[p] from @scheme[ri], where the +@techlink{render pass} for @racket[p] from @racket[ri], where the information was previously registered during the @techlink{collect pass}. See also @secref["passes"]. -The result is @scheme[#f] if the no value for the given key is found. +The result is @racket[#f] if the no value for the given key is found. Furthermore, the search failure is recorded for potential consistency -reporting, such as when @exec{setup-plt} is used to build +reporting, such as when @exec{racket setup} is used to build documentation. } @@ -1010,7 +1010,7 @@ documentation. @defproc[(resolve-get/ext? [p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) (values any/c boolean?)]{ -Like @scheme[render-get], but returns a second value to indicate +Like @racket[render-get], but returns a second value to indicate whether the resulting information originated from an external source (i.e., a different document).} @@ -1018,12 +1018,12 @@ whether the resulting information originated from an external source @defproc[(resolve-search [dep-key any/c][p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) void?]{ -Like @scheme[resolve-get], but a shared @scheme[dep-key] groups +Like @racket[resolve-get], but a shared @racket[dep-key] groups multiple searches as a single request for the purposes of consistency reporting and dependency tracking. That is, a single success for the -same @scheme[dep-key] means that all of the failed attempts for the -same @scheme[dep-key] have been satisfied. However, for dependency -checking, such as when using @exec{setup-plt} to re-build +same @racket[dep-key] means that all of the failed attempts for the +same @racket[dep-key] have been satisfied. However, for dependency +checking, such as when using @exec{racket setup} to re-build documentation, all attempts are recorded (in case external changes mean that an earlier attempt would succeed next time). @@ -1032,9 +1032,9 @@ mean that an earlier attempt would succeed next time). @defproc[(resolve-get/tentative [p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) any/c]{ -Like @scheme[resolve-search], but without dependency tracking. For +Like @racket[resolve-search], but without dependency tracking. For multi-document settings where dependencies are normally tracked, such -as when using @exec{setup-plt} to build documentation, this function +as when using @exec{racket setup} to build documentation, this function is suitable for use only for information within a single document. } @@ -1044,8 +1044,8 @@ is suitable for use only for information within a single document. [pred (info-key? . -> . any/c)]) list?]{ -Applies @scheme[pred] to each key mapped for @scheme[p] in -@scheme[ri], returning a list of all keys for which @scheme[pred] +Applies @racket[pred] to each key mapped for @racket[p] in +@racket[ri], returning a list of all keys for which @racket[pred] returns a true value. } @@ -1054,14 +1054,14 @@ returns a true value. [ri resolve-info?]) collected-info?]{ -Returns the information collected for @scheme[p] as recorded within -@scheme[ri]. +Returns the information collected for @racket[p] as recorded within +@racket[ri]. } @defproc[(tag-key [t tag?] [ri resolve-info?]) tag?]{ -Converts a @scheme[generated-tag] value with @scheme[t] to a string. +Converts a @racket[generated-tag] value with @racket[t] to a string. } @@ -1070,7 +1070,7 @@ Converts a @scheme[generated-tag] value with @scheme[t] to a string. @section{HTML Style Properties} @defmodule[scribble/html-properties]{ The -@scheme[scribble/html-properties] library provides datatypes used as +@racket[scribble/html-properties] library provides datatypes used as @tech{style properties} for HTML rendering.} @@ -1082,20 +1082,20 @@ tag.} @defstruct[url-anchor ([name string?])]{ -Used as a @tech{style property} with @scheme[element] to insert an +Used as a @tech{style property} with @racket[element] to insert an anchor before the element.} @defstruct[hover-property ([text string?])]{ -Used as a @tech{style property} with @scheme[element] to add text that +Used as a @tech{style property} with @racket[element] to add text that is shown when the mouse hovers over the element.} @defstruct[script-property ([type string?] [script (or/c path-string? (listof string?))])]{ -Used as a @tech{style property} with @scheme[element] to supply a +Used as a @tech{style property} with @racket[element] to supply a script alternative to the element content.} @@ -1106,8 +1106,8 @@ Used as a @tech{style property} to supply a CSS file to be referenced in the generated HTML. This property can be attached to any style, and all additions are collected to the top of the generated HTML page. -The @scheme[path] field can be a result of -@scheme[path->main-collects-relative].} +The @racket[path] field can be a result of +@racket[path->main-collects-relative].} @defstruct[body-id ([value string?])]{ @@ -1123,7 +1123,7 @@ an HTML tag.} [extra-files (listof (or/c path-string? (cons/c 'collects (listof bytes?))))])]{ -Like @scheme[latex-defaults], but use for the +Like @racket[latex-defaults], but use for the @exec{scribble} command-line tool's @DFlag{html} and @DFlag{htmls} modes.} @@ -1133,7 +1133,7 @@ Like @scheme[latex-defaults], but use for the @section{Latex Style Properties} @defmodule[scribble/latex-properties]{ The -@scheme[scribble/latex-properties] library provides datatypes used as +@racket[scribble/latex-properties] library provides datatypes used as @tech{style properties} for Latex rendering.} @@ -1145,8 +1145,8 @@ included in the generated Latex. This property can be attached to any style, and all additions are collected to the top of the generated Latex file. -The @scheme[path] field can be a result of -@scheme[path->main-collects-relative].} +The @racket[path] field can be a result of +@racket[path->main-collects-relative].} @defstruct[latex-defaults ([prefix (or/c bytes? path-string? @@ -1156,17 +1156,17 @@ The @scheme[path] field can be a result of [extra-files (listof (or/c path-string? (cons/c 'collects (listof bytes?))))])]{ -Used as a @tech{style property} on the main @scheme[part] of a document +Used as a @tech{style property} on the main @racket[part] of a document to set a default prefix file, style file, and extra files (see @secref["config-style"]). The defaults are used by the @exec{scribble} command-line tool for and @DFlag{latex} or @DFlag{pdf} mode if none are supplied via @DFlag{prefix} and @DFlag{style} (where -@scheme[extra-files] are used only when @scheme[prefix] is used). A +@racket[extra-files] are used only when @racket[prefix] is used). A byte-string value is used directly like file content, and a path can -be a result of @scheme[path->main-collects-relative]. +be a result of @racket[path->main-collects-relative]. Languages (used with @hash-lang[]) like -@schememodname[scribble/manual] and @schememodname[scribble/sigplan] +@racketmodname[scribble/manual] and @racketmodname[scribble/sigplan] add this property to a document to specify appropriate files for Latex rendering.} @@ -1174,11 +1174,11 @@ rendering.} @defstruct[latex-auto-extra-files ([paths (listof (or/c path-string? (cons/c 'collects (listof bytes?))))])]{ -Used as a @tech{style property} for the main @scheme[part] of a +Used as a @tech{style property} for the main @racket[part] of a document to supply extra files needed to build the document via the @exec{scribble} command-line tool (for @DFlag{latex} and @DFlag{pdf} mode). Languages (used with @hash-lang[]) like -@schememodname[scribble/sigplan] add this property to a document to specify +@racketmodname[scribble/sigplan] add this property to a document to specify appropriate extra files.} diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl index 936ec5c8..e5143e8f 100644 --- a/collects/scribblings/scribble/decode.scrbl +++ b/collects/scribblings/scribble/decode.scrbl @@ -4,11 +4,11 @@ @title[#:tag "decode"]{Decoding Text} -@defmodule[scribble/decode]{The @schememodname[scribble/decode] +@defmodule[scribble/decode]{The @racketmodname[scribble/decode] library helps you write document content in a natural way---more like plain text, except for @litchar["@"] escapes. Roughly, it processes a stream of strings to produces instances of the -@schememodname[scribble/struct] datatypes (see @secref["struct"]).} +@racketmodname[scribble/struct] datatypes (see @secref["struct"]).} At the @tech{flow} level, decoding recognizes a blank line as a @tech{paragraph} separator. Blocks and paragraphs without blank lines @@ -19,24 +19,24 @@ special text conversions: @itemize[ - @item{@litchar{---}: converted to @scheme['mdash], which the HTML render + @item{@litchar{---}: converted to @racket['mdash], which the HTML render outputs as an en-dash surrounded by space (so don't put spaces around @litchar{---} in a document)} - @item{@litchar{--}: converted to @scheme['ndash]} + @item{@litchar{--}: converted to @racket['ndash]} - @item{@litchar{``}: converted to @scheme['ldquo], which is fancy open quotes: ``} + @item{@litchar{``}: converted to @racket['ldquo], which is fancy open quotes: ``} - @item{@litchar{''}: converted to @scheme['rdquo], which is fancy closing quotes: ''} + @item{@litchar{''}: converted to @racket['rdquo], which is fancy closing quotes: ''} - @item{@litchar{'}: converted to @scheme['rsquo], which is a fancy apostrophe: '} + @item{@litchar{'}: converted to @racket['rsquo], which is a fancy apostrophe: '} ] -Some functions @deftech{decode} a sequence of @scheme[_pre-flow] or -@scheme[_pre-content] arguments using @scheme[decode-flow] or -@scheme[decode-content], respectively. For example, the @scheme[bold] -function accepts any number of @scheme[_pre-content] arguments, so +Some functions @deftech{decode} a sequence of @racket[_pre-flow] or +@racket[_pre-content] arguments using @racket[decode-flow] or +@racket[decode-content], respectively. For example, the @racket[bold] +function accepts any number of @racket[_pre-content] arguments, so that in @verbatim[#:indent 2]|{@bold{``apple''}}| @@ -47,52 +47,52 @@ then it is bolded. @defproc[(pre-content? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{pre-content} value: a -string or other non-list @scheme[content], or a @scheme[splice] +Returns @racket[#t] if @racket[v] is a @deftech{pre-content} value: a +string or other non-list @racket[content], or a @racket[splice] containing a list of @tech{pre-content} values; otherwise returns -@scheme[#f]. +@racket[#f]. Pre-content is decoded into @tech{content} by functions like -@scheme[decode-content] and @scheme[decode-paragraph].} +@racket[decode-content] and @racket[decode-paragraph].} @defproc[(pre-flow? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{pre-flow} value: a -string or other non-list @scheme[content], a @scheme[block], -@|void-const|, or a @scheme[splice] containing a list of -@tech{pre-flow} values; otherwise returns @scheme[#f]. +Returns @racket[#t] if @racket[v] is a @deftech{pre-flow} value: a +string or other non-list @racket[content], a @racket[block], +@|void-const|, or a @racket[splice] containing a list of +@tech{pre-flow} values; otherwise returns @racket[#f]. Pre-flow is decoded into a @tech{flow} (i.e., a list of @tech{blocks}) -by functions like @scheme[decode-flow].} +by functions like @racket[decode-flow].} @defproc[(pre-part? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{pre-part} value: a +Returns @racket[#t] if @racket[v] is a @deftech{pre-part} value: a string or other non-list @tech{content}, a @tech{block}, a -@scheme[part], a @scheme[title-decl], a @scheme[part-start], a -@scheme[part-index-decl], a @scheme[part-collect-decl], a -@scheme[part-tag-decl], @|void-const|, or a @scheme[splice] containing -a list of @tech{pre-part} values; otherwise returns @scheme[#f]. +@racket[part], a @racket[title-decl], a @racket[part-start], a +@racket[part-index-decl], a @racket[part-collect-decl], a +@racket[part-tag-decl], @|void-const|, or a @racket[splice] containing +a list of @tech{pre-part} values; otherwise returns @racket[#f]. -A pre-part sequence is decoded into a @scheme[part] by functions like -@scheme[decode] and @scheme[decode-part].} +A pre-part sequence is decoded into a @racket[part] by functions like +@racket[decode] and @racket[decode-part].} @defproc[(decode [lst (listof pre-part?)]) part?]{ -Decodes a document, producing a part. In @scheme[lst], instances of -@scheme[splice] are inlined into the list. An instance of -@scheme[title-decl] supplies the title for the part, plus tag, style -and version information. Instances of @scheme[part-index-decl] (that +Decodes a document, producing a part. In @racket[lst], instances of +@racket[splice] are inlined into the list. An instance of +@racket[title-decl] supplies the title for the part, plus tag, style +and version information. Instances of @racket[part-index-decl] (that precede any sub-part) add index entries that point to the -section. Instances of @scheme[part-collect-decl] add elements to the +section. Instances of @racket[part-collect-decl] add elements to the part that are used only during the @techlink{collect pass}. Instances -of @scheme[part-tag-decl] add hyperlink tags to the section -title. Instances of @scheme[part-start] at level 0 trigger sub-part -parsing. Instances of @scheme[section] trigger are used as-is as -subsections, and instances of @scheme[paragraph] and other +of @racket[part-tag-decl] add hyperlink tags to the section +title. Instances of @racket[part-start] at level 0 trigger sub-part +parsing. Instances of @racket[section] trigger are used as-is as +subsections, and instances of @racket[paragraph] and other flow-element datatypes are used as-is in the enclosing flow.} @@ -102,9 +102,9 @@ flow-element datatypes are used as-is in the enclosing flow.} [depth exact-nonnegative-integer?]) part?]{ -Like @scheme[decode], but given a list of tag string for the part, a -title (if @scheme[#f], then a @scheme[title-decl] instance is used if -found), and a depth for @scheme[part-start]s to trigger sub-part +Like @racket[decode], but given a list of tag string for the part, a +title (if @racket[#f], then a @racket[title-decl] instance is used if +found), and a depth for @racket[part-start]s to trigger sub-part parsing. } @@ -112,9 +112,9 @@ parsing. @defproc[(decode-flow [lst (listof pre-flow?)]) flow?]{ Decodes a flow. A sequence of two or more newlines separated only by -whitespace counts is parsed as a paragraph separator. In @scheme[lst], -instances of @scheme[splice] are inlined into the list. Instances of -@scheme[paragraph] and other flow-element datatypes are used as-is in +whitespace counts is parsed as a paragraph separator. In @racket[lst], +instances of @racket[splice] are inlined into the list. Instances of +@racket[paragraph] and other flow-element datatypes are used as-is in the enclosing flow. } @@ -123,7 +123,7 @@ the enclosing flow. Decodes a compound paragraph. If the compound paragraph contains a single block, the block is returned without a -@scheme[compound-paragraph] wrapper. +@racket[compound-paragraph] wrapper. } @@ -141,7 +141,7 @@ Decodes @tech{content}. @defproc[(decode-elements [lst (listof pre-content?)]) list?]{ -An alias for @scheme[decode-content]. +An alias for @racket[decode-content]. } @defproc[(decode-string [s string?]) (listof content?)]{ @@ -153,7 +153,7 @@ Decodes a single string to produce @tech{content}. @defproc[(whitespace? [s string?]) boolean?]{ -Returns @scheme[#t] if @scheme[s] contains only whitespace, @scheme[#f] +Returns @racket[#t] if @racket[s] contains only whitespace, @racket[#f] otherwise. } @@ -164,9 +164,9 @@ otherwise. [style any/c] [content content?])]{ -See @scheme[decode] and @scheme[decode-part]. The @scheme[tag-prefix] -and @scheme[style] fields are propagated to the resulting -@scheme[part]. +See @racket[decode] and @racket[decode-part]. The @racket[tag-prefix] +and @racket[style] fields are propagated to the resulting +@racket[part]. } @@ -176,33 +176,33 @@ and @scheme[style] fields are propagated to the resulting [style any/c] [title content?])]{ -Like @scheme[title-decl], but for a sub-part. See @scheme[decode] and -@scheme[decode-part]. +Like @racket[title-decl], but for a sub-part. See @racket[decode] and +@racket[decode-part]. } @defstruct[part-index-decl ([plain-seq (listof string?)] [entry-seq list?])]{ -See @scheme[decode]. The two fields are as for @scheme[index-element]. +See @racket[decode]. The two fields are as for @racket[index-element]. } @defstruct[part-collect-decl ([element element?])]{ -See @scheme[decode]. +See @racket[decode]. } @defstruct[part-tag-decl ([tag tag?])]{ -See @scheme[decode]. +See @racket[decode]. } @defstruct[splice ([run list?])]{ -See @scheme[decode], @scheme[decode-part], and @scheme[decode-flow]. +See @racket[decode], @racket[decode-part], and @racket[decode-flow]. } diff --git a/collects/scribblings/scribble/doclang.scrbl b/collects/scribblings/scribble/doclang.scrbl index 080e7d70..062d7e3b 100644 --- a/collects/scribblings/scribble/doclang.scrbl +++ b/collects/scribblings/scribble/doclang.scrbl @@ -3,16 +3,16 @@ @title[#:tag "doclang"]{Document Language} -@defmodulelang[scribble/doclang]{The @schememodname[scribble/doclang] -language provides everything from @scheme[scheme/base], except that it -replaces the @scheme[#%module-begin] form.} +@defmodulelang[scribble/doclang]{The @racketmodname[scribble/doclang] +language provides everything from @racket[racket/base], except that it +replaces the @racket[#%module-begin] form.} -The @schememodname[scribble/doclang] @scheme[#%module-begin] +The @racketmodname[scribble/doclang] @racket[#%module-begin] essentially packages the body of the module into a call to -@scheme[decode], binds the result to @scheme[doc], and exports -@scheme[doc]. +@racket[decode], binds the result to @racket[doc], and exports +@racket[doc]. Any module-level form other than an expression (e.g., a -@scheme[require] or @scheme[define]) remains at the top level, and -the @scheme[doc] binding is put at the end of the module. As usual, a -module-top-level @scheme[begin] slices into the module top level. +@racket[require] or @racket[define]) remains at the top level, and +the @racket[doc] binding is put at the end of the module. As usual, a +module-top-level @racket[begin] slices into the module top level. diff --git a/collects/scribblings/scribble/docreader.scrbl b/collects/scribblings/scribble/docreader.scrbl index 00e77970..19f9acb8 100644 --- a/collects/scribblings/scribble/docreader.scrbl +++ b/collects/scribblings/scribble/docreader.scrbl @@ -5,8 +5,8 @@ @title[#:tag "docreader"]{Document Reader} -@defmodulelang[scribble/doc]{The @schememodname[scribble/doc] language is -the same as @schememodname[scribble/doclang], except that -@scheme[read-syntax-inside] is used to read the body of the module. In +@defmodulelang[scribble/doc]{The @racketmodname[scribble/doc] language is +the same as @racketmodname[scribble/doclang], except that +@racket[read-syntax-inside] is used to read the body of the module. In other words, the module body starts in Scribble ``text'' mode instead of S-expression mode.} diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl index 88504396..4c50f071 100644 --- a/collects/scribblings/scribble/eval.scrbl +++ b/collects/scribblings/scribble/eval.scrbl @@ -1,11 +1,11 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-label scheme/sandbox)) + (for-label racket/sandbox)) @title[#:tag "eval"]{Evaluation and Examples} -@defmodule[scribble/eval]{The @scheme[scribble/eval] library provides +@defmodule[scribble/eval]{The @racket[scribble/eval] library provides utilities for evaluating code at document-build time and incorporating the results in the document, especially to show example uses of defined procedures and syntax.} @@ -13,22 +13,22 @@ defined procedures and syntax.} @defform*[[(interaction datum ...) (interaction #:eval eval-expr datum ...)]]{ -Like @scheme[schemeinput], except that the result for each input -@scheme[datum] is shown on the next line. The result is determined by -evaluating the @scheme[quote]d form of the @scheme[datum] using the -evaluator produced by @scheme[eval-expr], if provided. +Like @racket[racketinput], except that the result for each input +@racket[datum] is shown on the next line. The result is determined by +evaluating the @racket[quote]d form of the @racket[datum] using the +evaluator produced by @racket[eval-expr], if provided. -The @scheme[eval-expr] must produce a sandbox evaluator via -@scheme[make-evaluator] or @scheme[make-module-evaluator] with the -@scheme[sandbox-output] and @scheme[sandbox-error-output] parameters -set to @scheme['string]. If @scheme[eval] is not provided, an -evaluator is created using @scheme[make-base-eval]. See also -@scheme[make-eval-factory]. +The @racket[eval-expr] must produce a sandbox evaluator via +@racket[make-evaluator] or @racket[make-module-evaluator] with the +@racket[sandbox-output] and @racket[sandbox-error-output] parameters +set to @racket['string]. If @racket[eval] is not provided, an +evaluator is created using @racket[make-base-eval]. See also +@racket[make-eval-factory]. -Uses of @scheme[code:comment] and @schemeidfont{code:blank} are -stipped from each @scheme[datum] before evaluation. +Uses of @racket[code:comment] and @racketidfont{code:blank} are +stipped from each @racket[datum] before evaluation. -If a @scheme[datum] has the form @scheme[(@#,indexed-scheme[eval:alts] +If a @racket[datum] has the form @racket[(@#,indexed-racket[eval:alts] #,(svar show-datum) #,(svar eval-datum))], then @svar[show-datum] is typeset, while @svar[eval-datum] is evaluated.} @@ -36,83 +36,83 @@ typeset, while @svar[eval-datum] is evaluated.} @defform*[[(interaction-eval datum) (interaction-eval #:eval eval-expr datum)]]{ -Like @scheme[interaction], evaluates the @scheme[quote]d form of -@scheme[datum], but returns the empty string.} +Like @racket[interaction], evaluates the @racket[quote]d form of +@racket[datum], but returns the empty string.} @defform*[[(interaction-eval-show datum) (interaction-eval-show #:eval eval-expr datum)]]{ -Like @scheme[interaction-eval], but produces an element representing +Like @racket[interaction-eval], but produces an element representing the printed form of the evaluation result.} -@defform*[[(schemeblock+eval datum ...) - (schemeblock+eval #:eval eval-expr datum ...)]]{ +@defform*[[(racketblock+eval datum ...) + (racketblock+eval #:eval eval-expr datum ...)]]{ -Combines @scheme[schemeblock] and @scheme[interaction-eval].} +Combines @racket[racketblock] and @racket[interaction-eval].} -@defform*[[(schememod+eval name datum ...) - (schememod+eval #:eval eval-expr name datum ...)]]{ +@defform*[[(racketmod+eval name datum ...) + (racketmod+eval #:eval eval-expr name datum ...)]]{ -Combines @scheme[schememod] and @scheme[interaction-eval].} +Combines @racket[racketmod] and @racket[interaction-eval].} @defform*[[(def+int defn-datum expr-datum ...) (def+int #:eval eval-expr defn-datum expr-datum ...)]]{ -Like @scheme[interaction], except the @scheme[defn-datum] is -typeset as for @scheme[schemeblock] (i.e., no prompt) and a line of -space is inserted before the @scheme[expr-datum]s.} +Like @racket[interaction], except the @racket[defn-datum] is +typeset as for @racket[racketblock] (i.e., no prompt) and a line of +space is inserted before the @racket[expr-datum]s.} @defform*[[(defs+int (defn-datum ...) expr-datum ...) (defs+int #:eval eval-expr (defn-datum ...) expr-datum ...)]]{ -Like @scheme[def+int], but for multiple leading definitions.} +Like @racket[def+int], but for multiple leading definitions.} @defform*[[(examples datum ...) (examples #:eval eval-expr datum ...)]]{ -Like @scheme[interaction], but with an ``Examples:'' label prefixed.} +Like @racket[interaction], but with an ``Examples:'' label prefixed.} @defform*[[(defexamples datum ...) (defexamples #:eval eval-expr datum ...)]]{ -Like @scheme[examples], but each definition using @scheme[define] or -@scheme[define-struct] among the @scheme[datum]s is typeset without a +Like @racket[examples], but each definition using @racket[define] or +@racket[define-struct] among the @racket[datum]s is typeset without a prompt, and with line of space after it.} @defproc[(make-base-eval) (any/c . -> . any)]{ -Creates an evaluator using @scheme[(make-evaluator 'scheme/base)], +Creates an evaluator using @racket[(make-evaluator 'racket/base)], setting sandbox parameters to disable limits, set the outputs to -@scheme['string], and not add extra security guards.} +@racket['string], and not add extra security guards.} @defproc[(make-base-eval-factory [mod-paths (listof module-path?)]) (-> (any/c . -> . any))]{ -Produces a function that is like @scheme[make-base-eval], except that -each module in @scheme[mod-paths] is attached to the evaluator's +Produces a function that is like @racket[make-base-eval], except that +each module in @racket[mod-paths] is attached to the evaluator's namespace. The modules are loaded and instantiated once (when the -returned @scheme[make-base-eval]-like function is called the first +returned @racket[make-base-eval]-like function is called the first time) and then attached to each evaluator that is created.} @defproc[(make-eval-factory [mod-paths (listof module-path?)]) (-> (any/c . -> . any))]{ -Like @scheme[make-base-eval-factor], but each module in @scheme[mod-paths] is +Like @racket[make-base-eval-factor], but each module in @racket[mod-paths] is also required into the top-level environment for each generated evaluator.} @defproc[(close-eval [eval (any/c . -> . any)]) (one-of/c "")]{ -Shuts down an evaluator produced by @scheme[make-base-eval]. Use -@scheme[close-eval] when garbage collection cannot otherwise reclaim +Shuts down an evaluator produced by @racket[make-base-eval]. Use +@racket[close-eval] when garbage collection cannot otherwise reclaim an evaluator (e.g., because it is defined in a module body).} @@ -122,5 +122,5 @@ an evaluator (e.g., because it is defined in a module body).} A parameter that serves as a hook for evaluation. The evaluator to use is supplied as the first argument to the parameter's value, and the second argument is the form to evaluate. The last argument is -@scheme[#t] if exceptions are being captured (to display exception -results), @scheme[#f] otherwise.} +@racket[#t] if exceptions are being captured (to display exception +results), @racket[#f] otherwise.} diff --git a/collects/scribblings/scribble/how-to-paper.scrbl b/collects/scribblings/scribble/how-to-paper.scrbl index a4fe3391..3ee33d45 100644 --- a/collects/scribblings/scribble/how-to-paper.scrbl +++ b/collects/scribblings/scribble/how-to-paper.scrbl @@ -27,10 +27,10 @@ Create a file @filepath{mouse.scrbl} with this content: glass of milk. }| -The first line's @scheme[#, @hash-lang[] #, -@schememodname[scribble/base]] indicates that the file implements a +The first line's @racket[#, @hash-lang[] #, +@racketmodname[scribble/base]] indicates that the file implements a Scribble document. The document starts in ``text mode,'' and the -@litchar["@"] character escapes to operators like @scheme[title], +@litchar["@"] character escapes to operators like @racket[title], where the curly braces return to text mode for the arguments to the operator. The rest is document content. @@ -89,10 +89,10 @@ Add more text to @filepath{mouse.scrbl} so that it looks like this: }| Now, after the first paragraph of the paper, we have two - sub-sections, each created by calling @scheme[section] to + sub-sections, each created by calling @racket[section] to generate a sub-section declaration. The first sub-section has two paragraphs. The second section, as initiated by the result - of the second @scheme[section] call, has a single paragraph. + of the second @racket[section] call, has a single paragraph. Run the @exec{scribble} command(s) from @secref["first-example"] again. You may notice the curly double-quotes in the output; in PDF @@ -104,7 +104,7 @@ for em-dashes in HTML. @section{Splitting the Document Source} As a document grows larger, it's better to split sections into -separate source files. The @scheme[include-section] operation +separate source files. The @racket[include-section] operation incorporates a document defined by a @filepath{.scrbl} file into a larger document. @@ -145,8 +145,8 @@ and in @filepath{straw.scbl}, put }| Notice that the new files both start with @hash-lang[], like the -original document, and the @scheme[section]s from the original -document become @scheme[title]s in the new documents. Both +original document, and the @racket[section]s from the original +document become @racket[title]s in the new documents. Both @filepath{milk.scrbl} and @filepath{straw.scrbl} are documents in their own right with their own titles, and they can be individually rendered using @exec{scribble}. Running @exec{scribble} on @@ -171,7 +171,7 @@ content look right by changing the first line to #lang scribble/sigplan }| -If you're instead working toward PLT Scheme library documentation, +If you're instead working toward Racket library documentation, try changing the first line to @sample|{ @@ -184,11 +184,11 @@ top-level sections turned into chapters that each start on a new page. If you have split the document into multiple files, the first line of the main document file determines the output format. -Using @schememodname[scribble/sigplan] or -@schememodname[scribble/manual] does not change the rendered HTML for -a document---aside from @schememodname[scribble/manual] adding a +Using @racketmodname[scribble/sigplan] or +@racketmodname[scribble/manual] does not change the rendered HTML for +a document---aside from @racketmodname[scribble/manual] adding a version number---but it changes the set of bindings available in the -document body. For example, with @schememodname[scribble/sigplan], the +document body. For example, with @racketmodname[scribble/sigplan], the introductory text can be marked as an abstract: @sample|{ @@ -204,16 +204,16 @@ introductory text can be marked as an abstract: ....}| When rendered as HTML, the abstract shows up as an inset paragraph. If -you try to use @scheme[abstract] with the -@schememodname[scribble/base] or @schememodname[scribble/manual] -language, then you get an error, because @scheme[abstract] is not +you try to use @racket[abstract] with the +@racketmodname[scribble/base] or @racketmodname[scribble/manual] +language, then you get an error, because @racket[abstract] is not defined. When a document is implemented across multiple files, changing the language of the main document can set the style for all of the parts, but it does not introduce bindings into the other part files. For example, if you change the language of @filepath{mouse.scrbl} to -@schememodname[scribble/sigplan], then @scheme[abstract] becomes +@racketmodname[scribble/sigplan], then @racket[abstract] becomes available in @filepath{mouse.scrbl} but not in @filepath{milk.scrbl} or @filepath{straw.scrbl}. In other words, operator names are lexically scoped. @@ -221,9 +221,9 @@ lexically scoped. @; ---------------------------------------- @section{More Functions} -The @schememodname[scribble/sigplan] and -@schememodname[scribble/manual] languages are supersets of the -@schememodname[scribble/base] language, which provides a collection of +The @racketmodname[scribble/sigplan] and +@racketmodname[scribble/manual] languages are supersets of the +@racketmodname[scribble/base] language, which provides a collection of basic operations. Many of the operations are style variations that you can apply to text: @@ -241,15 +241,15 @@ which renders as @italic{probably} ask you for a straw. } -As you would expect, calls to functions like @scheme[smaller], -@scheme[larger], and @scheme[bold] can be nested in other calls. They -can also be nested within calls to @scheme[title] or @scheme[section]: +As you would expect, calls to functions like @racket[smaller], +@racket[larger], and @racket[bold] can be nested in other calls. They +can also be nested within calls to @racket[title] or @racket[section]: @sample|{ @section{@italic{Not} the Last Straw} }| -The @scheme[centered] operation centers a flow of text: +The @racket[centered] operation centers a flow of text: @sample|{ If a mouse eats all your cookies, put up a sign that says @@ -273,19 +273,19 @@ which renders as and see if anyone brings you more. } -The @scheme[margin-note] operation is used in a similar way, but the +The @racket[margin-note] operation is used in a similar way, but the rendered text is moved to the margins. -@margin-note{If you use @scheme[margin-note], then the content shows +@margin-note{If you use @racket[margin-note], then the content shows up over here.} -The @scheme[itemlist] operation creates a sequence of bulleted text, -where the @scheme[item] operation groups text to appear in a single -bullet. The @scheme[itemlist] operation is different from the others +The @racket[itemlist] operation creates a sequence of bulleted text, +where the @racket[item] operation groups text to appear in a single +bullet. The @racket[itemlist] operation is different from the others that we have seen before, because it only accepts values produced by -@scheme[item] instead of arbitrary text. This difference is reflected +@racket[item] instead of arbitrary text. This difference is reflected in the use of @litchar{[}...@litchar{]} for the arguments to -@scheme[itemlist] instead of @litchar["{"]...@litchar["}"]: +@racket[itemlist] instead of @litchar["{"]...@litchar["}"]: @sample|{ @centered{@bold{Notice to Mice}} @@ -306,21 +306,21 @@ which renders as } @; ---------------------------------------- -@section{Text Mode vs. Scheme Mode for Arguments} +@section{Text Mode vs. Racket Mode for Arguments} When @litchar{[}...@litchar{]} surrounds the arguments of an -operation, the argument expressions are in Scheme mode rather than -text mode. Even in Scheme mode, @litchar["@"] can be used to apply +operation, the argument expressions are in Racket mode rather than +text mode. Even in Racket mode, @litchar["@"] can be used to apply operations; once the @"@" syntax is enabled through a -language like @schememodname[scribble/base] (as opposed to -@schememodname[scheme]), it behaves the same in both Scheme mode and +language like @racketmodname[scribble/base] (as opposed to +@racketmodname[racket]), it behaves the same in both Racket mode and text mode. -One advantage of using Scheme mode for the arguments to -@scheme[itemlist] is that we can pass a keyword-tagged optional -argument to @scheme[itemlist]. In particular, if you want a list with -numbers instead of bullets, supply the @scheme['ordered] style to -@scheme[itemlist] using the @scheme[#:style] keyword: +One advantage of using Racket mode for the arguments to +@racket[itemlist] is that we can pass a keyword-tagged optional +argument to @racket[itemlist]. In particular, if you want a list with +numbers instead of bullets, supply the @racket['ordered] style to +@racket[itemlist] using the @racket[#:style] keyword: @sample|{ @itemlist[#:style 'ordered @@ -347,15 +347,15 @@ is equivalent to @italic["Yummy!"] }| -which is equivalent to the Scheme expression +which is equivalent to the Racket expression - @schemeblock[ + @racketblock[ (italic "Yummy!") ] These equivalences explain why Scribble functions are documented in -Scheme notation. If you're reading this in HTML format, you can click -@scheme[italic] above to access its documentation. The documentation +Racket notation. If you're reading this in HTML format, you can click +@racket[italic] above to access its documentation. The documentation won't completely make sense, yet, but it will by the end of this chapter. @@ -364,15 +364,15 @@ to supply other optional arguments? You can use both @litchar{[}...@litchar{]} and @litchar["{"]...@litchar["}"] for an operation, as long as the @litchar{[}...@litchar{]} is first, and as long as no character separate the closing @litchar{]} from the -opening @litchar["{"]. For example, calling @scheme[italic] is the -same as using @scheme[elem] with the @scheme['italic] style: +opening @litchar["{"]. For example, calling @racket[italic] is the +same as using @racket[elem] with the @racket['italic] style: @sample|{ @elem[#:style 'italic]{Yummy!} }| You can also @emph{omit} both @litchar{[}...@litchar{]} and -@litchar["{"]...@litchar["}"]. In that case, the Scheme expression +@litchar["{"]...@litchar["}"]. In that case, the Racket expression after @litchar["@"] is used directly instead of applied as an operation. For example, @@ -386,22 +386,22 @@ renders as 1 plus 2 is @(number->string (+ 1 2)). } -The call to @scheme[number->string] is needed because a naked number +The call to @racket[number->string] is needed because a naked number is not valid as document content. @; ---------------------------------------- @section[#:tag "how-to:reader"]{@"@" Syntax Basics} The @"@" notation provided by Scribble is just another way of -writing Scheme expressions. Scribble documents could be constructed -using normal Scheme notation, without using @"@" at all, but +writing Racket expressions. Scribble documents could be constructed +using normal Racket notation, without using @"@" at all, but that would be inconvenient for most purposes. The @"@" notation makes dealing with textual content much easier. -Whether in text mode or Scheme mode, @litchar["@"] in a document -provides an escape to Scheme mode. The basic syntax of @litchar["@"] is +Whether in text mode or Racket mode, @litchar["@"] in a document +provides an escape to Racket mode. The basic syntax of @litchar["@"] is -@schemeblock[ +@racketblock[ @#,BNF-seq[@litchar["@"] @nonterm{cmd} @litchar{[} @kleenestar{@nonterm{datum}} @litchar{]} @@ -421,42 +421,42 @@ one must be present. No spaces are allowed between ] -A @nonterm{cmd} or @nonterm{datum} is normal Scheme notation, while a +A @nonterm{cmd} or @nonterm{datum} is normal Racket notation, while a @nonterm{text-body} is itself in text mode. A @nonterm{cmd} obviously -must not start with @litchar{[} or @litchar["{"], even though Scheme +must not start with @litchar{[} or @litchar["{"], even though Racket forms could otherwise start with those characters. -The expansion of just @litchar["@"]@nonterm{cmd} into Scheme code is +The expansion of just @litchar["@"]@nonterm{cmd} into Racket code is -@schemeblock[ +@racketblock[ @#,nonterm{cmd} ] When either @litchar{[} @litchar{]} or @litchar["{"] @litchar["}"] are used, the expansion is -@schemeblock[ +@racketblock[ (@#,nonterm{cmd} @#,kleenestar{@nonterm{datum}} @#,kleenestar{@nonterm{parsed-body}}) ] where @kleenestar{@nonterm{parsed-body}} is the parse result of the @nonterm{text-body}. The @kleenestar{@nonterm{parsed-body}} part often -turns out to be a sequence of Scheme strings. +turns out to be a sequence of Racket strings. -In practice, the @nonterm{cmd} is normally a Scheme identifier that is +In practice, the @nonterm{cmd} is normally a Racket identifier that is bound to a procedure or syntactic form. If the procedure or form expects further text to typeset, then @litchar["{"]...@litchar["}"] supplies the text. If the form expects other data, typically -@litchar{[}...@litchar{]} is used to surround Scheme arguments, +@litchar{[}...@litchar{]} is used to surround Racket arguments, instead. Even if an operation's argument is a string, if the string is not used as content text (but instead used as, say, a hyperlink label), then the string is typically provided through @litchar{[}...@litchar{]} instead of @litchar["{"]...@litchar["}"]. Sometimes, both @litchar{[}...@litchar{]} and @litchar["{"]...@litchar["}"] are used, where the former surround -Scheme arguments that precede text to typeset. Finally, if a form is a -purely Scheme-level form with not typeset result, such as a -@scheme[require] to import more operations, then typically just +Racket arguments that precede text to typeset. Finally, if a form is a +purely Racket-level form with not typeset result, such as a +@racket[require] to import more operations, then typically just @litchar["@"] is used. For example the text-mode stream @@ -471,9 +471,9 @@ For example the text-mode stream @figure["straw" @elem{A straw}]{@image["straw.png"]} }| -is equivalent to the Scheme-mode sequence +is equivalent to the Racket-mode sequence -@schemeblock[ +@racketblock[ (require scriblib/figure) "\n" "\n" (section #:tag "poetry" "Of Mice and Cookies") "\n" @@ -485,12 +485,12 @@ is equivalent to the Scheme-mode sequence Besides showing how different argument conventions are used for different operations, the above example illustrates how whitespace is -preserved in the Scheme form of a text-mode stream---including +preserved in the Racket form of a text-mode stream---including newlines preserved as their own strings. Notice how the second -@scheme[section] gets two arguments for its content, since the -argument content for @scheme[section] in the source stream includes +@racket[section] gets two arguments for its content, since the +argument content for @racket[section] in the source stream includes both the use of an operator and additional text. When an operation -like @scheme[section] or @scheme[italic] accepts content to typeset, +like @racket[section] or @racket[italic] accepts content to typeset, it normally accepts an arbitrary number of arguments that together form the content. @@ -502,21 +502,21 @@ arguments while disabling @litchar["@"] between the brackets. @; ---------------------------------------- @section{Decoding Sequences} -In a document that starts @scheme[#, @hash-lang[] #, -@schememodname[scribble/base]], the top level is a text-mode stream, +In a document that starts @racket[#, @hash-lang[] #, +@racketmodname[scribble/base]], the top level is a text-mode stream, just like the @nonterm{text-body} in a @litchar["@"] form. As illustrated in the previous section, such a top-level sequence -corresponds to a mixture of Scheme-mode strings and operation -applications. There's an implicit operation, @scheme[decode], that +corresponds to a mixture of Racket-mode strings and operation +applications. There's an implicit operation, @racket[decode], that wraps the whole document to consume this mixture of strings and other values and turn them into a document description. -The @scheme[decode] operation implements @defterm{flow decoding}, +The @racket[decode] operation implements @defterm{flow decoding}, which takes a document stream and breaks it up into sections and paragraphs. Blank lines delimit paragraphs, and the results of -operations like @scheme[title] and @scheme[section] generate ``here's +operations like @racket[title] and @racket[section] generate ``here's the title'' or ``a new section starts here'' declarations that are -recognized by @scheme[decode]. +recognized by @racket[decode]. A different but related @defterm{content decoding} takes place within a paragraph or section title. Content decoding is responsible for @@ -524,16 +524,16 @@ converting @litchar{---} to an em-dash or for converting @litchar{"} and @litchar{'} to suitable curly quotes. The decoding process for document's stream is ultimately determined by -the @hash-lang[] line that starts the document. The @schememodname[scribble/base], -@schememodname[scribble/manual], and @schememodname[scribble/sigplan] -languages all use the same @scheme[decode] operation. The -@schememodname[scribble/text] language, however, acts more like a +the @hash-lang[] line that starts the document. The @racketmodname[scribble/base], +@racketmodname[scribble/manual], and @racketmodname[scribble/sigplan] +languages all use the same @racket[decode] operation. The +@racketmodname[scribble/text] language, however, acts more like a plain-text preprocessor and it does not perform any such decoding -rules. (For more on @schememodname[scribble/text], see +rules. (For more on @racketmodname[scribble/text], see @secref["preprocessor"].) @margin-note{More precisely, languages like - @schememodname[scribble/base] apply @scheme[decode] only after + @racketmodname[scribble/base] apply @racket[decode] only after lifting out all definitions and imports from the document stream.} @@ -542,10 +542,10 @@ paragraphs, it applies content decoding to strings within the paragraph. When content is wrapped with an operation, however, content decoding does not apply automatically. An operation is responsible for calling a content or flow decoder as it sees fit. Most operations call -the decoder; for example, @scheme[italic], @scheme[bold], -@scheme[smaller], etc., all decode their arguments. Similarly, -@scheme[title] and @scheme[section] decode the given content for the -title or section name. The @scheme[literal] and @scheme[verbatim] +the decoder; for example, @racket[italic], @racket[bold], +@racket[smaller], etc., all decode their arguments. Similarly, +@racket[title] and @racket[section] decode the given content for the +title or section name. The @racket[literal] and @racket[verbatim] operators, however, do not decode the given strings. For example, @sample|{ @@ -577,9 +577,9 @@ because the source is equivalent to (verbatim (number->string (+ 1 2))) }| -where @scheme[(number->string (+ 1 2))] is evaluated to produce the -argument to @scheme[verbatim]. The @litchar["|{"]...@litchar["}|"] -style of brackets is often used with @scheme[verbatim], because +where @racket[(number->string (+ 1 2))] is evaluated to produce the +argument to @racket[verbatim]. The @litchar["|{"]...@litchar["}|"] +style of brackets is often used with @racket[verbatim], because @litchar["|{"]...@litchar["}|"] disables @"@" notation for arguments. For example, @@ -596,12 +596,12 @@ renders as @; ---------------------------------------- @section[#:tag "roadmap"]{Next Steps} -If your immediate goal is to document a PLT Scheme library or write +If your immediate goal is to document a Racket library or write literate programs, skip to @secref["how-to-doc"], and then go back to @secref["reader"] and other chapters. -If you are more interested in producing documents unrelated to PLT -Scheme, continue with @secref["reader"] and then +If you are more interested in producing documents unrelated to +Racket, continue with @secref["reader"] and then @secref["generic-prose"]. Move on to @secref["internals"] when you need more power. diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl index 16667302..5571a2d2 100644 --- a/collects/scribblings/scribble/how-to.scrbl +++ b/collects/scribblings/scribble/how-to.scrbl @@ -6,9 +6,9 @@ @title[#:tag "how-to-doc"]{Getting Started with Documentation} Although the @exec{scribble} command-line utility generates output -from a Scribble document, documentation of PLT Scheme libraries is -normally built by @exec{setup-plt}. This chapter emphasizes the -@exec{setup-plt} approach, which more automatically supports links +from a Scribble document, documentation of Racket libraries is +normally built by @exec{raco setup}. This chapter emphasizes the +@exec{raco setup} approach, which more automatically supports links across documents. @margin-note{See @secref["getting-started"] for information on using the @@ -33,36 +33,36 @@ To document a collection or @|PLaneT| package: @title{My Library} - Welcome to my documentation: @scheme[(list 'testing 1 2 3)]. + Welcome to my documentation: @racket[(list 'testing 1 2 3)]. }| The first line starts the file in ``text'' mode and selects - the PLT Scheme manual output format. - It also introduces bindings like @scheme[title] and - @scheme[scheme] for writing PLT Scheme documentation.} + the Racket manual output format. + It also introduces bindings like @racket[title] and + @racket[racket] for writing Racket documentation.} @item{Add the following entry to your collect or package's @filepath{info.ss}: - @schemeblock[ + @racketblock[ (define scribblings '(("manual.scrbl" ()))) ] - The @scheme[()] above is a list of options. When your document + The @racket[()] above is a list of options. When your document gets large enough that you want it split into multiple pages, - add the @scheme['multi-page] option (omitting the quote, since + add the @racket['multi-page] option (omitting the quote, since the whole right-hand side of the definition is already quoted). If you do not already have an @filepath{info.ss} module, here's a suitable complete module: - @schememod[ + @racketmod[ setup/infotab (define scribblings '(("manual.scrbl" ()))) ]} - @item{Run @exec{setup-plt} to build your documentation. For a + @item{Run @exec{raco setup} to build your documentation. For a collection, optionally supply @Flag{l} followed by the collection name to limit the build process to that collection. For a @|PLaneT| package, optionally supply @@ -71,64 +71,64 @@ To document a collection or @|PLaneT| package: @item{The generated documentation is normally @filepath{doc/manual/index.html} within the collection or - @|PLaneT| package directory. If the collection is in PLT - Scheme's main @filepath{collects} directory, however, then the + @|PLaneT| package directory. If the collection is in + Racket's main @filepath{collects} directory, however, then the documentation is generated as @filepath{manual/index.html} in the installation's main @filepath{doc} directory.} ] @; ---------------------------------------- -@section[#:tag "scheme-hyperlinks"]{Scheme Typesetting and Hyperlinks} +@section[#:tag "racket-hyperlinks"]{Racket Typesetting and Hyperlinks} In the document source at the start of this chapter -(@secref["setting-up"]), the Scheme expression -@scheme[(#,(schemeidfont "list") 'testing 1 2 3)] is typeset properly, -but the @schemeidfont{list} identifier is not hyperlinked to the usual -definition. To cause @schemeidfont{list} to be hyperlinked, add a -@scheme[require] form like this: +(@secref["setting-up"]), the Racket expression +@racket[(#,(racketidfont "list") 'testing 1 2 3)] is typeset properly, +but the @racketidfont{list} identifier is not hyperlinked to the usual +definition. To cause @racketidfont{list} to be hyperlinked, add a +@racket[require] form like this: @verbatim[#:indent 2]|{ - @(require (for-label scheme)) + @(require (for-label racket)) }| -This @scheme[require] with @scheme[for-label] declaration introduces a -document-time binding for each export of the @schememodname[scheme] -module. When the document is built, the @scheme[scheme] form detects -the binding for @scheme[list], and so it generates a reference to the -specification of @scheme[list]. The setup process detects the +This @racket[require] with @racket[for-label] declaration introduces a +document-time binding for each export of the @racketmodname[racket] +module. When the document is built, the @racket[racket] form detects +the binding for @racket[list], and so it generates a reference to the +specification of @racket[list]. The setup process detects the reference, and it finds the matching specification in the existing documentation, and ultimately directs the hyperlink to that specification. -Hyperlinks based on @scheme[for-label] and @scheme[scheme] are the +Hyperlinks based on @racket[for-label] and @racket[racket] are the preferred mechanism for linking to information outside of a single document. Such links require no information about where and how a binding is documented elsewhere: @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @title{My Library} - See also @scheme[list]. + See also @racket[list]. }| -The @scheme[scheme] form typesets a Scheme expression for inline text, +The @racket[racket] form typesets a Racket expression for inline text, so it ignores the source formatting of the expression. The -@scheme[schemeblock] form, in contrast, typesets inset Scheme code, +@racket[racketblock] form, in contrast, typesets inset Racket code, and it preserves the expression's formatting from the document source. @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @title{My Library} - Some example Scheme code: + Some example Racket code: - @schemeblock[ + @racketblock[ (define (nobody-understands-me what) (list "When I think of all the" what @@ -141,22 +141,22 @@ and it preserves the expression's formatting from the document source. @; ---------------------------------------- @section[#:tag "section-hyperlinks"]{Section Hyperlinks} -A @scheme[section] declaration in a document can include a -@scheme[#:tag] argument that declares a hyperlink-target tag. The -@scheme[secref] function generates a hyperlink, using the section name -as the text of the hyperlink. Use @scheme[seclink] to create a +A @racket[section] declaration in a document can include a +@racket[#:tag] argument that declares a hyperlink-target tag. The +@racket[secref] function generates a hyperlink, using the section name +as the text of the hyperlink. Use @racket[seclink] to create a hyperlink with text other than the section title. The following example illustrates section hyperlinks: @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @title{My Library} - Welcome to my documentation: @scheme[(list 'testing 1 2 3)]. + Welcome to my documentation: @racket[(list 'testing 1 2 3)]. @table-of-contents[] @@ -173,23 +173,23 @@ The following example illustrates section hyperlinks: Since the page is so short, the hyperlinks in the above example are more effective if you change the @filepath{info.ss} file to add the - @scheme['multi-file] flag: + @racket['multi-file] flag: -@schemeblock[ +@racketblock[ (define scribblings '(("manual.scrbl" (multi-page)))) ] A section can have a @techlink{tag prefix} that applies to all tags as seen from outside the section. Such a prefix is automatically given to -each top-level document as processed by @exec{setup-plt}. Thus, +each top-level document as processed by @exec{raco setup}. Thus, referencing a section tag in a different document requires using a prefix, which is based on the target document's main source file. The -following example links to a section in the PLT Scheme reference +following example links to a section in the Racket reference manual: @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @(define ref-src '(lib "scribblings/reference/reference.scrbl")) @@ -198,41 +198,41 @@ manual: See also @italic{@secref[#:doc ref-src]{pairs}}. }| -As mentioned in @secref{scheme-hyperlinks}, however, cross-document -references based on @scheme[(require (for-label ....))] and -@scheme[scheme] are usually better than cross-document references -using @scheme[secref]. +As mentioned in @secref{racket-hyperlinks}, however, cross-document +references based on @racket[(require (for-label ....))] and +@racket[racket] are usually better than cross-document references +using @racket[secref]. @; ---------------------------------------- -@section{Defining Scheme Bindings} +@section{Defining Racket Bindings} -Use @scheme[defproc] to document a procedure, @scheme[defform] to -document a syntactic form, @scheme[defstruct] to document a structure +Use @racket[defproc] to document a procedure, @racket[defform] to +document a syntactic form, @racket[defstruct] to document a structure type, etc. These forms provide consistent formatting of definitions, -and they declare hyperlink targets for @scheme[scheme]-based +and they declare hyperlink targets for @racket[racket]-based hyperlinks. -To document a @scheme[my-helper] procedure that is exported by +To document a @racket[my-helper] procedure that is exported by @filepath{helper.ss} in the @filepath{my-lib} collection that contains @filepath{manual.scrbl}: @itemize[ - @item{Use @scheme[(require (for-label "helper.ss"))] to import the + @item{Use @racket[(require (for-label "helper.ss"))] to import the binding information about the bindings of @filepath{helper.ss} for use when typesetting identifiers. A relative reference - @scheme["helper.ss"] works since it is relative to the + @racket["helper.ss"] works since it is relative to the documentation source.} @item{Add a @tt|{@defmodule[my-lib/helper]}| declaration, which specifies the library that is being documented within the - section. The @scheme[defmodule] form needs an absolute module - name @scheme[mylib/helper], instead of a relative reference - @scheme["helper.ss"], since the module path given to - @scheme[defmodule] appears verbatim in the generated + section. The @racket[defmodule] form needs an absolute module + name @racket[mylib/helper], instead of a relative reference + @racket["helper.ss"], since the module path given to + @racket[defmodule] appears verbatim in the generated documentation.} - @item{Use @scheme[defproc] to document the procedure.} + @item{Use @racket[defproc] to document the procedure.} ] @@ -243,7 +243,7 @@ following: @; planet libraries @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme + @(require (for-label racket "helper.ss")) @title{My Library} @@ -254,24 +254,24 @@ following: (listof (not/c (one-of/c 'cow)))]{ - Replaces each @scheme['cow] in @scheme[lst] with - @scheme['aardvark].} + Replaces each @racket['cow] in @racket[lst] with + @racket['aardvark].} }| -In @scheme[defproc], a contract is specified with each argument to the -procedure. In this example, the contract for the @scheme[_lst] -argument is @scheme[list?], which is the contract for a list. After +In @racket[defproc], a contract is specified with each argument to the +procedure. In this example, the contract for the @racket[_lst] +argument is @racket[list?], which is the contract for a list. After the closing parenthesis that ends the argument sequence, the contract -of the result must be given; in this case, @scheme[my-helper] +of the result must be given; in this case, @racket[my-helper] guarantees a result that is a list where none of the elements are -@scheme['cow]. +@racket['cow]. Some things to notice in this example and the documentation that it generates: @itemize[ - @item{The @scheme[list?], @scheme[listof], @|etc| elements of + @item{The @racket[list?], @racket[listof], @|etc| elements of contracts are hyperlinked to their documentation.} @item{The result contract is formatted in the generated documentation @@ -279,56 +279,56 @@ generates: contracts is preserved. (In this case, putting the contract all on one line would be better.)} - @item{In the prose that documents @scheme[my-helper], @scheme[_lst] + @item{In the prose that documents @racket[my-helper], @racket[_lst] is automatically typeset in italic, matching the typesetting in - the blue box. The @scheme[scheme] form essentially knows that + the blue box. The @racket[racket] form essentially knows that it's used in the scope of a procedure with argument - @scheme[_lst].} + @racket[_lst].} - @item{If you hover the mouse pointer over @scheme[my-helper], a popup - reports that it is provided from @schemeidfont{my-lib/helper}.} + @item{If you hover the mouse pointer over @racket[my-helper], a popup + reports that it is provided from @racketidfont{my-lib/helper}.} - @item{If you use @scheme[my-helper] in any documentation now, as long - as that documentation source also has a @scheme[(require + @item{If you use @racket[my-helper] in any documentation now, as long + as that documentation source also has a @racket[(require (for-label ....))] of @filepath{helper.ss}, then the reference is hyperlinked to the definition above.} ] -See @scheme[defproc*], @scheme[defform], @|etc| for more information -on forms to document Scheme bindings. +See @racket[defproc*], @racket[defform], @|etc| for more information +on forms to document Racket bindings. @; ---------------------------------------- -@section{Showing Scheme Examples} +@section{Showing Racket Examples} -The @scheme[examples] form from @scheme[scribble/eval] +The @racket[examples] form from @racket[scribble/eval] helps you generate examples in your documentation. @bold{Warning:} the -@scheme[examples] form is especially likely to change or be replaced. +@racket[examples] form is especially likely to change or be replaced. -To use @scheme[examples], the procedures to document must be suitable -for use at documentation time; in fact, @scheme[examples] uses +To use @racket[examples], the procedures to document must be suitable +for use at documentation time; in fact, @racket[examples] uses bindings introduced into the document source by -@scheme[require]. Thus, to generate examples using @scheme[my-helper] +@racket[require]. Thus, to generate examples using @racket[my-helper] from the previous section, @filepath{helper.ss} must be imported both -via @scheme[require-for-label] and @scheme[require]: +via @racket[require-for-label] and @racket[require]: @verbatim[#:indent 2]|{ #lang scribble/manual @(require scribble/eval ; <--- added "helper.ss" ; <--- added - (for-label scheme + (for-label racket "helper.ss")) @title{My Library} - @defmodule[my-lib/helper]{The @schememodname[my-lib/helper] + @defmodule[my-lib/helper]{The @racketmodname[my-lib/helper] module---now with extra cows!} @defproc[(my-helper [lst list?]) (listof (not/c (one-of/c 'cow)))]{ - Replaces each @scheme['cow] in @scheme[lst] with - @scheme['aardvark]. + Replaces each @racket['cow] in @racket[lst] with + @racket['aardvark]. @examples[ (my-helper '()) @@ -339,14 +339,14 @@ via @scheme[require-for-label] and @scheme[require]: @;---------------------------------------- @section{Multi-Page Sections} -Setting the @scheme['multi-page] option (see +Setting the @racket['multi-page] option (see @secref["section-hyperlinks"]) causes each top-level section of a document to be rendered as a separate HTML page. -To push sub-sections onto separate pages, use the @scheme['toc] style -for the enclosing section (as started by @scheme[title], -@scheme[section], @scheme[subsection], etc.) and use -@scheme[local-table-of-contents] to generate hyperlinks to the +To push sub-sections onto separate pages, use the @racket['toc] style +for the enclosing section (as started by @racket[title], +@racket[section], @racket[subsection], etc.) and use +@racket[local-table-of-contents] to generate hyperlinks to the sub-sections. Revising @filepath{cows.scrbl} from the previous section: @@ -366,18 +366,18 @@ Revising @filepath{cows.scrbl} from the previous section: }| To run this example, remember to change @filepath{info.ss} to add the -@scheme['multi-page] style. You may also want to add a call to -@scheme[table-of-contents] in @filepath{manual.scrbl}. +@racket['multi-page] style. You may also want to add a call to +@racket[table-of-contents] in @filepath{manual.scrbl}. -The difference between @scheme[table-of-contents] and -@scheme[local-table-of-contents] is that the latter is ignored for +The difference between @racket[table-of-contents] and +@racket[local-table-of-contents] is that the latter is ignored for Latex output. -When using @scheme[local-table-of-contents], it often makes sense to +When using @racket[local-table-of-contents], it often makes sense to include introductory text before the call of -@scheme[local-table-of-contents]. When the introductory text is less +@racket[local-table-of-contents]. When the introductory text is less important and when when local table of contents is short, putting the -introductory text after the call of @scheme[local-table-of-contents] +introductory text after the call of @racket[local-table-of-contents] may be appropriate. @;---------------------------------------- diff --git a/collects/scribblings/scribble/jfp.scrbl b/collects/scribblings/scribble/jfp.scrbl index 15424cd4..06e89fa7 100644 --- a/collects/scribblings/scribble/jfp.scrbl +++ b/collects/scribblings/scribble/jfp.scrbl @@ -5,18 +5,18 @@ @(define-syntax-rule (def base-author) (begin (require (for-label scribble/base)) - (define base-author @scheme[author]))) + (define base-author @racket[author]))) @(def base-author) @title{JFP Paper Format} -@defmodulelang[scribble/jfp]{The @schememodname[scribble/jfp] -language is like @schememodname[scribble/manual], but configured with +@defmodulelang[scribble/jfp]{The @racketmodname[scribble/jfp] +language is like @racketmodname[scribble/manual], but configured with Latex style defaults to use the @filepath{jfp.cls} class file that is included with Scribble.} -Latex output with @schememodname[scribble/jfp] uses a main-document -version supplied to @scheme[title] as the short-form document name (to +Latex output with @racketmodname[scribble/jfp] uses a main-document +version supplied to @racket[title] as the short-form document name (to be used in page headers). @defproc[(abstract [pre-content pre-content?] ...) block?]{ @@ -25,19 +25,19 @@ Generates a @tech{nested flow} for a paper abstract.} @defform[(include-abstract module-path)]{ -Similar to @scheme[include-section], but incorporates the document in the +Similar to @racket[include-section], but incorporates the document in the specified module as an abstract. The document must have no title or sub-parts.} @defproc[(author [name pre-content?] ...) block?]{ -A replacement for @base-author from @schememodname[scribble/base].} +A replacement for @base-author from @racketmodname[scribble/base].} @defproc[((author/short [short-name pre-content?] ...) [long-name pre-content?] ...) block?]{ -Like @scheme[author], but allows the short-form names (to be used in +Like @racket[author], but allows the short-form names (to be used in page headers) to be specified separately from the long-form name.} @deftogether[( @@ -46,10 +46,10 @@ page headers) to be specified separately from the long-form name.} @defproc[(affiliation-sep) element?] )]{ -Use @scheme[affiliation] within @scheme[author] or the long-name part -of @scheme[author/short] to specify affiliations after all authors. +Use @racket[affiliation] within @racket[author] or the long-name part +of @racket[author/short] to specify affiliations after all authors. If different authors have different affiliations, use -@scheme[affiliation-mark] with a number after each author, and then -use @scheme[affiliation-mark] before each different affiliation within -a single @scheme[affiliation], using @scheme[(affiliation-sep)] to +@racket[affiliation-mark] with a number after each author, and then +use @racket[affiliation-mark] before each different affiliation within +a single @racket[affiliation], using @racket[(affiliation-sep)] to separate affiliations.} diff --git a/collects/scribblings/scribble/layers.scrbl b/collects/scribblings/scribble/layers.scrbl index db1aea9f..5583ef34 100644 --- a/collects/scribblings/scribble/layers.scrbl +++ b/collects/scribblings/scribble/layers.scrbl @@ -16,31 +16,31 @@ and instead use the document-generation structure directly. A Scribble document normally starts -@schememod[ +@racketmod[ scribble/manual ] but it could also start -@schememod[ +@racketmod[ scribble/base ] or -@schememod[ +@racketmod[ scribble/doc ] The last one introduces the smallest number of typesetting bindings in -the document body. Using @schememodname[scribble/base] after -@hash-lang[] is the same as using @schememodname[scribble/doc] plus -@scheme[(require scribble/base)], and using -@schememodname[scribble/manual] after @hash-lang[] is the same as using -@schememodname[scribble/doc] plus @scheme[(require scribble/manual)]. +the document body. Using @racketmodname[scribble/base] after +@hash-lang[] is the same as using @racketmodname[scribble/doc] plus +@racket[(require scribble/base)], and using +@racketmodname[scribble/manual] after @hash-lang[] is the same as using +@racketmodname[scribble/doc] plus @racket[(require scribble/manual)]. Besides making the file a module, each of the @hash-lang[] -declarations selects the Scribble reader (instead of the usual Scheme +declarations selects the Scribble reader (instead of the usual Racket reader), and it starts the body of the file in ``text'' mode. The reader layer mostly leaves text alone, but @litchar["@"] forms escape to S-expression mode. @@ -61,7 +61,7 @@ A module written as reads as -@schemeblock[ +@racketblock[ (module #,(nonterm "name") scribble/doc (require scribble/manual) "\n" @@ -74,14 +74,14 @@ reads as ] As shown in this example, the read result is a module whose content -mingles text and definitions. The @schememodname[scribble/doc] -language lifts definitions, @scheme[require]s, and @scheme[provide]s +mingles text and definitions. The @racketmodname[scribble/doc] +language lifts definitions, @racket[require]s, and @racket[provide]s to the beginning of the module, while everything else is collected -into a document bound to the provided identifier @scheme[doc]. That +into a document bound to the provided identifier @racket[doc]. That is, the module is transformed to something like this: -@schemeblock[ -(module #,(nonterm "name") scheme/base +@racketblock[ +(module #,(nonterm "name") racket/base (require scribble/decode scribble/manual) (define to-be "To Be") @@ -95,23 +95,23 @@ is, the module is transformed to something like this: (provide doc)) ] -The @scheme[decode] function produces a @scheme[part] structure -instance that represents the document. To build the @scheme[part] -instance, it inspects its arguments to find a @scheme[title-decl] -value created by @scheme[title] to name the part, @scheme[part-start] -values created by @scheme[section] to designate sub-parts, etc. +The @racket[decode] function produces a @racket[part] structure +instance that represents the document. To build the @racket[part] +instance, it inspects its arguments to find a @racket[title-decl] +value created by @racket[title] to name the part, @racket[part-start] +values created by @racket[section] to designate sub-parts, etc. -A @scheme[part] is the input to a rendering back-end, such as the HTML +A @racket[part] is the input to a rendering back-end, such as the HTML renderer. All renderers recognize a fixed structure hierarchy: the content of a part is a @defterm{flow}, which is a sequence of @defterm{flow elements}, such as paragraphs and tables; a table, in turn, consists of a list of list of flows; a paragraph is a list of -@defterm{elements}, which can be instances of the @scheme[element] +@defterm{elements}, which can be instances of the @racket[element] structure type, plain strings, or certain special symbols. -The value bound to @scheme[doc] in the example above is something like +The value bound to @racket[doc] in the example above is something like -@schemeblock[ +@racketblock[ (make-part .... (list "To Be" " or Not " "To Be") (code:comment "title") .... @@ -125,38 +125,38 @@ The value bound to @scheme[doc] in the example above is something like ] Notice that the @litchar{'} in the input's @litchar{'tis} has turned -into @scheme['rsquo] (rendered as a curly apostrophe). The conversion to use -@scheme['rsquo] was performed by @scheme[decode] via -@scheme[decode-flow] via @scheme[decode-paragraph] via -@scheme[decode-content] via @scheme[decode-string]. +into @racket['rsquo] (rendered as a curly apostrophe). The conversion to use +@racket['rsquo] was performed by @racket[decode] via +@racket[decode-flow] via @racket[decode-paragraph] via +@racket[decode-content] via @racket[decode-string]. -In contrast, @scheme[(make-element 'bold (list "That"))] was produced -by the @scheme[bold] function. The @scheme[decode] operation is a -function, not a syntactic form, and so @scheme[bold] has control over -its argument before @scheme[decode] sees the result. Also, decoding +In contrast, @racket[(make-element 'bold (list "That"))] was produced +by the @racket[bold] function. The @racket[decode] operation is a +function, not a syntactic form, and so @racket[bold] has control over +its argument before @racket[decode] sees the result. Also, decoding traverses only immediate string arguments. -As it turns out, @scheme[bold] also decodes its argument, because the -@scheme[bold] function is implemented as +As it turns out, @racket[bold] also decodes its argument, because the +@racket[bold] function is implemented as -@schemeblock[ +@racketblock[ (define (bold . strs) (make-element 'bold (decode-content strs))) ] -The @scheme[verbatim] function, however, does not decode its content, +The @racket[verbatim] function, however, does not decode its content, and instead typesets its text arguments directly. A document module can construct elements directly using -@scheme[make-element], but normally functions like @scheme[bold] and -@scheme[verbatim] are used to construct them. In particular, the -@schememodname[scribble/manual] library provides many functions and +@racket[make-element], but normally functions like @racket[bold] and +@racket[verbatim] are used to construct them. In particular, the +@racketmodname[scribble/manual] library provides many functions and forms to typeset elements and flow elements. -The @scheme[part] structure hierarchy includes built-in element types +The @racket[part] structure hierarchy includes built-in element types for setting hyperlink targets and references. Again, this machinery is normally packaged into higher-level functions and forms, such as -@scheme[secref], @scheme[defproc], and @scheme[scheme]. +@racket[secref], @racket[defproc], and @racket[racket]. @; ---------------------------------------------------------------------- @@ -166,76 +166,76 @@ Working roughly from the bottom up, the Scribble layers are: @itemize[ - @item{@schememodname[scribble/reader]: A reader that extends the - syntax of Scheme with @"@"-forms for conveniently embedding a + @item{@racketmodname[scribble/reader]: A reader that extends the + syntax of Racket with @"@"-forms for conveniently embedding a mixin of text and escapes. See @secref["reader"].} - @item{@schememodname[scribble/core]: A set of document datatypes + @item{@racketmodname[scribble/core]: A set of document datatypes and utilities that define the basic layout and processing of a - document. For example, the @scheme[part] datatype is defined in + document. For example, the @racket[part] datatype is defined in this layer. See @secref["core"].} - @item{@schememodname[scribble/base-render] with - @schememodname[scribble/html-render], - @schememodname[scribble/latex-render], or - @schememodname[scribble/text-render]: A base renderer and + @item{@racketmodname[scribble/base-render] with + @racketmodname[scribble/html-render], + @racketmodname[scribble/latex-render], or + @racketmodname[scribble/text-render]: A base renderer and mixins that generate documents in various formats from - instances of the @schememodname[scribble/struct] datatypes. See + instances of the @racketmodname[scribble/struct] datatypes. See @secref["renderer"].} - @item{@schememodname[scribble/decode]: Processes a stream of text, + @item{@racketmodname[scribble/decode]: Processes a stream of text, section-start markers, etc. to produce instances of the - @schememodname[scribble/core] datatypes. See + @racketmodname[scribble/core] datatypes. See @secref["decode"].} - @item{@schememodname[scribble/doclang]: A language to be used for the + @item{@racketmodname[scribble/doclang]: A language to be used for the initial import of a module; processes the module top level - through @schememodname[scribble/decode], and otherwise provides - all of @schememodname[scheme/base]. See @secref["doclang"].} + through @racketmodname[scribble/decode], and otherwise provides + all of @racketmodname[racket/base]. See @secref["doclang"].} - @item{@schememodname[scribble/doc]: A language that combines - @schememodname[scribble/reader] with - @schememodname[scribble/doclang]. See @secref["docreader"].} + @item{@racketmodname[scribble/doc]: A language that combines + @racketmodname[scribble/reader] with + @racketmodname[scribble/doclang]. See @secref["docreader"].} - @item{@schememodname[scribble/base]: A library of basic document - operators---such as @scheme[title], @scheme[section], and - @scheme[secref]---for use with @schememodname[scribble/decode] + @item{@racketmodname[scribble/base]: A library of basic document + operators---such as @racket[title], @racket[section], and + @racket[secref]---for use with @racketmodname[scribble/decode] and a renderer. This library name also can be used as a - language, where it combines @schememodname[scribble/doc] with - the exports of @schememodname[scribble/base]. See + language, where it combines @racketmodname[scribble/doc] with + the exports of @racketmodname[scribble/base]. See @secref["base"].} - @item{@schememodname[scribble/scheme]: A library of functions for - typesetting Scheme code. See @secref["scheme"]. These functions + @item{@racketmodname[scribble/racket]: A library of functions for + typesetting Racket code. See @secref["scheme"]. These functions are not normally used directly, but instead used through - @schememodname[scribble/manual].} + @racketmodname[scribble/manual].} - @item{@schememodname[scribble/manual]: A library of functions for - writing PLT Scheme documentation; re-exports - @schememodname[scribble/base]. Also, the - @schememodname[scribble/manual-struct] library provides types + @item{@racketmodname[scribble/manual]: A library of functions for + writing Racket documentation; re-exports + @racketmodname[scribble/base]. Also, the + @racketmodname[scribble/manual-struct] library provides types for index-entry descriptions created by functions in - @schememodname[scribble/manual]. See @secref["manual"].} + @racketmodname[scribble/manual]. See @secref["manual"].} - @item{@schememodname[scribble/eval]: A library of functions for + @item{@racketmodname[scribble/eval]: A library of functions for evaluating code at document-build time, especially for showing examples. See @secref["eval"].} - @item{@schememodname[scribble/bnf]: A library of support functions + @item{@racketmodname[scribble/bnf]: A library of support functions for writing grammars. See @secref["bnf"].} - @item{@schememodname[scribble/xref]: A library of support functions + @item{@racketmodname[scribble/xref]: A library of support functions for using cross-reference information, typically after a document is rendered (e.g., to search). See @secref["xref"].} - @item{@schememodname[scribble/text]: A language that uses - @schememodname[scribble/reader] preprocessing text files.} + @item{@racketmodname[scribble/text]: A language that uses + @racketmodname[scribble/reader] preprocessing text files.} ] The @exec{scribble} command-line utility generates output with a specified renderer. More specifically, the executable installs a renderer, loads the modules specified on the command line, extracts -the @scheme[doc] export of each module (which must be an instance of -@scheme[part]), and renders each---potentially with links that span +the @racket[doc] export of each module (which must be an instance of +@racket[part]), and renders each---potentially with links that span documents. diff --git a/collects/scribblings/scribble/lp.scrbl b/collects/scribblings/scribble/lp.scrbl index 2814d6ad..a876995b 100644 --- a/collects/scribblings/scribble/lp.scrbl +++ b/collects/scribblings/scribble/lp.scrbl @@ -3,7 +3,7 @@ scribble/core scribble/html-properties scribble/latex-properties - scheme/runtime-path + racket/runtime-path (prefix-in lp-ex: "lp-ex-doc.scrbl") "utils.ss" (for-label scribble/lp-include scribble/lp)) @@ -14,17 +14,17 @@ (make-tex-addition "lp.tex"))) ]{Literate Programming} -Programs written using @schememodname[scribble/lp] are simultaneously +Programs written using @racketmodname[scribble/lp] are simultaneously two things: a program and a document describing the program. -Programs in @schememodname[scribble/lp] are viewed in two different +Programs in @racketmodname[scribble/lp] are viewed in two different ways, either by running the program directly or by including it with -@scheme[lp-include]. When running the program, all of the -@scheme[chunk] expressions are collected and stitched together into a +@racket[lp-include]. When running the program, all of the +@racket[chunk] expressions are collected and stitched together into a program, and the rest of the module is discarded. When using -@scheme[lp-include], the entire contents of the module are preserved +@racket[lp-include], the entire contents of the module are preserved and are treated like an ordinary Scribble document, where -@scheme[chunk]s are typeset in a manner similar to @scheme[codeblock]. +@racket[chunk]s are typeset in a manner similar to @racket[codeblock]. @(define-runtime-path lp-ex "lp-ex.rkt") @@ -44,31 +44,31 @@ For example, consider this program: [else (list* line "\n" (loop))]))))))) -When this file is @scheme[require]d in the normal manner, it defines a -function @scheme[f] that squares its argument, and the documentation -is ignored. When it is included with @scheme[lp-include], it looks +When this file is @racket[require]d in the normal manner, it defines a +function @racket[f] that squares its argument, and the documentation +is ignored. When it is included with @racket[lp-include], it looks like this: @(make-nested-flow (make-style "LPBoxed" null) (part-blocks lp-ex:doc)) -@section{@schememodname[scribble/lp] Language} +@section{@racketmodname[scribble/lp] Language} -@defmodulelang[scribble/lp]{The @schememodname[scribble/lp] language +@defmodulelang[scribble/lp]{The @racketmodname[scribble/lp] language provides core support for literate programming.} @defform[(chunk id form ...)]{ - Introduces a chunk, binding @scheme[id] for use in other - chunks. Normally, @scheme[id] starts with @litchar{<} and ends with + Introduces a chunk, binding @racket[id] for use in other + chunks. Normally, @racket[id] starts with @litchar{<} and ends with @litchar{>}. When running a scribble program only the code inside the chunks is run; the rest is ignored. - If @scheme[id] is @schemeidfont{<*>}, then this chunk is - used as the main chunk in the file. If @schemeidfont{<*>} + If @racket[id] is @racketidfont{<*>}, then this chunk is + used as the main chunk in the file. If @racketidfont{<*>} is never used, then the first chunk in the file is treated as the main chunk. If some chunk is not referenced from the main chunk (possibly indirectly via other chunks that @@ -77,15 +77,15 @@ provides core support for literate programming.} } -@section{@schememodname[scribble/lp-include] Module} +@section{@racketmodname[scribble/lp-include] Module} @defmodule[scribble/lp-include]{The -@schememodname[scribble/lp-include] library is normally used within a +@racketmodname[scribble/lp-include] library is normally used within a Scribble document---that is, a module that starts with something like -@scheme[#, @hash-lang[] scribble/base] or @scheme[#, @hash-lang[] -scribble/manual], instead of @scheme[#, @hash-lang[] scheme].} +@racket[#, @hash-lang[] scribble/base] or @racket[#, @hash-lang[] +scribble/manual], instead of @racket[#, @hash-lang[] racket].} @defform[(lp-include filename)]{ -Includes the source of @scheme[filename] as the typeset version of the literate +Includes the source of @racket[filename] as the typeset version of the literate program. } diff --git a/collects/scribblings/scribble/manual-stub.scrbl b/collects/scribblings/scribble/manual-stub.scrbl index 68cbb8b1..b373d528 100644 --- a/collects/scribblings/scribble/manual-stub.scrbl +++ b/collects/scribblings/scribble/manual-stub.scrbl @@ -2,7 +2,7 @@ @(require "utils.ss" (for-label scribble/sigplan)) -@title{PLT Scheme Manual Format} +@title{Racket Manual Format} The @schememodname[scribble/manual] language is a major component of Scribble, and it is documented in its own chapter: diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index a0552269..773fd9f7 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -1,255 +1,285 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label scribble/manual-struct)) -@(define lit-ellipses (scheme ...)) -@(define lit-ellipses+ (scheme ...+)) +@(define lit-ellipses (racket ...)) +@(define lit-ellipses+ (racket ...+)) @title[#:tag "manual" #:style 'toc]{Manual Forms} -@defmodulelang[scribble/manual]{The @schememodname[scribble/manual] -language provides all of @schememodname[scribble/base] plus many -additional functions that are specific to writing PLT Scheme +@defmodulelang[scribble/manual]{The @racketmodname[scribble/manual] +language provides all of @racketmodname[scribble/base] plus many +additional functions that are specific to writing Racket documentation. -The @schememodname[scribble/manual] name can also be used as a library -with @scheme[require], in which case it provides all of the same +The @racketmodname[scribble/manual] name can also be used as a library +with @racket[require], in which case it provides all of the same bindings, but without setting the reader or setting the default -rendering format to the PLT Scheme manual format.} +rendering format to the Racket manual format.} -With @hash-lang[], @schememodname[scribble/manual] associates a -@scheme[latex-defaults] @tech{style property} with its @scheme[doc] -export to select the default PLT Scheme manual style for Latex -rendering---unless a style is supplied to @scheme[title] that already -includes a @scheme[latex-defaults] @tech{style property}. +With @hash-lang[], @racketmodname[scribble/manual] associates a +@racket[latex-defaults] @tech{style property} with its @racket[doc] +export to select the default Racket manual style for Latex +rendering---unless a style is supplied to @racket[title] that already +includes a @racket[latex-defaults] @tech{style property}. @local-table-of-contents[] @; ------------------------------------------------------------------------ @section[#:tag "scribble:manual:code"]{Typesetting Code} -@defform[(schemeblock datum ...)]{ +@defform[(racketblock datum ...)]{ -Typesets the @scheme[datum] sequence as a table of Scheme code inset -by two spaces. The source locations of the @scheme[datum]s determine +Typesets the @racket[datum] sequence as a table of Racket code inset +by two spaces. The source locations of the @racket[datum]s determine the generated layout. For example, -@schemeblock[ -(schemeblock +@racketblock[ +(racketblock (define (loop x) (loop (not x)))) ] produces the output -@schemeblock[ +@racketblock[ (define (loop x) (loop (not x))) ] -with the @scheme[(loop (not x))] indented under @scheme[define], -because that's the way it is idented the use of @scheme[schemeblock]. +with the @racket[(loop (not x))] indented under @racket[define], +because that's the way it is idented the use of @racket[racketblock]. -Furthermore, @scheme[define] is typeset as a keyword (bold and black) -and as a hyperlink to @scheme[define]'s definition in the reference +Furthermore, @racket[define] is typeset as a keyword (bold and black) +and as a hyperlink to @racket[define]'s definition in the reference manual, because this document was built using a for-label binding of -@scheme[define] (in the source) that matches a definition in the -reference manual. Similarly, @scheme[not] is a hyperlink to the its +@racket[define] (in the source) that matches a definition in the +reference manual. Similarly, @racket[not] is a hyperlink to the its definition in the reference manual. -Use @scheme[unsyntax] to escape back to an expression that produces an -@scheme[element]. For example, +Use @racket[unsyntax] to escape back to an expression that produces an +@racket[element]. For example, @let[([unsyntax #f]) -(schemeblock - (schemeblock - (+ 1 (unsyntax (elem (scheme x) (subscript "2")))))) +(racketblock + (racketblock + (+ 1 (unsyntax (elem (racket x) (subscript "2")))))) ] produces -@schemeblock[ -(+ 1 (unsyntax (elem (scheme x) (subscript "2")))) +@racketblock[ +(+ 1 (unsyntax (elem (racket x) (subscript "2")))) ] -The @scheme[unsyntax] form is regonized via -@scheme[free-identifier=?], so if you want to typeset code that -includes @scheme[unsyntax], you can simply hide the usual binding: +The @racket[unsyntax] form is regonized via +@racket[free-identifier=?], so if you want to typeset code that +includes @racket[unsyntax], you can simply hide the usual binding: -@SCHEMEBLOCK[ -(schemeblock - (let ([(UNSYNTAX (scheme unsyntax)) #f]) - (schemeblock +@RACKETBLOCK[ +(racketblock + (let ([(UNSYNTAX (racket unsyntax)) #f]) + (racketblock (syntax (+ 1 (unsyntax x)))))) ] -Or use @scheme[SCHEMEBLOCK], whose escape form is @scheme[UNSYNTAX] -instead of @scheme[unsyntax]. +Or use @racket[RACKETBLOCK], whose escape form is @racket[UNSYNTAX] +instead of @racket[unsyntax]. A few other escapes are recognized symbolically: @itemize[ - @item{@scheme[(#,(scheme code:line) _datum ...)] typesets as the - sequence of @scheme[_datum]s (i.e., without the - @scheme[code:line] wrapper).} + @item{@racket[(#,(indexed-racket code:line) _datum ...)] typesets as the + sequence of @racket[_datum]s (i.e., without the + @racket[code:line] wrapper).} - @item{@scheme[(#,(scheme code:comment) _datum)] typesets like - @scheme[_datum], but colored as a comment and prefixed with a - semi-colon. A typical @scheme[_datum] escapes from - Scheme-typesetting mode using @scheme[unsyntax] and - produces a paragraph using @scheme[t]: + @item{@racket[(#,(indexed-racket code:comment) _datum)] typesets like + @racket[_datum], but colored as a comment and prefixed with a + semi-colon. A typical @racket[_datum] escapes from + Racket-typesetting mode using @racket[unsyntax] and + produces a paragraph using @racket[t]: @verbatim[#:indent 2]|{ (code:comment @#,t{this is a comment}) }| (Note that @litchar|{@#,foo{...}}| reads as - @SCHEME[(unsyntax (foo "..."))].) + @RACKET[(unsyntax (foo "..."))].) } - @item{@schemeidfont{code:blank} typesets as a blank space.} + @item{@indexed-racket[code:blank] typesets as a blank space.} - @item{@scheme[(#,(scheme code:hilite) _datum)] typesets like - @scheme[_datum], but with a background highlight.} + @item{@racket[(#,(indexed-racket code:hilite) _datum)] typesets like + @racket[_datum], but with a background highlight.} - @item{@scheme[(#,(scheme code:quote) _datum)] typesets like - @scheme[(@#,schemeidfont{quote} _datum)], but without rendering the - @schemeidfont{quote} as @litchar{'}.} + @item{@racket[(#,(indexed-racket code:quote) _datum)] typesets like + @racket[(@#,racketidfont{quote} _datum)], but without rendering the + @racketidfont{quote} as @litchar{'}.} - @item{@schemeidfont{_}@scheme[_id] typesets as @scheme[id], but - colored as a variable (like @scheme[schemevarfont]); this - escape applies only if @schemeidfont{_}@scheme[_id] has no + @item{@racketidfont{_}@racket[_id] typesets as @racket[id], but + colored as a variable (like @racket[racketvarfont]); this + escape applies only if @racketidfont{_}@racket[_id] has no for-label binding and is not specifically colored as a subform - non-terminal via @scheme[defform], a variable via - @scheme[defproc], etc.} + non-terminal via @racket[defform], a variable via + @racket[defproc], etc.} ] -See also @schememodname[scribble/comment-reader]. +See also @racketmodname[scribble/comment-reader]. } -@defform[(SCHEMEBLOCK datum ...)]{Like @scheme[schemeblock], but with -the expression escape @scheme[UNSYNTAX] instead of @scheme[unsyntax].} +@defform[(RACKETBLOCK datum ...)]{Like @racket[racketblock], but with +the expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].} -@defform[(schemeblock0 datum ...)]{Like @scheme[schemeblock], but +@defform[(racketblock0 datum ...)]{Like @racket[racketblock], but without insetting the code.} -@defform[(SCHEMEBLOCK0 datum ...)]{Like @scheme[SCHEMEBLOCK], but +@defform[(RACKETBLOCK0 datum ...)]{Like @racket[RACKETBLOCK], but without insetting the code.} -@defform[(schemeinput datum ...)]{Like @scheme[schemeblock], but the -@scheme[datum] are typeset after a prompt representing a REPL.} +@defform[(racketinput datum ...)]{Like @racket[racketblock], but the +@racket[datum] are typeset after a prompt representing a REPL.} -@defform[(schememod lang datum ...)]{Like @scheme[schemeblock], but -the @scheme[datum] are typeset inside a @schememodfont{#lang}-form -module whose language is @scheme[lang]. The source location of -@scheme[lang] (relative to the body @scheme[datum]s) determines the -relative positioning of the @schememodfont{#lang} line in the typeset +@defform[(racketmod lang datum ...)]{Like @racket[racketblock], but +the @racket[datum] are typeset inside a @racketmodfont{#lang}-form +module whose language is @racket[lang]. The source location of +@racket[lang] (relative to the body @racket[datum]s) determines the +relative positioning of the @racketmodfont{#lang} line in the typeset output.} -@defform[(scheme datum ...)]{Like @scheme[schemeblock], but typeset on +@defform[(racket datum ...)]{Like @racket[racketblock], but typeset on a single line and wrapped with its enclosing paragraph, independent of -the formatting of @scheme[datum].} +the formatting of @racket[datum].} -@defform[(SCHEME datum ...)]{Like @scheme[scheme], but with the -@scheme[UNSYNTAX] escape like @scheme[schemeblock].} +@defform[(RACKET datum ...)]{Like @racket[racket], but with the +@racket[UNSYNTAX] escape like @racket[racketblock].} -@defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset +@defform[(racketresult datum ...)]{Like @racket[racket], but typeset as a REPL value (i.e., a single color with no hyperlinks).} -@defform[(schemeid datum ...)]{Like @scheme[scheme], but typeset +@defform[(racketid datum ...)]{Like @racket[racket], but typeset as an unbound identifier (i.e., no coloring or hyperlinks).} -@defform*[((schememodname datum) - (schememodname ((unsyntax (scheme unsyntax)) expr)))]{ -Like @scheme[scheme], but typeset as a module path. If @scheme[datum] -is an identifier or @scheme[expr] produces a symbol, then it is +@defform*[((racketmodname datum) + (racketmodname ((unsyntax (racket unsyntax)) expr)))]{ +Like @racket[racket], but typeset as a module path. If @racket[datum] +is an identifier or @racket[expr] produces a symbol, then it is hyperlinked to the module path's definition as created by -@scheme[defmodule].} +@racket[defmodule].} -@defform[(schememodlink datum pre-content-expr ...)]{ -Like @scheme[schememod], but separating the module path to link -from the content to be linked. The @scheme[datum] module path is always +@defform[(racketmodlink datum pre-content-expr ...)]{ +Like @racket[racketmod], but separating the module path to link +from the content to be linked. The @racket[datum] module path is always linked, even if it is not an identifier.} -@defproc[(litchar [str string?] ...) element?]{Typesets @scheme[str]s as a +@defproc[(litchar [str string?] ...) element?]{Typesets @racket[str]s as a representation of literal text. Use this when you have to talk about the individual characters in a stream of text, as as when documenting a reader extension.} -@defproc[(schemefont [pre-content pre-content?] ...) element?]{Typesets -@tech{decode}d @scheme[pre-content] as uncolored, unhyperlinked -Scheme. This procedure is useful for typesetting things like -@schemefont{#lang}, which are not @scheme[read]able by themselves.} +@defproc[(racketfont [pre-content pre-content?] ...) element?]{Typesets +@tech{decode}d @racket[pre-content] as uncolored, unhyperlinked +Racket. This procedure is useful for typesetting things like +@racketfont{#lang}, which are not @racket[read]able by themselves.} -@defproc[(schemevalfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a value.} +@defproc[(racketvalfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a value.} -@defproc[(schemeresultfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a REPL result.} +@defproc[(racketresultfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a REPL result.} -@defproc[(schemeidfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as an identifier.} +@defproc[(racketidfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as an identifier.} -@defproc[(schemevarfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a variable (i.e., an argument or +@defproc[(racketvarfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a variable (i.e., an argument or sub-form in a procedure being documented).} -@defproc[(schemekeywordfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a syntactic form name.} +@defproc[(racketkeywordfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a syntactic form name.} -@defproc[(schemeparenfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored like parentheses.} +@defproc[(racketparenfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored like parentheses.} -@defproc[(schememetafont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as meta-syntax, such as backquote or +@defproc[(racketmetafont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as meta-syntax, such as backquote or unquote.} -@defproc[(schemeerror [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as error-message text.} +@defproc[(racketerror [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as error-message text.} -@defproc[(schememodfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as module name.} +@defproc[(racketmodfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as module name.} -@defproc[(schemeoutput [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as output.} +@defproc[(racketoutput [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as output.} @defproc[(procedure [pre-content pre-content?] ...) element?]{Typesets -@tech{decode}d @scheme[pre-content] as a procedure name in a REPL +@tech{decode}d @racket[pre-content] as a procedure name in a REPL result (e.g., in typewriter font with a @litchar{#} suffix.).} -@defform[(var datum)]{Typesets @scheme[datum] as an identifier that is +@defform[(var datum)]{Typesets @racket[datum] as an identifier that is an argument or sub-form in a procedure being documented. Normally, the -@scheme[defproc] and @scheme[defform] arrange for @scheme[scheme] to +@racket[defproc] and @racket[defform] arrange for @racket[racket] to format such identifiers automatically in the description of the -procedure, but use @scheme[var] if that cannot work for some reason.} +procedure, but use @racket[var] if that cannot work for some reason.} -@defform[(svar datum)]{Like @scheme[var], but for subform non-terminals +@defform[(svar datum)]{Like @racket[var], but for subform non-terminals in a form definition.} +@deftogether[( +@defform[(schemeblock datum ...)] +@defform[(SCHEMEBLOCK datum ...)] +@defform[(schemeblock0 datum ...)] +@defform[(SCHEMEBLOCK0 datum ...)] +@defform[(schemeinput datum ...)] +@defform[(schememod lang datum ...)] +@defform[(scheme datum ...)] +@defform[(SCHEME datum ...)] +@defform[(schemeresult datum ...)] +@defform[(schemeid datum ...)] +@defform*[((schememodname datum) + (schememodname ((unsyntax (scheme unsyntax)) expr)))] +@defform[(schememodlink datum pre-content-expr ...)] +@defproc[(schemefont [pre-content pre-content?] ...) element?] +@defproc[(schemevalfont [pre-content pre-content?] ...) element?] +@defproc[(schemeresultfont [pre-content pre-content?] ...) element?] +@defproc[(schemeidfont [pre-content pre-content?] ...) element?] +@defproc[(schemevarfont [pre-content pre-content?] ...) element?] +@defproc[(schemekeywordfont [pre-content pre-content?] ...) element?] +@defproc[(schemeparenfont [pre-content pre-content?] ...) element?] +@defproc[(schememetafont [pre-content pre-content?] ...) element?] +@defproc[(schemeerror [pre-content pre-content?] ...) element?] +@defproc[(schememodfont [pre-content pre-content?] ...) element?] +@defproc[(schemeoutput [pre-content pre-content?] ...) element?] +)]{ + +Compatibility aliases. Each @racketidfont{scheme...} name is an alias for the +corresponding @racketidfont{racket...} binding.} + @; ------------------------------------------------------------------------ @subsection{Typesetting Comments} @defmodulereader[scribble/comment-reader] -As a reader module, @schememodname[scribble/comment-reader] reads a +As a reader module, @racketmodname[scribble/comment-reader] reads a single S-expression that contains @litchar{;}-based comment lines, and -it wraps the comments with @scheme[code:comment] for use with forms -like @scheme[schemeblock]. More precisely, -@schememodname[scribble/comment-reader] extends the current reader to +it wraps the comments with @racket[code:comment] for use with forms +like @racket[racketblock]. More precisely, +@racketmodname[scribble/comment-reader] extends the current reader to adjust the parsing of @litchar{;}. For example, within a Scribble document that imports -@schememodname[scribble/manual], +@racketmodname[scribble/manual], @verbatim[#:indent 2]|{ @#reader scribble/comment-reader - (schemeblock + (racketblock ;; This is not a pipe (make-pipe) ) @@ -258,19 +288,19 @@ For example, within a Scribble document that imports generates @#reader scribble/comment-reader - (schemeblock + (racketblock ;; This is not a pipe (make-pipe) ) The initial @litchar["@"] is needed above to shift into S-expression -mode, so that @schememetafont{#reader} is recognized as a reader +mode, so that @racketmetafont{#reader} is recognized as a reader declaration instead of literal text. Also, the example uses -@scheme[(schemeblock ....)] instead of -@schememetafont["@"]@scheme[schemeblock]@schememetafont["["]@scheme[....]@schememetafont["]"] +@racket[(racketblock ....)] instead of +@racketmetafont["@"]@racket[racketblock]@racketmetafont["["]@racket[....]@racketmetafont["]"] because the @"@"-reader would drop comments within the -@scheme[schemeblock] before giving -@schememodname[scribble/comment-reader] a chance to convert them. +@racket[racketblock] before giving +@racketmodname[scribble/comment-reader] a chance to convert them. @; ------------------------------------------------------------------------ @section[#:tag "doc-modules"]{Documenting Modules} @@ -281,41 +311,41 @@ because the @"@"-reader would drop comments within the [maybe-sources code:blank (code:line #:use-sources (mod-path ...))])]{ -Produces a sequence of flow elements (encaptured in a @scheme[splice]) -to start the documentation for a module that can be @scheme[require]d -using the path @scheme[id]. The @tech{decode}d @scheme[pre-flow]s +Produces a sequence of flow elements (encaptured in a @racket[splice]) +to start the documentation for a module that can be @racket[require]d +using the path @racket[id]. The @tech{decode}d @racket[pre-flow]s introduce the module, but need not include all of the module content. Besides generating text, this form expands to a use of -@scheme[declare-exporting] with @scheme[id]; the -@scheme[#:use-sources] clause, if provided, is propagated to -@scheme[declare-exporting]. Consequently, @scheme[defmodule] should be +@racket[declare-exporting] with @racket[id]; the +@racket[#:use-sources] clause, if provided, is propagated to +@racket[declare-exporting]. Consequently, @racket[defmodule] should be used at most once in a section, though it can be shadowed with -@scheme[defmodule]s in sub-sections. +@racket[defmodule]s in sub-sections. -If a @scheme[#:require-form] clause is provided, the given expression -produces an element to use instead of @scheme[(scheme require)] for +If a @racket[#:require-form] clause is provided, the given expression +produces an element to use instead of @racket[(racket require)] for the declaration of the module. This is useful to suggest a different -way of accessing the module instead of through @scheme[require]. +way of accessing the module instead of through @racket[require]. -Hyperlinks created by @scheme[schememodname] are associated with the -enclosing section, rather than the local @scheme[id] text.} +Hyperlinks created by @racket[racketmodname] are associated with the +enclosing section, rather than the local @racket[id] text.} @defform*[[(defmodulelang id maybe-sources pre-flow ...) (defmodulelang content-expr #:module-paths (mod-path ...) maybe-sources pre-flow ...)]]{ -Like @scheme[defmodule], but documents @scheme[id] as a module path -suitable for use by either @scheme[require] or @hash-lang[]. If the -module path for @scheme[require] is syntactically different from the -@hash-lang[] form, use the @scheme[#:module-paths] to provide them +Like @racket[defmodule], but documents @racket[id] as a module path +suitable for use by either @racket[require] or @hash-lang[]. If the +module path for @racket[require] is syntactically different from the +@hash-lang[] form, use the @racket[#:module-paths] to provide them separately.} @defform[(defmodulereader id maybe-sources pre-flow ...)]{ -Like @scheme[defmodule], but documents @scheme[id] as a module path -suitable for use with @schememetafont{#reader}.} +Like @racket[defmodule], but documents @racket[id] as a module path +suitable for use with @racketmetafont{#reader}.} @deftogether[( @@ -326,7 +356,7 @@ suitable for use with @schememetafont{#reader}.} @defform[(defmodulereader* (id ...+) maybe-sources pre-flow ...)] )]{ -Like @scheme[defmodule], etc., but introduces multiple module paths instead +Like @racket[defmodule], etc., but introduces multiple module paths instead of just one.} @deftogether[( @@ -337,54 +367,54 @@ of just one.} @defform[(defmodulereader*/no-declare (id ...) pre-flow ...)] )]{ -Like @scheme[defmodule*], etc., but without expanding to -@scheme[declare-exporting]. Use this form when you want to provide a +Like @racket[defmodule*], etc., but without expanding to +@racket[declare-exporting]. Use this form when you want to provide a more specific list of modules (e.g., to name both a specific module and one that combines several modules) via your own -@scheme[declare-exporting] declaration.} +@racket[declare-exporting] declaration.} @defform/subs[(declare-exporting mod-path ... maybe-sources) ([maybe-sources code:blank (code:line #:use-sources (mod-path ...))])]{ -Associates the @scheme[mod-path]s to all bindings defined within the +Associates the @racket[mod-path]s to all bindings defined within the enclosing section, except as overridden by other -@scheme[declare-exporting] declarations in nested sub-sections. The -list of @scheme[mod-path]s is shown, for example, when the user hovers +@racket[declare-exporting] declarations in nested sub-sections. The +list of @racket[mod-path]s is shown, for example, when the user hovers the mouse over one of the bindings defined within the section. -More significantly, the first @scheme[mod-path] plus the -@scheme[#:use-sources] @scheme[mod-path]s determine the binding that -is documented by each @scheme[defform], @scheme[defproc], or similar -form within the section that contains the @scheme[declare-exporting] +More significantly, the first @racket[mod-path] plus the +@racket[#:use-sources] @racket[mod-path]s determine the binding that +is documented by each @racket[defform], @racket[defproc], or similar +form within the section that contains the @racket[declare-exporting] declaration: @itemize[ - @item{If no @scheme[#:use-sources] clause is supplied, then the + @item{If no @racket[#:use-sources] clause is supplied, then the documentation applies to the given name as exported by the first - @scheme[mod-path].} + @racket[mod-path].} - @item{If @scheme[#:use-sources] @scheme[mod-path]s are supplied, then + @item{If @racket[#:use-sources] @racket[mod-path]s are supplied, then they are tried in order. The first one to provide an export with the same symbolic name and - @scheme[free-label-identifier=?] to the given name is used as + @racket[free-label-identifier=?] to the given name is used as the documented binding. This binding is assumed to be the same - as the identifier as exported by the first @scheme[mod-path] in - the @scheme[declare-exporting] declaration.} + as the identifier as exported by the first @racket[mod-path] in + the @racket[declare-exporting] declaration.} ] -The initial @scheme[mod-path]s sequence can be empty if -@scheme[mod-path]s are given with @scheme[#:use-sources]. In that +The initial @racket[mod-path]s sequence can be empty if +@racket[mod-path]s are given with @racket[#:use-sources]. In that case, the rendered documentation never reports an exporting module for identifiers that are documented within the section, but the -@scheme[mod-path]s in @scheme[#:use-sources] provide a binding context +@racket[mod-path]s in @racket[#:use-sources] provide a binding context for connecting (via hyperlinks) definitions and uses of identifiers. -The @scheme[declare-exporting] form should be used no more than once +The @racket[declare-exporting] form should be used no more than once per section, since the declaration applies to the entire section, -although overriding @scheme[declare-exporting] forms can appear in +although overriding @racket[declare-exporting] forms can appear in sub-sections.} @; ------------------------------------------------------------------------ @@ -405,25 +435,25 @@ sub-sections.} [ellipses+ @#,lit-ellipses+])]{ Produces a sequence of flow elements (encapsulated in a -@scheme[splice]) to document a procedure named @scheme[id]. Nesting -@scheme[prototype]s corresponds to a curried function, as in -@scheme[define]. The @scheme[id] is indexed, and it also registered so -that @scheme[scheme]-typeset uses of the identifier (with the same +@racket[splice]) to document a procedure named @racket[id]. Nesting +@racket[prototype]s corresponds to a curried function, as in +@racket[define]. The @racket[id] is indexed, and it also registered so +that @racket[racket]-typeset uses of the identifier (with the same for-label binding) are hyperlinked to this documentation. -A @scheme[defmodule] or @scheme[declare-exporting] form (or one of the -variants) in an enclosing section determines the @scheme[id] binding -that is being defined. The @scheme[id] should also have a for-label -binding (as introduced by @scheme[(require (for-label ....))]) that -matches the definition binding; otherwise, the defined @scheme[id] +A @racket[defmodule] or @racket[declare-exporting] form (or one of the +variants) in an enclosing section determines the @racket[id] binding +that is being defined. The @racket[id] should also have a for-label +binding (as introduced by @racket[(require (for-label ....))]) that +matches the definition binding; otherwise, the defined @racket[id] will not typeset correctly within the definition. -Each @scheme[arg-spec] must have one of the following forms: +Each @racket[arg-spec] must have one of the following forms: @specsubform[(arg-id contract-expr-datum)]{ An argument whose contract is specified by - @scheme[contract-expr-datum] which is typeset via - @scheme[schemeblock0].} + @racket[contract-expr-datum] which is typeset via + @racket[racketblock0].} @specsubform[(arg-id contract-expr-datum default-expr)]{ Like the previous case, but with a default value. All arguments @@ -440,21 +470,21 @@ Each @scheme[arg-spec] must have one of the following forms: @specsubform[@#,lit-ellipses]{Any number of the preceding argument. This form is normally used at the end, but keyword-based arguments can sensibly appear afterward. See also the documentation for - @scheme[append] for a use of @lit-ellipses before the last + @racket[append] for a use of @lit-ellipses before the last argument.} @specsubform[@#,lit-ellipses+]{One or more of the preceding argument (normally at the end, like @lit-ellipses).} -The @scheme[result-contract-expr-datum] is typeset via -@scheme[schemeblock0], and it represents a contract on the procedure's +The @racket[result-contract-expr-datum] is typeset via +@racket[racketblock0], and it represents a contract on the procedure's result. -The @tech{decode}d @scheme[pre-flow] documents the procedure. In this -description, references to @svar[arg-id]s using @scheme[scheme], -@scheme[schemeblock], @|etc| are typeset as procedure arguments. +The @tech{decode}d @racket[pre-flow] documents the procedure. In this +description, references to @svar[arg-id]s using @racket[racket], +@racket[racketblock], @|etc| are typeset as procedure arguments. -The typesetting of all information before the @scheme[pre-flow]s +The typesetting of all information before the @racket[pre-flow]s ignores the source layout, except that the local formatting is preserved for contracts and default-values expressions.} @@ -463,13 +493,13 @@ preserved for contracts and default-values expressions.} result-contract-expr-datum] ...) pre-flow ...)]{ -Like @scheme[defproc], but for multiple cases with the same -@scheme[id]. +Like @racket[defproc], but for multiple cases with the same +@racket[id]. -When an @scheme[id] has multiple calling cases, they must be defined -with a single @scheme[defproc*], so that a single definition point -exists for the @scheme[id]. However, multiple distinct @scheme[id]s -can also be defined by a single @scheme[defproc*], for the case that +When an @racket[id] has multiple calling cases, they must be defined +with a single @racket[defproc*], so that a single definition point +exists for the @racket[id]. However, multiple distinct @racket[id]s +can also be defined by a single @racket[defproc*], for the case that it's best to document a related group of procedures at once.} @@ -484,74 +514,74 @@ it's best to document a related group of procedures at once.} ...))])]{ Produces a sequence of flow elements (encapsulated in a -@scheme[splice]) to document a syntatic form named by @scheme[id] -whose syntax is described by @scheme[form-datum]. If no @scheme[#:id] is used -to specify @scheme[id], then @scheme[form-datum] must have the form -@scheme[(id . _datum)]. +@racket[splice]) to document a syntatic form named by @racket[id] +whose syntax is described by @racket[form-datum]. If no @racket[#:id] is used +to specify @racket[id], then @racket[form-datum] must have the form +@racket[(id . _datum)]. -The @scheme[id] is indexed, and it is also registered so that -@scheme[scheme]-typeset uses of the identifier (with the same +The @racket[id] is indexed, and it is also registered so that +@racket[racket]-typeset uses of the identifier (with the same for-label binding) are hyperlinked to this documentation. -The @scheme[defmodule] or @scheme[declare-exporting] requirements, as -well as the binding requirements for @scheme[id], are the same as for -@scheme[defproc]. +The @racket[defmodule] or @racket[declare-exporting] requirements, as +well as the binding requirements for @racket[id], are the same as for +@racket[defproc]. -The @tech{decode}d @scheme[pre-flow] documents the form. In this -description, a reference to any identifier in @scheme[form-datum] via -@scheme[scheme], @scheme[schemeblock], @|etc| is typeset as a sub-form -non-terminal. If @scheme[#:literals] clause is provided, however, -instances of the @scheme[literal-id]s are typeset normally (i.e., as +The @tech{decode}d @racket[pre-flow] documents the form. In this +description, a reference to any identifier in @racket[form-datum] via +@racket[racket], @racket[racketblock], @|etc| is typeset as a sub-form +non-terminal. If @racket[#:literals] clause is provided, however, +instances of the @racket[literal-id]s are typeset normally (i.e., as determined by the enclosing context). -If a @scheme[#:contracts] clause is provided, each -@scheme[subform-datum] (typically an identifier that serves as a -meta-variable in @scheme[form-datum]) is shown as producing a value -that must satisfy the contract described by @scheme[contract-expr-datum]. +If a @racket[#:contracts] clause is provided, each +@racket[subform-datum] (typically an identifier that serves as a +meta-variable in @racket[form-datum]) is shown as producing a value +that must satisfy the contract described by @racket[contract-expr-datum]. -The typesetting of @scheme[form-datum], @scheme[subform-datum], and -@scheme[contract-expr-datum] preserves the source layout, like -@scheme[schemeblock].} +The typesetting of @racket[form-datum], @racket[subform-datum], and +@racket[contract-expr-datum] preserves the source layout, like +@racket[racketblock].} @defform[(defform* maybe-id maybe-literals [form-datum ...+] maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but for multiple forms using the same -@scheme[_id].} +Like @racket[defform], but for multiple forms using the same +@racket[_id].} @defform[(defform/subs maybe-id maybe-literals form-datum ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but including an auxiliary grammar of -non-terminals shown with the @scheme[_id] form. Each -@scheme[nonterm-id] is specified as being any of the corresponding -@scheme[clause-datum]s, where the formatting of each -@scheme[clause-datum] is preserved.} +Like @racket[defform], but including an auxiliary grammar of +non-terminals shown with the @racket[_id] form. Each +@racket[nonterm-id] is specified as being any of the corresponding +@racket[clause-datum]s, where the formatting of each +@racket[clause-datum] is preserved.} @defform[(defform*/subs maybe-id maybe-literals [form-datum ...] maybe-contracts pre-flow ...)]{ -Like @scheme[defform/subs], but for multiple forms for @scheme[_id].} +Like @racket[defform/subs], but for multiple forms for @racket[_id].} @defform[(defform/none maybe-literal form-datum maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but without registering a definition.} +Like @racket[defform], but without registering a definition.} @defform[(defidform id pre-flow ...)]{ -Like @scheme[defform], but with a plain @scheme[id] as the form.} +Like @racket[defform], but with a plain @racket[id] as the form.} @defform[(defidform/inline id)]{ -Like @scheme[defidform], but @racket[id] is typeset as an inline +Like @racket[defidform], but @racket[id] is typeset as an inline element. Use this form sparingly, because the typeset form does not stand out to the reader as a specification of @racket[id].} @@ -559,24 +589,24 @@ stand out to the reader as a specification of @racket[id].} @defform[(specform maybe-literals datum maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but without indexing or registering a +Like @racket[defform], but without indexing or registering a definition, and with indenting on the left for both the specification -and the @scheme[pre-flow]s.} +and the @racket[pre-flow]s.} @defform[(specsubform maybe-literals datum maybe-contracts pre-flow ...)]{ -Similar to @scheme[defform], but without any specific identifier being +Similar to @racket[defform], but without any specific identifier being defined, and the table and flow are typeset indented. This form is intended for use when refining the syntax of a non-terminal used in a -@scheme[defform] or other @scheme[specsubform]. For example, it is -used in the documentation for @scheme[defproc] in the itemization of +@racket[defform] or other @racket[specsubform]. For example, it is +used in the documentation for @racket[defproc] in the itemization of possible shapes for @svar[arg-spec]. -The @scheme[pre-flow]s list is parsed as a flow that documents the +The @racket[pre-flow]s list is parsed as a flow that documents the procedure. In this description, a reference to any identifier in -@scheme[datum] is typeset as a sub-form non-terminal.} +@racket[datum] is typeset as a sub-form non-terminal.} @defform[(specsubform/subs maybe-literals datum @@ -584,16 +614,16 @@ procedure. In this description, a reference to any identifier in maybe-contracts pre-flow ...)]{ -Like @scheme[specsubform], but with a grammar like -@scheme[defform/subs].} +Like @racket[specsubform], but with a grammar like +@racket[defform/subs].} @defform[(specspecsubform maybe-literals datum maybe-contracts pre-flow ...)]{ -Like @scheme[specsubform], but indented an extra level. Since using -@scheme[specsubform] within the body of @scheme[specsubform] already -nests indentation, @scheme[specspecsubform] is for extra indentation +Like @racket[specsubform], but indented an extra level. Since using +@racket[specsubform] within the body of @racket[specsubform] already +nests indentation, @racket[specspecsubform] is for extra indentation without nesting a description.} @@ -602,27 +632,27 @@ without nesting a description.} maybe-contracts pre-flow ...)]{ -Like @scheme[specspecsubform], but with a grammar like -@scheme[defform/subs].} +Like @racket[specspecsubform], but with a grammar like +@racket[defform/subs].} @defform[(defparam id arg-id contract-expr-datum pre-flow ...)]{ -Like @scheme[defproc], but for a parameter. The -@scheme[contract-expr-datum] serves as both the result contract on the +Like @racket[defproc], but for a parameter. The +@racket[contract-expr-datum] serves as both the result contract on the parameter and the contract on values supplied for the parameter. The -@scheme[arg-id] refers to the parameter argument in the latter case.} +@racket[arg-id] refers to the parameter argument in the latter case.} @defform[(defboolparam id arg-id pre-flow ...)]{ -Like @scheme[defparam], but the contract on a parameter argument is -@scheme[any/c], and the contract on the parameter result is -@scheme[boolean?].} +Like @racket[defparam], but the contract on a parameter argument is +@racket[any/c], and the contract on the parameter result is +@racket[boolean?].} @defform[(defthing id contract-expr-datum pre-flow ...)]{ -Like @scheme[defproc], but for a non-procedure binding.} +Like @racket[defproc], but for a non-procedure binding.} @deftogether[( @defform[ (defstruct* struct-name ([field-name contract-expr-datum] ...) @@ -643,34 +673,34 @@ Like @scheme[defproc], but for a non-procedure binding.} (code:line #:extra-constructor-name constructor-id)])] )]{ -Similar to @scheme[defform] or @scheme[defproc], but for a structure -definition. The @scheme[defstruct*] form corresponds to @scheme[struct], -while @scheme[defstruct] corresponds to @scheme[define-struct].} +Similar to @racket[defform] or @racket[defproc], but for a structure +definition. The @racket[defstruct*] form corresponds to @racket[struct], +while @racket[defstruct] corresponds to @racket[define-struct].} @defform[(deftogether [def-expr ...] pre-flow ...)]{ -Combines the definitions created by the @scheme[def-expr]s into a -single definition box. Each @scheme[def-expr] should produce a -definition point via @scheme[defproc], @scheme[defform], etc. Each -@scheme[def-expr] should have an empty @scheme[pre-flow]; the -@tech{decode}d @scheme[pre-flow] sequence for the @scheme[deftogether] +Combines the definitions created by the @racket[def-expr]s into a +single definition box. Each @racket[def-expr] should produce a +definition point via @racket[defproc], @racket[defform], etc. Each +@racket[def-expr] should have an empty @racket[pre-flow]; the +@tech{decode}d @racket[pre-flow] sequence for the @racket[deftogether] form documents the collected bindings.} -@defform/subs[(schemegrammar maybe-literals id clause-datum ...+) +@defform/subs[(racketgrammar maybe-literals id clause-datum ...+) ([maybe-literals code:blank (code:line #:literals (literal-id ...))])]{ -Creates a table to define the grammar of @scheme[id]. Each identifier -mentioned in a @scheme[clause-datum] is typeset as a non-terminal, -except for the identifiers listed as @scheme[literal-id]s, which are -typeset as with @scheme[scheme].} +Creates a table to define the grammar of @racket[id]. Each identifier +mentioned in a @racket[clause-datum] is typeset as a non-terminal, +except for the identifiers listed as @racket[literal-id]s, which are +typeset as with @racket[racket].} -@defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)]{ +@defform[(racketgrammar* maybe-literals [id clause-datum ...+] ...)]{ -Like @scheme[schemegrammar], but for typesetting multiple productions +Like @racket[racketgrammar], but for typesetting multiple productions at once, aligned around the @litchar{=} and @litchar{|}.} @defproc[(defidentifier [id identifier?] @@ -679,23 +709,31 @@ at once, aligned around the @litchar{=} and @litchar{|}.} [#:show-libs? show-libs? boolean? #t]) element?]{ -Typesets @scheme[id] as a Scheme identifier, and also establishes the +Typesets @racket[id] as a Racket identifier, and also establishes the identifier as the definition of a binding in the same way as -@scheme[defproc], @scheme[defform], etc. As always, the library that -provides the identifier must be declared via @scheme[defmodule] or -@scheme[declare-exporting] for an enclosing section. +@racket[defproc], @racket[defform], etc. As always, the library that +provides the identifier must be declared via @racket[defmodule] or +@racket[declare-exporting] for an enclosing section. -If @scheme[form?] is a true value, then the identifier is documented +If @racket[form?] is a true value, then the identifier is documented as a syntactic form, so that uses of the identifier (normally -including @scheme[id] itself) are typeset as a syntactic form. +including @racket[id] itself) are typeset as a syntactic form. -If @scheme[index?] is a true value, then the identifier is registered +If @racket[index?] is a true value, then the identifier is registered in the index. -If @scheme[show-libs?] is a true value, then the identifier's defining +If @racket[show-libs?] is a true value, then the identifier's defining module may be exposed in the typeset form (e.g., when viewing HTML and the mouse hovers over the identifier).} +@deftogether[( +@defform[(schemegrammar maybe-literals id clause-datum ...+)] +@defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)] +)]{ + +Compatibility aliases for @racket[racketgrammar] and @racket[racketgrammar*].} + + @; ------------------------------------------------------------------------ @section[#:tag "doc-classes"]{Documenting Classes and Interfaces} @@ -703,75 +741,75 @@ the mouse hovers over the identifier).} ([super super-id (mixin-id super)])]{ -Creates documentation for a class @scheme[id] that is a subclass of -@scheme[super] and implements each interface @scheme[intf-id]. Each -identifier in @scheme[super] (except @scheme[object%]) and -@scheme[intf-id] must be documented somewhere via @scheme[defclass] or -@scheme[definterface]. +Creates documentation for a class @racket[id] that is a subclass of +@racket[super] and implements each interface @racket[intf-id]. Each +identifier in @racket[super] (except @racket[object%]) and +@racket[intf-id] must be documented somewhere via @racket[defclass] or +@racket[definterface]. -The decoding of the @scheme[pre-flow] sequence should start with +The decoding of the @racket[pre-flow] sequence should start with general documentation about the class, followed by constructor -definition (see @scheme[defconstructor]), and then field and method -definitions (see @scheme[defmethod]). In rendered form, the +definition (see @racket[defconstructor]), and then field and method +definitions (see @racket[defmethod]). In rendered form, the constructor and method specification are indented to visually group them under the class definition.} @defform[(defclass/title id super (intf-id ...) pre-flow ...)]{ -Like @scheme[defclass], also includes a @scheme[title] declaration -with the style @scheme['hidden]. In addition, the constructor and +Like @racket[defclass], also includes a @racket[title] declaration +with the style @racket['hidden]. In addition, the constructor and methods are not left-indented. This form is normally used to create a section to be rendered on its -own HTML. The @scheme['hidden] style is used because the definition +own HTML. The @racket['hidden] style is used because the definition box serves as a title.} @defform[(definterface id (intf-id ...) pre-flow ...)]{ -Like @scheme[defclass], but for an interfaces. Naturally, -@scheme[pre-flow] should not generate a constructor declaration.} +Like @racket[defclass], but for an interfaces. Naturally, +@racket[pre-flow] should not generate a constructor declaration.} @defform[(definterface/title id (intf-id ...) pre-flow ...)]{ -Like @scheme[definterface], but for single-page rendering as in -@scheme[defclass/title].} +Like @racket[definterface], but for single-page rendering as in +@racket[defclass/title].} @defform[(defmixin id (domain-id ...) (range-id ...) pre-flow ...)]{ -Like @scheme[defclass], but for a mixin. Any number of -@scheme[domain-id] classes and interfaces are specified for the +Like @racket[defclass], but for a mixin. Any number of +@racket[domain-id] classes and interfaces are specified for the mixin's input requires, and any number of result classes and (more -likely) interfaces are specified for the @scheme[range-id]. The -@scheme[domain-id]s supply inherited methods.} +likely) interfaces are specified for the @racket[range-id]. The +@racket[domain-id]s supply inherited methods.} @defform[(defmixin/title id (domain-id ...) (range-id ...) pre-flow ...)]{ -Like @scheme[defmixin], but for single-page rendering as in -@scheme[defclass/title].} +Like @racket[defmixin], but for single-page rendering as in +@racket[defclass/title].} @defform/subs[(defconstructor (arg-spec ...) pre-flow ...) ([arg-spec (arg-id contract-expr-datum) (arg-id contract-expr-datum default-expr)])]{ -Like @scheme[defproc], but for a constructor declaration in the body -of @scheme[defclass], so no return contract is specified. Also, the -@scheme[new]-style keyword for each @scheme[arg-spec] is implicit from -the @scheme[arg-id].} +Like @racket[defproc], but for a constructor declaration in the body +of @racket[defclass], so no return contract is specified. Also, the +@racket[new]-style keyword for each @racket[arg-spec] is implicit from +the @racket[arg-id].} @defform[(defconstructor/make (arg-spec ...) pre-flow ...)]{ -Like @scheme[defconstructor], but specifying by-position -initialization arguments (for use with @scheme[make-object]) instead -of by-name arguments (for use with @scheme[new]).} +Like @racket[defconstructor], but specifying by-position +initialization arguments (for use with @racket[make-object]) instead +of by-name arguments (for use with @racket[new]).} @defform[(defconstructor*/make [(arg-spec ...) ...] pre-flow ...)]{ -Like @scheme[defconstructor/make], but with multiple constructor -patterns analogous @scheme[defproc*].} +Like @racket[defconstructor/make], but with multiple constructor +patterns analogous @racket[defproc*].} @defform[(defconstructor/auto-super [(arg-spec ...) ...] pre-flow ...)]{ -Like @scheme[defconstructor], but the constructor is +Like @racket[defconstructor], but the constructor is annotated to indicate that additional initialization arguments are accepted and propagated to the superclass.} @@ -790,13 +828,13 @@ accepted and propagated to the superclass.} (code:line #:mode extend) (code:line #:mode extend-final)])]{ -Like @scheme[defproc], but for a method within a @scheme[defclass] or -@scheme[definterface] body. +Like @racket[defproc], but for a method within a @racket[defclass] or +@racket[definterface] body. -The @scheme[maybe-mode] specifies whether the method overrides a +The @racket[maybe-mode] specifies whether the method overrides a method from a superclass, and so on. (For these purposes, use -@scheme[#:mode override] when refining a method of an implemented -interface.) The @scheme[extend] mode is like @scheme[override], but +@racket[#:mode override] when refining a method of an implemented +interface.) The @racket[extend] mode is like @racket[override], but the description of the method should describe only extensions to the superclass implementation.} @@ -805,23 +843,23 @@ superclass implementation.} result-contract-expr-datum] ...) pre-flow ...)]{ -Like @scheme[defproc*], but for a method within a @scheme[defclass] or -@scheme[definterface] body. The @scheme[maybe-mode] specification is as in -@scheme[defmethod].} +Like @racket[defproc*], but for a method within a @racket[defclass] or +@racket[definterface] body. The @racket[maybe-mode] specification is as in +@racket[defmethod].} @defform[(method class/intf-id method-id)]{ -Creates a hyperlink to the method named by @scheme[method-id] in the -class or interface named by @scheme[class/intf-id]. The hyperlink -names the method, only; see also @scheme[xmethod]. +Creates a hyperlink to the method named by @racket[method-id] in the +class or interface named by @racket[class/intf-id]. The hyperlink +names the method, only; see also @racket[xmethod]. -For-label binding information is used with @scheme[class/intf-id], but -not @scheme[method-id].} +For-label binding information is used with @racket[class/intf-id], but +not @racket[method-id].} @defform[(xmethod class/intf-id method-id)]{ -Like @scheme[method], but the hyperlink shows both the method name and +Like @racket[method], but the hyperlink shows both the method name and the containing class/interface.} @; ------------------------------------------------------------------------ @@ -829,78 +867,78 @@ the containing class/interface.} @defform[(defsignature id (super-id ...) pre-flow ...)]{ -Defines a signature @scheme[id] that extends the @scheme[super-id] +Defines a signature @racket[id] that extends the @racket[super-id] signatures. Any elements defined in @tech{decode}d -@scheme[pre-flow]s---including forms, procedures, structure types, +@racket[pre-flow]s---including forms, procedures, structure types, classes, interfaces, and mixins---are defined as members of the signature instead of direct bindings. These definitions can be -referenced through @scheme[sigelem] instead of @scheme[scheme]. +referenced through @racket[sigelem] instead of @racket[racket]. -The @tech{decode}d @scheme[pre-flow]s inset under the signature +The @tech{decode}d @racket[pre-flow]s inset under the signature declaration in the typeset output, so no new sections, @|etc| can be started.} @defform[(defsignature/splice id (super-id ...) pre-flow ...)]{ -Like @scheme[defsignature], but the @tech{decode}d @scheme[pre-flow]s +Like @racket[defsignature], but the @tech{decode}d @racket[pre-flow]s are not typeset under the signature declaration, and new sections, -@|etc| can be started in the @scheme[pre-flow]s.} +@|etc| can be started in the @racket[pre-flow]s.} @defproc[(signature-desc [pre-flow pre-flow?] ...) any/c]{ -Produces an opaque value that @scheme[defsignature] recognizes to +Produces an opaque value that @racket[defsignature] recognizes to outdent in the typeset form. This is useful for text describing the signature as a whole to appear right after the signature declaration.} @defform[(sigelem sig-id id)]{ -Typesets the identifier @scheme[id] with a hyperlink to its definition -as a member of the signature named by @scheme[sig-id].} +Typesets the identifier @racket[id] with a hyperlink to its definition +as a member of the signature named by @racket[sig-id].} @; ------------------------------------------------------------------------ @section[#:tag "doc-strings"]{Various String Forms} @defproc[(aux-elem [pre-content pre-content?] ...) element?]{ -Like @scheme[elem], but adds an @scheme['aux] @tech{style property}.} +Like @racket[elem], but adds an @racket['aux] @tech{style property}.} @defproc[(defterm [pre-content pre-content?] ...) element?]{Typesets the -@tech{decode}d @scheme[pre-content] as a defined term (e.g., in -italic). Consider using @scheme[deftech] instead, though, so that uses -of @scheme[tech] can hyper-link to the definition.} +@tech{decode}d @racket[pre-content] as a defined term (e.g., in +italic). Consider using @racket[deftech] instead, though, so that uses +of @racket[tech] can hyper-link to the definition.} @defproc[(onscreen [pre-content pre-content?] ...) element?]{ Typesets the -@tech{decode}d @scheme[pre-content] as a string that appears in a GUI, +@tech{decode}d @racket[pre-content] as a string that appears in a GUI, such as the name of a button.} @defproc[(menuitem [menu-name string?] [item-name string?]) element?]{ Typesets the given combination of a GUI's menu and item name.} @defproc[(filepath [pre-content pre-content?] ...) element?]{Typesets the -@tech{decode}d @scheme[pre-content] as a file name (e.g., in +@tech{decode}d @racket[pre-content] as a file name (e.g., in typewriter font and in in quotes).} @defproc[(exec [pre-content pre-content?] ...) element?]{Typesets the -@tech{decode}d @scheme[pre-content] as a command line (e.g., in +@tech{decode}d @racket[pre-content] as a command line (e.g., in typewriter font).} @defproc[(envvar [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] as an environment variable (e.g., +@tech{decode}d @racket[pre-content] as an environment variable (e.g., in typewriter font).} @defproc[(Flag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] as a flag (e.g., in typewriter +@tech{decode}d @racket[pre-content] as a flag (e.g., in typewriter font with a leading @litchar{-}).} @defproc[(DFlag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] a long flag (e.g., in typewriter +@tech{decode}d @racket[pre-content] a long flag (e.g., in typewriter font with two leading @litchar{-}s).} @defproc[(PFlag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] as a @litchar{+} flag (e.g., in typewriter +@tech{decode}d @racket[pre-content] as a @litchar{+} flag (e.g., in typewriter font with a leading @litchar{+}).} @defproc[(DPFlag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] a long @litchar{+} flag (e.g., in +@tech{decode}d @racket[pre-content] a long @litchar{+} flag (e.g., in typewriter font with two leading @litchar{+}s).} @; ------------------------------------------------------------------------ @@ -908,35 +946,39 @@ typewriter font with two leading @litchar{+}s).} See also @secref["base-links"]. -@defform[(schemelink id pre-content ...) +@defform[(racketlink id pre-content ...) #:contracts ([id identifier?] [pre-content pre-content?])]{ -An element where the @tech{decode}d @scheme[pre-content] is hyperlinked to the definition -of @scheme[id].} +An element where the @tech{decode}d @racket[pre-content] is hyperlinked to the definition +of @racket[id].} + +@defform[(schemelink id pre-content ...)]{ + +Compatibility alias for @racket[racketlink].} @defproc[(link [url string?] [pre-content any/c] ... [#:underline? underline? any/c #t] [#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")]) element?]{ -An alias of @scheme[hyperlink] for backward compatibility.} +Alias of @racket[hyperlink] for backward compatibility.} @defproc[(other-manual [module-path module-path?] [#:underline? underline? any/c #t]) element?]{ -An alias of @scheme[other-doc] for backward compatibility.} +Alias of @racket[other-doc] for backward compatibility.} @defproc[(deftech [pre-content pre-content?] ... [#:style? style? boolean? #t]) element?]{ -Produces an element for the @tech{decode}d @scheme[pre-content], and +Produces an element for the @tech{decode}d @racket[pre-content], and also defines a term that can be referenced elsewhere using -@scheme[tech]. +@racket[tech]. -The @scheme[content->string] result of the @tech{decode}d -@scheme[pre-content] is used as a key for references, but normalized +The @racket[content->string] result of the @tech{decode}d +@racket[pre-content] is used as a key for references, but normalized as follows: @itemize[ @@ -954,22 +996,22 @@ These normalization steps help support natural-language references that differ slightly from a defined form. For example, a definition of ``bananas'' can be referenced with a use of ``banana''. -If @scheme[style?] is true, then @scheme[defterm] is used on -@scheme[pre-content].} +If @racket[style?] is true, then @racket[defterm] is used on +@racket[pre-content].} @defproc[(tech [pre-content pre-content?] ... [#:doc module-path (or/c module-path? false/c) #f] [#:tag-prefixes prefixes (or/c (listof string?) false/c) #f]) element?]{ -Produces an element for the @tech{decode}d @scheme[pre-content], and +Produces an element for the @tech{decode}d @racket[pre-content], and hyperlinks it to the definition of the content as established by -@scheme[deftech]. The content's string form is normalized in the same -way as for @scheme[deftech]. The @scheme[#:doc] and -@scheme[#:tag-prefixes] arguments support cross-document and -section-specific references, like in @scheme[secref]. +@racket[deftech]. The content's string form is normalized in the same +way as for @racket[deftech]. The @racket[#:doc] and +@racket[#:tag-prefixes] arguments support cross-document and +section-specific references, like in @racket[secref]. -With the default style files, the hyperlink created by @scheme[tech] +With the default style files, the hyperlink created by @racket[tech] is somewhat quieter than most hyperlinks: the underline in HTML output is gray, instead of blue, and the term and underline turn blue only when the mouse is moved over the term. @@ -978,14 +1020,14 @@ In some cases, combining both natural-language uses of a term and proper linking can require some creativity, even with the normalization performed on the term. For example, if ``bind'' is defined, but a sentence uses the term ``binding,'' the latter can be -linked to the former using @schemefont["@tech{bind}ing"].} +linked to the former using @racketfont["@tech{bind}ing"].} @defproc[(techlink [pre-content pre-content?] ... [#:doc module-path (or/c module-path? false/c) #f] [#:tag-prefixes prefixes (or/c (listof string?) false/c) #f]) element?]{ -Like @scheme[tech], but the link is not a quiet. For example, in HTML +Like @racket[tech], but the link is not a quiet. For example, in HTML output, a hyperlink underline appears even when the mouse is not over the link.} @@ -994,37 +1036,41 @@ the link.} See also @secref["base-indexing"]. -@defform[(indexed-scheme datum ...)]{ +@defform[(indexed-racket datum ...)]{ -A combination of @scheme[scheme] and @scheme[as-index], with the -following special cases when a single @scheme[datum] is provided: +A combination of @racket[racket] and @racket[as-index], with the +following special cases when a single @racket[datum] is provided: @itemize[ - @item{If @scheme[datum] is a @scheme[quote] form, then the quote is + @item{If @racket[datum] is a @racket[quote] form, then the quote is removed from the key (so that it's sorted using its unquoted form).} - @item{If @scheme[datum] is a string, then quotes are removed from the + @item{If @racket[datum] is a string, then quotes are removed from the key (so that it's sorted using the string content).} ]} +@defform[(indexed-scheme datum ...)]{ + +Compatibility alias for @racket[indexed-racket].} + @defproc[(idefterm [pre-content pre-content?] ...) element?]{Combines -@scheme[as-index] and @scheme[defterm]. The content normally should be -plural, rather than singular. Consider using @scheme[deftech], +@racket[as-index] and @racket[defterm]. The content normally should be +plural, rather than singular. Consider using @racket[deftech], instead, which always indexes.} @defproc[(pidefterm [pre-content pre-content?] ...) element?]{Like -@scheme[idefterm], but plural: adds an ``s'' on the end of the content -for the index entry. Consider using @scheme[deftech], instead.} +@racket[idefterm], but plural: adds an ``s'' on the end of the content +for the index entry. Consider using @racket[deftech], instead.} @defproc[(indexed-file [pre-content pre-content?] ...) element?]{A -combination of @scheme[file] and @scheme[as-index], but where the sort +combination of @racket[file] and @racket[as-index], but where the sort key for the index iterm does not include quotes.} @defproc[(indexed-envvar [pre-content pre-content?] ...) element?]{A -combination of @scheme[envvar] and @scheme[as-index].} +combination of @racket[envvar] and @racket[as-index].} @; ------------------------------------------------------------------------ @section[#:tag "manual-images"]{Images} @@ -1033,16 +1079,16 @@ combination of @scheme[envvar] and @scheme[as-index].} [pre-element any/c] ...) element?]{ - An alias for @scheme[image] for backward compatibility.} + An alias for @racket[image] for backward compatibility.} @; ------------------------------------------------------------------------ @section{Bibliography} -@margin-note{See also @schememodname[scriblib/autobib].} +@margin-note{See also @racketmodname[scriblib/autobib].} @defproc[(cite [key string?] ...+) element?]{ -Links to a bibliography entry, using the @scheme[key]s both to indicate the +Links to a bibliography entry, using the @racket[key]s both to indicate the bibliography entry and, in square brackets, as the link text.} @defproc[(bibliography [#:tag tag string? "doc-bibliography"] @@ -1050,7 +1096,7 @@ bibliography entry and, in square brackets, as the link text.} part?]{ Creates a bibliography part containing the given entries, each of -which is created with @scheme[bib-entry]. The entries are typeset in +which is created with @racket[bib-entry]. The entries are typeset in order as given.} @defproc[(bib-entry [#:key key string?] @@ -1062,52 +1108,52 @@ order as given.} [#:url url (or/c false/c pre-content?) #f]) bib-entry?]{ -Creates a bibliography entry. The @scheme[key] is used to refer to the -entry via @scheme[cite]. The other arguments are used as elements in +Creates a bibliography entry. The @racket[key] is used to refer to the +entry via @racket[cite]. The other arguments are used as elements in the entry: @itemize[ - @item{@scheme[title] is the title of the cited work. It will be - surrounded by quotes in typeset form if @scheme[is-book?] is - @scheme[#f], otherwise it is typeset via @scheme[italic].} + @item{@racket[title] is the title of the cited work. It will be + surrounded by quotes in typeset form if @racket[is-book?] is + @racket[#f], otherwise it is typeset via @racket[italic].} - @item{@scheme[author] lists the authors. Use names in their usual + @item{@racket[author] lists the authors. Use names in their usual order (as opposed to ``last, first''), and separate multiple names with commas using ``and'' before the last name (where - there are multiple names). The @scheme[author] is typeset in + there are multiple names). The @racket[author] is typeset in the bibliography as given, or it is omitted if given as - @scheme[#f].} + @racket[#f].} - @item{@scheme[location] names the publication venue, such as a + @item{@racket[location] names the publication venue, such as a conference name or a journal with volume, number, and - pages. The @scheme[location] is typeset in the bibliography as - given, or it is omitted if given as @scheme[#f].} + pages. The @racket[location] is typeset in the bibliography as + given, or it is omitted if given as @racket[#f].} - @item{@scheme[date] is a date, usually just a year (as a string). It + @item{@racket[date] is a date, usually just a year (as a string). It is typeset in the bibliography as given, or it is omitted if - given as @scheme[#f].} + given as @racket[#f].} - @item{@scheme[url] is an optional URL. It is typeset in the - bibliography using @scheme[tt] and hyperlinked, or it is - omitted if given as @scheme[#f].} + @item{@racket[url] is an optional URL. It is typeset in the + bibliography using @racket[tt] and hyperlinked, or it is + omitted if given as @racket[#f].} ]} @defproc[(bib-entry? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a bibliography entry created by -@scheme[bib-entry], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a bibliography entry created by +@racket[bib-entry], @racket[#f] otherwise.} @; ------------------------------------------------------------------------ @section{Miscellaneous} @defproc[(t [pre-content pre-content?] ...) paragraph?]{Wraps the -@tech{decode}d @scheme[pre-content] as a paragraph.} +@tech{decode}d @racket[pre-content] as a paragraph.} -@defthing[PLaneT element?]{@scheme["PLaneT"] (to help make sure you get +@defthing[PLaneT element?]{@racket["PLaneT"] (to help make sure you get the letters in the right case).} @defproc[(hash-lang) element?]{Returns an element for @hash-lang[] @@ -1122,14 +1168,14 @@ an inset command-line example (e.g., in typewriter font).} @defproc[(centerline [pre-flow pre-flow?] ...) nested-flow?]{ -An alias for @scheme[centered] for backward compatibility.} +An alias for @racket[centered] for backward compatibility.} @defproc[(math [pre-content any/c] ...) element?]{The @tech{decode}d -@scheme[pre-content] is further transformed: +@racket[pre-content] is further transformed: @itemize[ - @item{Any immediate @scheme['rsquo] is converted to @scheme['prime].} + @item{Any immediate @racket['rsquo] is converted to @racket['prime].} @item{Parentheses and sequences of decimal digits in immediate strings are left as-is, but any other immediate string is @@ -1147,24 +1193,24 @@ An alias for @scheme[centered] for backward compatibility.} @section[#:tag "index-entries"]{Index-Entry Descriptions} @defmodule[scribble/manual-struct]{The -@schememodname[scribble/manual-struct] library provides types used to -describe index entries created by @schememodname[scribble/manual] +@racketmodname[scribble/manual-struct] library provides types used to +describe index entries created by @racketmodname[scribble/manual] functions. These structure types are provided separate from -@schememodname[scribble/manual] so that -@schememodname[scribble/manual] need not be loaded when deserializing +@racketmodname[scribble/manual] so that +@racketmodname[scribble/manual] need not be loaded when deserializing cross-reference information that was generated by a previously rendered document.} @defstruct[module-path-index-desc ()]{ Indicates that the index entry corresponds to a module definition via -@scheme[defmodule] and company.} +@racket[defmodule] and company.} @defstruct[exported-index-desc ([name symbol?] [from-libs (listof module-path?)])]{ Indicates that the index entry corresponds to the definition of an -exported binding. The @scheme[name] field and @scheme[from-libs] list +exported binding. The @racket[name] field and @racket[from-libs] list correspond to the documented name of the binding and the primary modules that export the documented name (but this list is not exhaustive, because new modules can re-export the binding).} @@ -1172,44 +1218,44 @@ exhaustive, because new modules can re-export the binding).} @defstruct[(form-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -syntactic form via @scheme[defform] and company.} +syntactic form via @racket[defform] and company.} @defstruct[(procedure-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -procedure binding via @scheme[defproc] and company.} +procedure binding via @racket[defproc] and company.} @defstruct[(thing-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -binding via @scheme[defthing] and company.} +binding via @racket[defthing] and company.} @defstruct[(struct-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -structure type via @scheme[defstruct] and company.} +structure type via @racket[defstruct] and company.} @defstruct[(class-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -class via @scheme[defclass] and company.} +class via @racket[defclass] and company.} @defstruct[(interface-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of an -interface via @scheme[definterface] and company.} +interface via @racket[definterface] and company.} @defstruct[(mixin-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -mixin via @scheme[defmixin] and company.} +mixin via @racket[defmixin] and company.} @defstruct[(method-index-desc exported-index-desc) ([method-name symbol?] [class-tag tag?])]{ Indicates that the index entry corresponds to the definition of an -method via @scheme[defmethod] and company. The @scheme[_name] field -from @scheme[exported-index-desc] names the class or interface that -contains the method. The @scheme[method-name] field names the method. -The @scheme[class-tag] field provides a pointer to the start of the +method via @racket[defmethod] and company. The @racket[_name] field +from @racket[exported-index-desc] names the class or interface that +contains the method. The @racket[method-name] field names the method. +The @racket[class-tag] field provides a pointer to the start of the documentation for the method's class or interface.} diff --git a/collects/scribblings/scribble/plt.scrbl b/collects/scribblings/scribble/plt.scrbl index b44754f6..89b1a04a 100644 --- a/collects/scribblings/scribble/plt.scrbl +++ b/collects/scribblings/scribble/plt.scrbl @@ -3,8 +3,8 @@ @title[#:tag "plt-manuals" #:style 'toc]{Scribbling Documentation} -The @schememodname[scribble/manual] language and associated libraries -provide extensive support for documenting PLT Scheme libraries. The +The @racketmodname[scribble/manual] language and associated libraries +provide extensive support for documenting Racket libraries. The most significant aspect of support for documentation is the way that source-code bindings are connected to documentation sites through the module namespace---a connection that is facilitated by the fact that diff --git a/collects/scribblings/scribble/reader-internals.scrbl b/collects/scribblings/scribble/reader-internals.scrbl index 4086e29d..8ad09806 100644 --- a/collects/scribblings/scribble/reader-internals.scrbl +++ b/collects/scribblings/scribble/reader-internals.scrbl @@ -3,53 +3,53 @@ scribble/bnf scribble/eval "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label (only-in scribble/reader use-at-readtable))) @(define read-eval (make-base-eval)) -@(interaction-eval #:eval read-eval (require (for-syntax scheme/base))) +@(interaction-eval #:eval read-eval (require (for-syntax racket/base))) @title[#:tag "reader-internals"]{@"@" Reader Internals} @;-------------------------------------------------------------------- @section{Using the @"@" Reader} -You can use the reader via Scheme's @schemefont{#reader} form: +You can use the reader via Racket's @racketfont{#reader} form: -@schemeblock[ - @#,schemefont|{ +@racketblock[ + @#,racketfont|{ #reader scribble/reader @foo{This is free-form text!} }|] -or use the @scheme[at-exp] meta-language as described in +or use the @racket[at-exp] meta-language as described in @secref["at-exp-lang"]. Note that the Scribble reader reads @"@"-forms as S-expressions. This means that it is up to you to give meanings for these expressions in -the usual way: use Scheme functions, define your functions, or require -functions. For example, typing the above into @exec{mzscheme} is likely +the usual way: use Racket functions, define your functions, or require +functions. For example, typing the above into @exec{racket} is likely going to produce a ``reference to undefined identifier'' error, unless -@scheme[foo] is defined. You can use @scheme[string-append] instead, -or you can define @scheme[foo] as a function (with variable arity). +@racket[foo] is defined. You can use @racket[string-append] instead, +or you can define @racket[foo] as a function (with variable arity). A common use of the Scribble @"@"-reader is when using Scribble as a documentation system for producing manuals. In this case, the manual text is likely to start with -@schememod[scribble/doc] +@racketmod[scribble/doc] which installs the @"@" reader starting in ``text mode,'' wraps the -file content afterward into a Scheme module where many useful Scheme +file content afterward into a Racket module where many useful Racket and documentation related functions are available, and parses the body -into a document using @schememodname[scribble/decode]. See +into a document using @racketmodname[scribble/decode]. See @secref["docreader"] for more information. -Another way to use the reader is to use the @scheme[use-at-readtable] +Another way to use the reader is to use the @racket[use-at-readtable] function to switch the current readtable to a readtable that parses @"@"-forms. You can do this in a single command line: -@commandline{mzscheme -ile scribble/reader "(use-at-readtable)"} +@commandline{racket -ile scribble/reader "(use-at-readtable)"} @;-------------------------------------------------------------------- @section{Syntax Properties} @@ -57,12 +57,12 @@ function to switch the current readtable to a readtable that parses The Scribble reader attaches properties to syntax objects. These properties might be useful in some rare situations. -Forms that Scribble reads are marked with a @scheme['scribble] +Forms that Scribble reads are marked with a @racket['scribble] property, and a value of a list of three elements: the first is -@scheme['form], the second is the number of items that were read from +@racket['form], the second is the number of items that were read from the datum part, and the third is the number of items in the body part -(strings, sub-forms, and escapes). In both cases, a @scheme[0] means -an empty datum/body part, and @scheme[#f] means that the corresponding +(strings, sub-forms, and escapes). In both cases, a @racket[0] means +an empty datum/body part, and @racket[#f] means that the corresponding part was omitted. If the form has neither parts, the property is not attached to the result. This property can be used to give different meanings to expressions from the datum and the body parts, for @@ -102,10 +102,10 @@ example, implicitly quoted keywords: In addition, the Scribble parser uses syntax properties to mark syntax items that are not physically in the original source --- indentation -spaces and newlines. Both of these will have a @scheme['scribble] +spaces and newlines. Both of these will have a @racket['scribble] property; an indentation string of spaces will have -@scheme['indentation] as the value of the property, and a newline will -have a @scheme['(newline S)] value where @scheme[S] is the original +@racket['indentation] as the value of the property, and a newline will +have a @racket['(newline S)] value where @racket[S] is the original newline string including spaces that precede and follow it (which includes the indentation for the following item). This can be used to implement a verbatim environment: drop indentation strings, and use @@ -147,26 +147,26 @@ is an example of this. @;-------------------------------------------------------------------- @section[#:tag "at-exp-lang"]{Adding @"@"-expressions to a Language} -@defmodulelang[at-exp]{The @schememodname[at-exp] language installs +@defmodulelang[at-exp]{The @racketmodname[at-exp] language installs @"@"-reader support in the readtable, and then chains to the reader of another language that is specified immediately after -@schememodname[at-exp].} +@racketmodname[at-exp].} -For example, @scheme[@#,hash-lang[] at-exp scheme/base] adds @"@"-reader -support to @scheme[scheme/base], so that +For example, @racket[@#,hash-lang[] at-exp racket/base] adds @"@"-reader +support to @racket[racket/base], so that -@schememod[ -at-exp scheme/base +@racketmod[ +at-exp racket/base -(define (greet who) @#,elem{@tt["@"]@scheme[string-append]@schemeparenfont["{"]@schemevalfont{Hello, }@tt["@|"]@scheme[who]@tt["|"]@schemevalfont{.}@schemeparenfont["}"]}) +(define (greet who) @#,elem{@tt["@"]@racket[string-append]@racketparenfont["{"]@racketvalfont{Hello, }@tt["@|"]@racket[who]@tt["|"]@racketvalfont{.}@racketparenfont["}"]}) (greet "friend")] -reports @scheme["Hello, friend."]. +reports @racket["Hello, friend."]. @;-------------------------------------------------------------------- @section{Interface} -@defmodule[scribble/reader]{The @schememodname[scribble/reader] module +@defmodule[scribble/reader]{The @racketmodname[scribble/reader] module provides direct Scribble reader functionality for advanced needs.} @; The `with-scribble-read' trick below shadows `read' and @@ -193,7 +193,7 @@ for reading. @defproc[(read-syntax-inside [source-name any/c (object-name in)] [in input-port? (current-input-port)]) (or/c syntax? eof-object?)]{ -These @schemeid[-inside] variants parse as if starting inside a +These @racketid[-inside] variants parse as if starting inside a @litchar["@{"]...@litchar["}"], and they return a (syntactic) list. Useful for implementing languages that are textual by default (see @filepath{docreader.ss} for example). @@ -216,26 +216,26 @@ resulting reader in several ways: @itemize[ -@item{@scheme[readtable] --- a readtable to base the @"@"-readtable +@item{@racket[readtable] --- a readtable to base the @"@"-readtable on.} -@item{@scheme[command-char] --- the character used for @"@"-forms.} +@item{@racket[command-char] --- the character used for @"@"-forms.} -@item{@scheme[datum-readtable] --- determines the readtable used for - reading the datum part. A @scheme[#t] values uses the +@item{@racket[datum-readtable] --- determines the readtable used for + reading the datum part. A @racket[#t] values uses the @"@"-readtable, otherwise it can be a readtable, or a readtable-to-readtable function that will construct one from the @"@"-readtable. The idea is that you may want to have completely different uses for the datum part, for example, introducing a convenient @litchar{key=val} syntax for attributes.} -@item{@scheme[syntax-post-proc] --- function that is applied on +@item{@racket[syntax-post-proc] --- function that is applied on each resulting syntax value after it has been parsed (but before it is wrapped quoting punctuations). You can use this to further control uses of @"@"-forms, for example, making the command be the head of a list: - @schemeblock[ + @racketblock[ (use-at-readtable #:syntax-post-processor (lambda (stx) @@ -249,31 +249,31 @@ resulting reader in several ways: @defproc[(make-at-reader [#:syntax? syntax? #t] [#:inside? inside? #f] ...) procedure?]{ Constructs a variant of a @"@"-readtable. The arguments are the same -as in @scheme[make-at-readtable], with two more that determine the -kind of reader function that will be created: @scheme[syntax?] chooses -between a @scheme[read]- or @scheme[read-syntax]-like function, and -@scheme[inside?] chooses a plain reader or an @schemeid[-inside] +as in @racket[make-at-readtable], with two more that determine the +kind of reader function that will be created: @racket[syntax?] chooses +between a @racket[read]- or @racket[read-syntax]-like function, and +@racket[inside?] chooses a plain reader or an @racketid[-inside] variant. The resulting function has a different contract and action based on -these inputs. The expected inputs are as in @scheme[read] or -@scheme[read-syntax] depending on @scheme[syntax?]; the function will -read a single expression or, if @scheme[inside?] is true, the whole +these inputs. The expected inputs are as in @racket[read] or +@racket[read-syntax] depending on @racket[syntax?]; the function will +read a single expression or, if @racket[inside?] is true, the whole input; it will return a syntactic list of expressions rather than a single one in this case. -Note that @scheme[syntax?] defaults to @scheme[#t], as this is the +Note that @racket[syntax?] defaults to @racket[#t], as this is the more expected common case when you're dealing with concrete-syntax reading. -Note that if @scheme[syntax?] is true, the @scheme[read]-like function +Note that if @racket[syntax?] is true, the @racket[read]-like function is constructed by simply converting a syntax result back into a datum.} @defproc[(use-at-readtable ...) void?]{ -Passes all arguments to @scheme[make-at-readtable], and installs the -resulting readtable using @scheme[current-readtable]. It also enables -line counting for the current input-port via @scheme[port-count-lines!]. +Passes all arguments to @racket[make-at-readtable], and installs the +resulting readtable using @racket[current-readtable]. It also enables +line counting for the current input-port via @racket[port-count-lines!]. This is mostly useful for playing with the Scribble syntax on the REPL.} diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl index e04ca036..da1901ce 100644 --- a/collects/scribblings/scribble/reader.scrbl +++ b/collects/scribblings/scribble/reader.scrbl @@ -3,41 +3,41 @@ scribble/bnf scribble/eval "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label (only-in scribble/reader use-at-readtable))) @(define read-eval (make-base-eval)) -@(interaction-eval #:eval read-eval (require (for-syntax scheme/base))) +@(interaction-eval #:eval read-eval (require (for-syntax racket/base))) -@(define (at-exp-scheme) - @scheme[#, @hash-lang[] #, @schememodname[at-exp] #, @schemeidfont{scheme}]) +@(define (at-exp-racket) + @racket[#, @hash-lang[] #, @racketmodname[at-exp] #, @racketidfont{racket}]) @title[#:tag "reader"]{@"@" Syntax} The Scribble @"@" notation is designed to be a convenient facility for -free-form text in Scheme code, where ``@"@"'' was chosen as one of the -least-used characters in existing Scheme code. An @"@"-expression is +free-form text in Racket code, where ``@"@"'' was chosen as one of the +least-used characters in existing Racket code. An @"@"-expression is simply an S-expression in disguise. Typically, @"@" notation is enabled through -@schememodname[scribble/base] or similar languages, but you can also +@racketmodname[scribble/base] or similar languages, but you can also add @"@" notation to an S-expression-based language using the -@schememodname[at-exp] meta-language. For example, +@racketmodname[at-exp] meta-language. For example, @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket (define v '@op{str}) }| is equivalent to -@schememod[ -scheme +@racketmod[ +racket (define v '(op "str")) ] -Using @at-exp-scheme[] is probably the easiest way to try the examples +Using @at-exp-racket[] is probably the easiest way to try the examples in this chapter. @;-------------------------------------------------------------------- @@ -46,7 +46,7 @@ in this chapter. To review @secref["how-to:reader"], the concrete syntax of @"@"-forms is roughly -@schemeblock[ +@racketblock[ @#,BNF-seq[@litchar["@"] @nonterm{cmd} @litchar{[} @kleenestar{@nonterm{datum}} @litchar{]} @@ -57,15 +57,15 @@ where all three parts after @litchar["@"] are optional, but at least one should be present. (Spaces are not allowed between the three parts.) Roughly, a form matching the above grammar is read as -@schemeblock[ +@racketblock[ (@#,nonterm{cmd} @#,kleenestar{@nonterm{datum}} @#,kleenestar{@nonterm{parsed-body}}) ] where @nonterm{parsed-body} is the translation of each @nonterm{text-body} in the input. Thus, the initial @nonterm{cmd} -determines the Scheme code that the input is translated into. The -common case is when @nonterm{cmd} is a Scheme identifier, which reads -as a plain Scheme form, with datum arguments and/or string arguments. +determines the Racket code that the input is translated into. The +common case is when @nonterm{cmd} is a Racket identifier, which reads +as a plain Racket form, with datum arguments and/or string arguments. Here is one example: @@ -73,38 +73,38 @@ Here is one example: @foo{blah blah blah} }===| -The example shows how an input syntax is read as Scheme syntax, not +The example shows how an input syntax is read as Racket syntax, not what it evaluates to. If you want to see the translation of an example into S-expression form, add a quote in front of it in a -@at-exp-scheme[] module. For example, running +@at-exp-racket[] module. For example, running @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket '@foo{blah blah blah} }| -in DrScheme prints the output +in DrRacket prints the output -@nested[#:style 'inset]{@schemeresult[(foo "blah blah blah")]} +@nested[#:style 'inset]{@racketresult[(foo "blah blah blah")]} while omitting the quote @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket @foo{blah blah blah} }| -triggers a syntax error because @scheme[foo] is not bound, and +triggers a syntax error because @racket[foo] is not bound, and @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket (define (foo str) (printf "He wrote ~s.\n" str)) @foo{blah blah blah} }| prints the output -@nested[#:style 'inset]{@schemeoutput{He wrote "blah blah blah".}} +@nested[#:style 'inset]{@racketoutput{He wrote "blah blah blah".}} Here are more examples of @"@"-forms: @@ -122,13 +122,13 @@ Here are more examples of @"@"-forms: }===| As seen in the last example, multiple lines and the newlines that -separate them are parsed to multiple Scheme strings. More generally, +separate them are parsed to multiple Racket strings. More generally, a @nonterm{text-body} is made of text, newlines, and nested @"@"-forms, where the syntax for @"@"-forms is the same whether it's -in a @nonterm{text-body} context as in a Scheme context. A +in a @nonterm{text-body} context as in a Racket context. A @nonterm{text-body} that isn't an @"@"-form is converted to a string expression for its @nonterm{parsed-body}; newlines and following -indentations are converted to @scheme["\n"] and all-space string +indentations are converted to @racket["\n"] and all-space string expressions. @scribble-examples|==={ @@ -142,8 +142,8 @@ expressions. The command part of an @"@"-form is optional as well. In that case, the @"@" forms is read as a list, which usually counts as a function -application, but it also useful when quoted with the usual Scheme -@scheme[quote]: +application, but it also useful when quoted with the usual Racket +@racket[quote]: @scribble-examples|==={ @{blah blah} @@ -155,8 +155,8 @@ application, but it also useful when quoted with the usual Scheme Finally, we can also drop the datum and text parts, which leaves us with only the command---which is read as is, not within a parenthesized -form. This is not useful when reading Scheme code, but it can be used -inside a text block to escape a Scheme identifier. A vertical bar +form. This is not useful when reading Racket code, but it can be used +inside a text block to escape a Racket identifier. A vertical bar (@litchar{|}) can be used to delimit the escaped identifier when needed. @@ -167,7 +167,7 @@ needed. @{blah @|foo|: blah} }===| -Actually, the command part can be any Scheme expression (that does not +Actually, the command part can be any Racket expression (that does not start with @litchar["["], @litchar["{"], or @litchar["|"]), which is particularly useful with such escapes since they can be used with any expression. @@ -177,7 +177,7 @@ expression. @foo{A @"string" escape} }===| -Note that an escaped Scheme string is merged with the surrounding text +Note that an escaped Racket string is merged with the surrounding text as a special case. This is useful if you want to use the special characters in your string, but escaping braces are not necessary if they are balanced. @@ -214,10 +214,10 @@ and @litchar{<>}s.) With this extension, Scribble syntax can be used as a @foo|<<{bar}@|{baz}>>| }===| -On the flip side of this is, how can an @"@" sign be used in Scheme -code? This is almost never an issue, because Scheme strings and +On the flip side of this is, how can an @"@" sign be used in Racket +code? This is almost never an issue, because Racket strings and characters are still read the same, and @litchar["@"] is set as a -non-terminating reader macro so it can be used in Scheme identifiers +non-terminating reader macro so it can be used in Racket identifiers anywhere except in the first character of an identifier. When @litchar["@"] must appear as the first character of an identifier, you must quote the identifier just like other non-standard characters in @@ -229,7 +229,7 @@ normal S-expression syntax: with a backslash or with vertical bars. }===| Note that spaces are not allowed before a @litchar{[} or a -@litchar["{"], or they will be part of the following text (or Scheme +@litchar["{"], or they will be part of the following text (or Racket code). (More on using braces in body texts below.) @scribble-examples|==={ @@ -238,11 +238,11 @@ code). (More on using braces in body texts below.) Finally, remember that the Scribble is just an alternate for S-expressions. Identifiers still get their meaning, as in any -Scheme code, through the lexical context in which they appear. -Specifically, when the above @"@"-form appears in a Scheme expression +Racket code, through the lexical context in which they appear. +Specifically, when the above @"@"-form appears in a Racket expression context, the lexical environment must provide bindings for -@scheme[foo] as a procedure or a macro; it can be defined, required, -or bound locally (with @scheme[let], for example). +@racket[foo] as a procedure or a macro; it can be defined, required, +or bound locally (with @racket[let], for example). @; FIXME: unfortunate code duplication @interaction[ @@ -266,8 +266,8 @@ or bound locally (with @scheme[let], for example). @;-------------------------------------------------------------------- @section{The Command Part} -Besides being a Scheme identifier, the @nonterm{cmd} part of an -@"@"-form can have Scheme punctuation prefixes, which will end up +Besides being a Racket identifier, the @nonterm{cmd} part of an +@"@"-form can have Racket punctuation prefixes, which will end up wrapping the @italic{whole} expression. @scribble-examples|==={ @@ -275,14 +275,14 @@ wrapping the @italic{whole} expression. @#`#'#,@foo{blah} }===| -When writing Scheme code, this means that @litchar|{@`',@foo{blah}}| +When writing Racket code, this means that @litchar|{@`',@foo{blah}}| is exactly the same as @litchar|{`@',@foo{blah}}| and @litchar|{`',@@foo{blah}}|, but unlike the latter two, the first construct can appear in body texts with the same meaning, whereas the other two would not work (see below). After the optional punctuation prefix, the @nonterm{cmd} itself is not -limited to identifiers; it can be @italic{any} Scheme expression. +limited to identifiers; it can be @italic{any} Racket expression. @scribble-examples|==={ @(lambda (x) x){blah} @@ -305,7 +305,7 @@ the @litchar["@"] and the @litchar{;}), then the construct is a comment. There are two comment forms, one for arbitrary-text and possibly nested comments, and another one for line comments: -@schemeblock[ +@racketblock[ @#,BNF-seq[@litchar["@;{"] @kleenestar{@nonterm{any}} @litchar["}"]] @#,BNF-seq[@litchar["@;"] @kleenestar{@nonterm{anything-else-without-newline}}] @@ -323,7 +323,7 @@ following spaces (or tabs) are part of the comment (similar to blah} }===| -Tip: if you're editing in a Scheme-aware editor (like DrScheme or +Tip: if you're editing in a Racket-aware editor (like DrRacket or Emacs), it is useful to comment out blocks like this: @verbatim[#:indent 2]|==={ @@ -337,7 +337,7 @@ parenthesis. If only the @nonterm{cmd} part of an @"@"-form is specified, then the result is the command part only, without an extra set of parenthesis. -This makes it suitable for Scheme escapes in body texts. (More on this +This makes it suitable for Racket escapes in body texts. (More on this below, in the description of the body part.) @scribble-examples|==={ @@ -356,7 +356,7 @@ Finally, note that there are currently no special rules for using @;-------------------------------------------------------------------- @section{The Datum Part} -The datum part can contains arbitrary Scheme expressions, which +The datum part can contains arbitrary Racket expressions, which are simply stacked before the body text arguments: @scribble-examples|==={ @@ -383,7 +383,7 @@ for the same purpose. @foo{} }===| -The most common use of the datum part is for Scheme forms that expect +The most common use of the datum part is for Racket forms that expect keyword-value arguments that precede the body of text arguments. @scribble-examples|==={ @@ -408,7 +408,7 @@ are valid text. As described above, the text turns to a sequence of string arguments for the resulting form. Spaces at the beginning and end of lines are -discarded, and newlines turn to individual @scheme["\n"] strings +discarded, and newlines turn to individual @racket["\n"] strings (i.e., they are not merged with other body parts); see also the information about newlines and indentation below. Spaces are @italic{not} discarded if they appear after the open @litchar["{"] @@ -422,7 +422,7 @@ single-line body. @foo[1]{ bar } }===| -If @litchar["@"] appears in a body, then it is interpreted as Scheme +If @litchar["@"] appears in a body, then it is interpreted as Racket code, which means that the @"@"-reader is applied recursively, and the resulting syntax appears as part of the S-expression, among other string contents. @@ -433,8 +433,8 @@ string contents. If the nested @"@" construct has only a command---no body or datum parts---it will not appear in a subform. Given that the command part -can be any Scheme expression, this makes @"@" a general escape to -arbitrary Scheme code. +can be any Racket expression, this makes @"@" a general escape to +arbitrary Racket code. @scribble-examples|==={ @foo{a @bar c} @@ -497,19 +497,19 @@ in reverse order with paren-like characters (@litchar{(}, @foo|!!{X |!!@b{Y}...}!!| }===| -Finally, remember that you can use an expression escape with a Scheme +Finally, remember that you can use an expression escape with a Racket string for confusing situations. This works well when you only need to quote short pieces, and the above works well when you have larger multi-line body texts. @;-------------------------------------------------------------------- -@subsection{Scheme Expression Escapes} +@subsection{Racket Expression Escapes} -In some cases, you may want to use a Scheme identifier (or a number or +In some cases, you may want to use a Racket identifier (or a number or a boolean etc.) in a position that touches the following text; in -these situations you should surround the escaped Scheme expression by +these situations you should surround the escaped Racket expression by a pair of @litchar{|} characters. The text inside the bars is -parsed as a Scheme expression. +parsed as a Racket expression. @scribble-examples|==={ @foo{foo@bar.} @@ -518,7 +518,7 @@ parsed as a Scheme expression. @foo{foo@|3|.} }===| -This form is a generic Scheme expression escape, there is no body text +This form is a generic Racket expression escape, there is no body text or datum part when you use this form. @scribble-examples|==={ @@ -552,8 +552,8 @@ you want to control the sub expressions in the form. }===| Note that @litchar["@|{...}|"] can be parsed as either an escape expression or -as the Scheme command part of a @"@"-form. The latter is used in this case -(since there is little point in Scheme code that uses braces. +as the Racket command part of a @"@"-form. The latter is used in this case +(since there is little point in Racket code that uses braces. @scribble-examples|==={ @|{blah}| @@ -603,7 +603,7 @@ for spaces between a @litchar["{"] and text, or between text and a A single newline that follows an open brace or precedes a closing brace is discarded, unless there are only newlines in the body; other -newlines are read as a @scheme["\n"] string +newlines are read as a @racket["\n"] string @scribble-examples|==={ @foo{bar @@ -631,7 +631,7 @@ newlines are read as a @scheme["\n"] string }===| In the parsed S-expression syntax, a single newline string is used for -all newlines; you can use @scheme[eq?] to identify this line. This +all newlines; you can use @racket[eq?] to identify this line. This can be used to identify newlines in the original @nonterm{text-body}. @; FIXME: unfortunate code duplication (again): @@ -641,7 +641,7 @@ can be used to identify newlines in the original @nonterm{text-body}. @#,tt[" }"])]) (for-each (lambda (x) (display (if (eq? x nl) "\n... " x))) @#,tt["@`{foo"] - @#,elem[@tt[" @"] @scheme[,@(list "bar" "\n" "baz")]] + @#,elem[@tt[" @"] @racket[,@(list "bar" "\n" "baz")]] @#,tt[" blah}}"]) (newline)) (let ([nl (car @'{ @@ -658,7 +658,7 @@ S-expressions, but the column of each line is noticed, and all-space indentation strings are added so the result has the same indentation. A indentation string is added to each line according to its distance from the leftmost syntax object (except for empty lines). (Note: if -you try these examples on a mzscheme REPL, you should be aware that +you try these examples on a Racket REPL, you should be aware that the reader does not know about the ``@litchar{> }'' prompt.) @scribble-examples|==={ @@ -722,11 +722,11 @@ example, in }===| a formatter will need to apply the 2-space indentation to the -rendering of the @scheme[bold] body. +rendering of the @racket[bold] body. Note that to get a first-line text to be counted as a leftmost line, line and column accounting should be on for the input port -(@scheme[use-at-readtable] turns them on for the current input port). +(@racket[use-at-readtable] turns them on for the current input port). Without this, @litchar/lines|==={ @@ -745,7 +745,7 @@ source accounting is not on, but }===| will (due to the last line). Pay attention to this, as it can be a -problem with Scheme code, for example: +problem with Racket code, for example: @litchar/lines|==={ @code{(define (foo x) diff --git a/collects/scribblings/scribble/renderer.scrbl b/collects/scribblings/scribble/renderer.scrbl index ccd33326..50f69a83 100644 --- a/collects/scribblings/scribble/renderer.scrbl +++ b/collects/scribblings/scribble/renderer.scrbl @@ -15,7 +15,7 @@ @title[#:tag "renderer"]{Renderer} A renderer is an object that provides two main methods: -@scheme[collect] and @scheme[render]. The first method is called to +@racket[collect] and @racket[render]. The first method is called to collect global information about the document, including information that spans multiple documents rendered together; the collection pass tends to be format-independent, and it usually implemented completely @@ -25,11 +25,11 @@ which is naturally specific to a particular format. @section{Base Renderer} @defmodule[scribble/base-render]{The -@schememodname[scribble/base-render] module provides @scheme[render%], +@racketmodname[scribble/base-render] module provides @racket[render%], which implements the core of a renderer. This rendering class must be -refined with a mixin from @schememodname[scribble/text-render], -@schememodname[scribble/html-render], or -@schememodname[scribble/latex-render].} +refined with a mixin from @racketmodname[scribble/text-render], +@racketmodname[scribble/html-render], or +@racketmodname[scribble/latex-render].} The mixin structure is meant to support document-specific extensions to the renderers. For example, the @exec{scribble} command-line tool @@ -38,7 +38,7 @@ might, in the future, extract rendering mixins from a document module See the @filepath{base-render.ss} source for more information about the methods of the renderer. Documents built with higher layers, such -as @schememodname[scribble/manual], generally do not call the render +as @racketmodname[scribble/manual], generally do not call the render object's methods directly. @defclass[render% object% ()]{ @@ -49,15 +49,15 @@ Represents a renderer. [refer-to-existing-files any/c #f] [root-path (or/c path-string? false/c) #f])]{ -Creates a renderer whose output will go to @scheme[dest-dir]. For -example, @scheme[dest-dir] could name the directory containing the +Creates a renderer whose output will go to @racket[dest-dir]. For +example, @racket[dest-dir] could name the directory containing the output Latex file, the HTML file for a single-file output, or the output sub-directory for multi-file HTML output. -If @scheme[root-path] is not @scheme[#f], it is normally the same as -@scheme[dest-dir] or a parent of @scheme[dest-dir]. It causes +If @racket[root-path] is not @racket[#f], it is normally the same as +@racket[dest-dir] or a parent of @racket[dest-dir]. It causes cross-reference information to record destination files relative to -@scheme[root-path]; when cross-reference information is serialized, it +@racket[root-path]; when cross-reference information is serialized, it can be deserialized via @method[render% deserialize-info] with a different root path (indicating that the destination files have moved).} @@ -68,7 +68,7 @@ moved).} collect-info?]{ Performs the @techlink{collect pass}. See @method[render% render] for -information on the @scheme[dests] argument.} +information on the @racket[dests] argument.} @defmethod[(resolve [srcs (listof part?)] [dests (listof path-string?)] @@ -76,7 +76,7 @@ information on the @scheme[dests] argument.} resolve-info?]{ Performs the @techlink{resolve pass}. See @method[render% render] for -information on the @scheme[dests] argument.} +information on the @racket[dests] argument.} @defmethod[(render [srcs (listof part?)] [dests (listof path-string?)] @@ -85,29 +85,29 @@ information on the @scheme[dests] argument.} Produces the final output. -The @scheme[dests] provide names of files for Latex or single-file +The @racket[dests] provide names of files for Latex or single-file HTML output, or names of sub-directories for multi-file HTML output. -If the @scheme[dests] are relative, they're relative to the current +If the @racket[dests] are relative, they're relative to the current directory; normally, they should indicates a path within the -@scheme[_dest-dir] supplied on initialization of the @scheme[render%] +@racket[_dest-dir] supplied on initialization of the @racket[render%] object.} @defmethod[(serialize-info [ri resolve-info?]) any/c]{ -Serializes the collected info in @scheme[ri].} +Serializes the collected info in @racket[ri].} @defmethod[(deserialize-info [v any/c] [ci collect-info?] [#:root root-path (or/c path-string? false/c) #f]) void?]{ -Adds the deserialized form of @scheme[v] to @scheme[ci]. +Adds the deserialized form of @racket[v] to @racket[ci]. -If @scheme[root-path] is not @scheme[#f], then file paths that are -recorded in @scheme[ci] as relative to an instantiation-supplied -@scheme[root-path] are deserialized as relative instead to the given -@scheme[root-path].} +If @racket[root-path] is not @racket[#f], then file paths that are +recorded in @racket[ci] as relative to an instantiation-supplied +@racket[root-path] are deserialized as relative instead to the given +@racket[root-path].} } @@ -119,7 +119,7 @@ recorded in @scheme[ci] as relative to an instantiation-supplied @defmixin[render-mixin (render%) ()]{ -Specializes a @scheme[render%] class for generating plain text.}} +Specializes a @racket[render%] class for generating plain text.}} @; ---------------------------------------- @@ -129,21 +129,21 @@ Specializes a @scheme[render%] class for generating plain text.}} @defmixin[render-mixin (render%) ()]{ -Specializes a @scheme[render%] class for generating HTML output. +Specializes a @racket[render%] class for generating HTML output. @defmethod[(set-external-tag-path [url string?]) void?]{ Configures the renderer to redirect links to external via -@scheme[url], adding a @scheme[tag] query element to the end of the -URL that contains the Base64-encoded, @scheme[print]ed, serialized -original tag (in the sense of @scheme[link-element]) for the link.} +@racket[url], adding a @racket[tag] query element to the end of the +URL that contains the Base64-encoded, @racket[print]ed, serialized +original tag (in the sense of @racket[link-element]) for the link.} } @defmixin[render-multi-mixin (render%) ()]{ Further specializes a rendering class produced by -@scheme[render-mixin] for generating multiple HTML +@racket[render-mixin] for generating multiple HTML files.} } @@ -156,4 +156,4 @@ files.} @defmixin[render-mixin (render%) ()]{ -Specializes a @scheme[render%] class for generating Latex input.}} +Specializes a @racket[render%] class for generating Latex input.}} diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl index 9285fecf..7925e321 100644 --- a/collects/scribblings/scribble/scheme.scrbl +++ b/collects/scribblings/scribble/scheme.scrbl @@ -1,45 +1,47 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-label scribble/scheme)) + (for-label scribble/racket)) -@title[#:tag "scheme"]{Scheme} +@title[#:tag "scheme"]{Racket} -@defmodule[scribble/scheme]{The @scheme[scribble/scheme] library -provides utilities for typesetting Scheme code. The -@scheme[scribble/manual] forms provide a higher-level interface.} +@defmodule*[(scribble/racket scribble/scheme)]{The +@racket[scribble/racket] library (or @racketmodname[scribble/scheme] +for backward compatibility) provides utilities for typesetting Racket +code. The @racket[scribble/manual] forms provide a higher-level +interface.} @defform*[[(define-code id typeset-expr) (define-code id typeset-expr uncode-id) (define-code id typeset-expr uncode-id d->s-expr) (define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)]]{ -Binds @scheme[id] to a form similar to @scheme[scheme] or -@scheme[schemeblock] for typesetting code. The form generated by -@scheme[define-code] handles source-location information, escapes via -@scheme[unquote], preservation of binding and property information, +Binds @racket[id] to a form similar to @racket[racket] or +@racket[racketblock] for typesetting code. The form generated by +@racket[define-code] handles source-location information, escapes via +@racket[unquote], preservation of binding and property information, and @tech{element transformers}. -The supplied @scheme[typeset-expr] expression should produce a +The supplied @racket[typeset-expr] expression should produce a procedure that performs the actual typesetting. This expression is -normally @scheme[to-element] or @scheme[to-paragraph]. The argument -supplied to @scheme[typeset-expr] is normally a syntax object, but -more generally it is the result of applying @scheme[d->s-expr]. +normally @racket[to-element] or @racket[to-paragraph]. The argument +supplied to @racket[typeset-expr] is normally a syntax object, but +more generally it is the result of applying @racket[d->s-expr]. -The optional @scheme[uncode-id] specifies the escape from literal code -to be recognized by @scheme[id]. The default is @scheme[unsyntax]. +The optional @racket[uncode-id] specifies the escape from literal code +to be recognized by @racket[id]. The default is @racket[unsyntax]. -The optional @scheme[d->s-expr] should produce a procedure that -accepts three arguments suitable for @scheme[datum->syntax]: a syntax -object or @scheme[#f], an arbitrary value, and a vector for a source +The optional @racket[d->s-expr] should produce a procedure that +accepts three arguments suitable for @racket[datum->syntax]: a syntax +object or @racket[#f], an arbitrary value, and a vector for a source location. The result should record as much or as little of the -argument information as needed by @scheme[typeset-expr] to typeset the -code. Normally, @scheme[d->s-expr] is @scheme[datum->syntax]. +argument information as needed by @racket[typeset-expr] to typeset the +code. Normally, @racket[d->s-expr] is @racket[datum->syntax]. -The @scheme[stx-prop-expr] should produce a procedure for recording a -@scheme['paren-shape] property when the source expression uses with -@scheme[id] has such a property. The default is -@scheme[syntax-property].} +The @racket[stx-prop-expr] should produce a procedure for recording a +@racket['paren-shape] property when the source expression uses with +@racket[id] has such a property. The default is +@racket[syntax-property].} @defproc[(to-paragraph [v any/c] [#:qq? qq? any/c #f]) block?]{ @@ -47,25 +49,25 @@ Typesets an S-expression that is represented by a syntax object, where source-location information in the syntax object controls the generated layout. -Identifiers that have @scheme[for-label] bindings are typeset and +Identifiers that have @racket[for-label] bindings are typeset and hyperlinked based on definitions declared elsewhere (via -@scheme[defproc], @scheme[defform], etc.). The identifiers -@schemeidfont{code:line}, @schemeidfont{code:comment}, -@schemeidfont{code:blank}, @schemeidfont{code:hilite}, and -@schemeidfont{code:quote} are handled as in @scheme[schemeblock], as +@racket[defproc], @racket[defform], etc.). The identifiers +@racketidfont{code:line}, @racketidfont{code:comment}, +@racketidfont{code:blank}, @racketidfont{code:hilite}, and +@racketidfont{code:quote} are handled as in @racket[racketblock], as are identifiers that start with @litchar{_}. -In addition, the given @scheme[v] can contain @scheme[var-id], -@scheme[shaped-parens], @scheme[just-context], or -@scheme[literal-syntax] structures to be typeset specially (see each -structure type for details), or it can contain @scheme[element] +In addition, the given @racket[v] can contain @racket[var-id], +@racket[shaped-parens], @racket[just-context], or +@racket[literal-syntax] structures to be typeset specially (see each +structure type for details), or it can contain @racket[element] structures that are used directly in the output. -If @scheme[qq?] is true, then @scheme[v] is rendered ``quasiquote'' -style, much like @scheme[print] with the @scheme[print-as-quasiquote] -parameter set to @scheme[#t]. In that case, @scheme[for-label] +If @racket[qq?] is true, then @racket[v] is rendered ``quasiquote'' +style, much like @racket[print] with the @racket[print-as-quasiquote] +parameter set to @racket[#t]. In that case, @racket[for-label] bindings on identifiers are ignored, since the identifiers are all -quoted in the output. Typically, @scheme[qq?] is set to true for +quoted in the output. Typically, @racket[qq?] is set to true for printing result values.} @@ -73,93 +75,93 @@ printing result values.} [v any/c]) block?]{ -Like @scheme[to-paragraph], but @scheme[prefix1] is prefixed onto the -first line, @scheme[prefix] is prefix to any subsequent line, and -@scheme[suffix] is added to the end. The @scheme[prefix1], -@scheme[prefix], and @scheme[suffix] arguments are used as -@tech{content}, except that if @scheme[suffix] is a list of elements, +Like @racket[to-paragraph], but @racket[prefix1] is prefixed onto the +first line, @racket[prefix] is prefix to any subsequent line, and +@racket[suffix] is added to the end. The @racket[prefix1], +@racket[prefix], and @racket[suffix] arguments are used as +@tech{content}, except that if @racket[suffix] is a list of elements, it is added to the end on its own line.} @defproc[(to-element [v any/c] [#:qq? qq? any/c #f]) element?]{ -Like @scheme[to-paragraph], except that source-location information is +Like @racket[to-paragraph], except that source-location information is mostly ignored, since the result is meant to be inlined into a paragraph.} @defproc[(to-element/no-color [v any/c] [#:qq? qq? any/c #f]) element?]{ -Like @scheme[to-element], but @scheme[for-syntax] bindings are +Like @racket[to-element], but @racket[for-syntax] bindings are ignored, and the generated text is uncolored. This variant is typically used to typeset results.} @defstruct[var-id ([sym (or/c symbol? identifier?)])]{ -When @scheme[to-paragraph] and variants encounter a @scheme[var-id] -structure, it is typeset as @scheme[sym] in the variable font, like -@scheme[schemevarfont]---unless the @scheme[var-id] appears under -quote or quasiquote, in which case @scheme[sym] is typeset as a symbol.} +When @racket[to-paragraph] and variants encounter a @racket[var-id] +structure, it is typeset as @racket[sym] in the variable font, like +@racket[racketvarfont]---unless the @racket[var-id] appears under +quote or quasiquote, in which case @racket[sym] is typeset as a symbol.} @defstruct[shaped-parens ([val any/c] [shape char?])]{ -When @scheme[to-paragraph] and variants encounter a -@scheme[shaped-parens] structure, it is typeset like a syntax object -that has a @scheme['paren-shape] property with value @scheme[shape].} +When @racket[to-paragraph] and variants encounter a +@racket[shaped-parens] structure, it is typeset like a syntax object +that has a @racket['paren-shape] property with value @racket[shape].} @defstruct[just-context ([val any/c] [context syntax?])]{ -When @scheme[to-paragraph] and variants encounter a -@scheme[just-context] structure, it is typeset using the -source-location information of @scheme[val] just the lexical context -of @scheme[ctx].} +When @racket[to-paragraph] and variants encounter a +@racket[just-context] structure, it is typeset using the +source-location information of @racket[val] just the lexical context +of @racket[ctx].} @defstruct[literal-syntax ([stx any/c])]{ -When @scheme[to-paragraph] and variants encounter a -@scheme[literal-syntax] structure, it is typeset as the string form of -@scheme[stx]. This can be used to typeset a syntax-object value in the +When @racket[to-paragraph] and variants encounter a +@racket[literal-syntax] structure, it is typeset as the string form of +@racket[stx]. This can be used to typeset a syntax-object value in the way that the default printer would represent the value.} @defproc[(element-id-transformer? [v any/c]) boolean?]{ -Provided @scheme[for-syntax]; returns @scheme[#t] if @scheme[v] is an +Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an @tech{element transformer} created by -@scheme[make-element-id-transformer], @scheme[#f] otherwise.} +@racket[make-element-id-transformer], @racket[#f] otherwise.} @defproc[(make-element-id-transformer [proc (syntax? . -> . syntax?)]) element-id-transformer?]{ -Provided @scheme[for-syntax]; creates an @deftech{element +Provided @racket[for-syntax]; creates an @deftech{element transformer}. When an identifier has a transformer binding to an @tech{element transformer}, then forms generated by -@scheme[define-code] (including @scheme[scheme] and -@scheme[schemeblock]) typeset the identifier by applying the -@scheme[proc] to the identifier. The result must be an expression -whose value, typically an @scheme[element], is passed on to functions -like @scheme[to-paragraph] .} +@racket[define-code] (including @racket[racket] and +@racket[racketblock]) typeset the identifier by applying the +@racket[proc] to the identifier. The result must be an expression +whose value, typically an @racket[element], is passed on to functions +like @racket[to-paragraph] .} @defproc[(variable-id? [v any/c]) boolean?]{ -Provided @scheme[for-syntax]; returns @scheme[#t] if @scheme[v] is an -@tech{element transformer} created by @scheme[make-variable-id], -@scheme[#f] otherwise.} +Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an +@tech{element transformer} created by @racket[make-variable-id], +@racket[#f] otherwise.} @defproc[(make-variable-id [sym (or/c symbol? identifier?)]) variable-id?]{ -Provided @scheme[for-syntax]; like @scheme[make-element-id-transformer] for -a transformer that produces @scheme[sym] typeset as a variable (like -@scheme[schemevarfont])---unless it appears under quote or quasiquote, -in which case @scheme[sym] is typeset as a symbol.} +Provided @racket[for-syntax]; like @racket[make-element-id-transformer] for +a transformer that produces @racket[sym] typeset as a variable (like +@racket[racketvarfont])---unless it appears under quote or quasiquote, +in which case @racket[sym] is typeset as a symbol.} @deftogether[( @defthing[output-color style?] @@ -185,4 +187,4 @@ in which case @scheme[sym] is typeset as a symbol.} @defthing[highlighted-color style?] )]{ -Styles that are used for coloring Scheme programs, results, and I/O.} +Styles that are used for coloring Racket programs, results, and I/O.} diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl index 79e74e75..2527a382 100644 --- a/collects/scribblings/scribble/scribble.scrbl +++ b/collects/scribblings/scribble/scribble.scrbl @@ -15,7 +15,7 @@ programmatically. This document itself is written using Scribble. At the time that it was written, its source was available at -@(let ([url "http://svn.plt-scheme.org/plt/trunk/collects/scribblings/scribble/"]) +@(let ([url "http://git.racket-lang.org/plt/tree/HEAD:/collects/scribblings/scribble"]) (link url url)) starting with the @filepath{scribble.scrbl} file. diff --git a/collects/scribblings/scribble/sigplan.scrbl b/collects/scribblings/scribble/sigplan.scrbl index d9fe6c90..49f2a450 100644 --- a/collects/scribblings/scribble/sigplan.scrbl +++ b/collects/scribblings/scribble/sigplan.scrbl @@ -4,16 +4,16 @@ @title{SIGPLAN Paper Format} -@defmodulelang[scribble/sigplan]{The @schememodname[scribble/sigplan] -language is like @schememodname[scribble/manual], but configured with +@defmodulelang[scribble/sigplan]{The @racketmodname[scribble/sigplan] +language is like @racketmodname[scribble/manual], but configured with Latex style defaults to use the @filepath{sigplanconf.cls} class file that is included with Scribble.} @defidform[preprint]{ -Enables the @tt{preprint} option. Use @scheme[preprint] only on the +Enables the @tt{preprint} option. Use @racket[preprint] only on the same line as @hash-lang[], with only whitespace between -@schememodname[scribble/sigplan] and @scheme[preprint]: +@racketmodname[scribble/sigplan] and @racket[preprint]: @verbatim[#:indent 2]|{ #lang scribble/sigplan @preprint @@ -21,15 +21,15 @@ same line as @hash-lang[], with only whitespace between @defidform[10pt]{ -Enables the @tt{10pt} option. Use @scheme[10pt] only on the +Enables the @tt{10pt} option. Use @racket[10pt] only on the same line as @hash-lang[], with only whitespace between -@schememodname[scribble/sigplan] and @scheme[10pt]: +@racketmodname[scribble/sigplan] and @racket[10pt]: @verbatim[#:indent 2]|{ #lang scribble/sigplan @10pt }| -The @scheme[10pt] and @scheme[preprint] options can be +The @racket[10pt] and @racket[preprint] options can be used together and may appear in any order. } @@ -40,7 +40,7 @@ Generates a @tech{nested flow} for a paper abstract.} @defform[(include-abstract module-path)]{ -Similar to @scheme[include-section], but incorporates the document in the +Similar to @racket[include-section], but incorporates the document in the specified module as an abstract. The document must have no title or sub-parts.} @@ -49,7 +49,7 @@ sub-parts.} [email pre-content?]) block?]{ -A replacement for @scheme[author] that associates an affiliation and +A replacement for @racket[author] that associates an affiliation and e-mail address with the author name.} @deftogether[( @@ -71,4 +71,4 @@ Declares information that is collected into the copyright region of the paper.} )]{ Typesets category, term, and keyword information for the paper, which -is normally placed immediately after an @scheme[abstract] form.} +is normally placed immediately after an @racket[abstract] form.} diff --git a/collects/scribblings/scribble/srcdoc.scrbl b/collects/scribblings/scribble/srcdoc.scrbl index 4cccf754..32f1bdff 100644 --- a/collects/scribblings/scribble/srcdoc.scrbl +++ b/collects/scribblings/scribble/srcdoc.scrbl @@ -3,25 +3,25 @@ "utils.ss" (for-label scribble/srcdoc scribble/extract - scheme/contract)) + racket/contract)) @title[#:tag "srcdoc"]{In-Source Documentation} -The @schememodname[scribble/srcdoc] and -@schememodname[scribble/extract] libraries support writing +The @racketmodname[scribble/srcdoc] and +@racketmodname[scribble/extract] libraries support writing documentation withing the documentation code along with an export contract, similar to using @as-index{JavaDoc}. With this approach, a single contract specification is used both for the run-time contract and the documentation of an exported binding. -The @schememodname[scribble/srcdoc] library provides forms for +The @racketmodname[scribble/srcdoc] library provides forms for exporting a binding with associated documentation. The -@scheme[scribble/extract] library is used to pull -@scheme[scribble/srcdoc]-based documentation into a Scribble document +@racket[scribble/extract] library is used to pull +@racket[scribble/srcdoc]-based documentation into a Scribble document (perhaps for multiple libraries). Although documentation is written with a library's implementation when -using @schememodname[scribble/srcdoc], the documentation creates no +using @racketmodname[scribble/srcdoc], the documentation creates no run-time overhead for the library. Similarly, typesetting the documentation does not require running the library. The two phases (run time versus documentation time) are kept separate in much the @@ -48,26 +48,26 @@ expressions. @defform[(provide/doc spec ...)]{ -Like @scheme[provide] or @scheme[provide/contract], but each -@scheme[spec] uses a @deftech{documentation transformer} to describe +Like @racket[provide] or @racket[provide/contract], but each +@racket[spec] uses a @deftech{documentation transformer} to describe the exported identifier and its contract. The currently supported @tech{documentation transformers} are -@scheme[proc-doc], @scheme[proc-doc/names], @scheme[parameter-doc], -and @scheme[thing-doc].} +@racket[proc-doc], @racket[proc-doc/names], @racket[parameter-doc], +and @racket[thing-doc].} @defform[(require/doc require-spec ...)]{ -Like @scheme[require], but for bindings that are needed at +Like @racket[require], but for bindings that are needed at documentation time (and documentation-expansion time, etc.) instead of -run time (and expansion time, etc.). A @scheme[require-doc] form has +run time (and expansion time, etc.). A @racket[require-doc] form has no effect on a normal use of the library; it affects only documentation extraction. -Typically, a library that uses @schememodname[scribble/srcdoc] -includes at least @scheme[(require/doc scribble/base scribble/manual)] -to get core Scheme forms and basic Scribble functions to use in +Typically, a library that uses @racketmodname[scribble/srcdoc] +includes at least @racket[(require/doc scribble/base scribble/manual)] +to get core Racket forms and basic Scribble functions to use in documentation expressions.} @defform*/subs[#:literals (-> ->* case->) @@ -81,27 +81,27 @@ documentation expressions.} (code:line keyword contract-expr)] [case-contract (case-> (-> arg ... result) ...)])]{ -When used in @scheme[provide/doc], exports @scheme[id] with the -contract described by @scheme[contract] or @scheme[case-contract], -just like using @scheme[provide/contract]. +When used in @racket[provide/doc], exports @racket[id] with the +contract described by @racket[contract] or @racket[case-contract], +just like using @racket[provide/contract]. -The @scheme[arg-id]s specify the names of arguments, which are not +The @racket[arg-id]s specify the names of arguments, which are not normally written as part of a contract. They are combined with the contract expression to generate the description of the binding in the -documentation via @scheme[defproc]. The @scheme[(arg-id default-expr)] +documentation via @racket[defproc]. The @racket[(arg-id default-expr)] pairs specify the names and default values of the optional arguments. -The @scheme[desc-expr] is a documentation-time expression that +The @racket[desc-expr] is a documentation-time expression that produces prose to describe the exported binding---that is, the last -part of the generated @scheme[defproc], so the description can refer -to the @scheme[arg-id]s using @scheme[scheme]. +part of the generated @racket[defproc], so the description can refer +to the @racket[arg-id]s using @racket[racket]. -The normal @scheme[require]s of the enclosing library are effectively -converted into @scheme[for-label] @scheme[require]s when generating -documentation, so that identifiers in the @scheme[contract]s are +The normal @racket[require]s of the enclosing library are effectively +converted into @racket[for-label] @racket[require]s when generating +documentation, so that identifiers in the @racket[contract]s are linked to their corresponding documentation. Similarly, any binding that is available in the run-time phase of of the enclosing library -can be referenced in documentation prose using the @scheme[scheme] +can be referenced in documentation prose using the @racket[racket] form.} @defform/subs[#:literals (-> ->d values) @@ -113,18 +113,18 @@ form.} (->d (arg ...) () #:pre-cond expression [id result]) (->d (arg ...) () #:rest id rest [id result])])]{ -Like @scheme[proc-doc], but supporting contract forms that embed -argument names. Only a subset of @scheme[->d] forms are currently +Like @racket[proc-doc], but supporting contract forms that embed +argument names. Only a subset of @racket[->d] forms are currently supported.} @defform[(thing-doc id contract-expr dec-expr)]{ -Like @scheme[proc-doc], but for an export of an arbitrary value.} +Like @racket[proc-doc], but for an export of an arbitrary value.} @defform[#:literals (parameter/c) (parameter-doc id (parameter/c contract-expr) arg-id desc-expr)]{ -Like @scheme[proc-doc], but for exporting a parameter.} +Like @racket[proc-doc], but for exporting a parameter.} @; ---------------------------------------- @@ -135,26 +135,26 @@ Like @scheme[proc-doc], but for exporting a parameter.} @defform[(include-extracted module-path)]{ Expands to a sequence of documentation forms extracted from -@scheme[module-path], which is expected to be a module that uses -@schememodname[scribble/srcdoc].} +@racket[module-path], which is expected to be a module that uses +@racketmodname[scribble/srcdoc].} @defform[(provide-extracted module-path)]{ -Similar to @scheme[include-extracted], but the documentation is -packaged and exported as @scheme[exported], instead of left +Similar to @racket[include-extracted], but the documentation is +packaged and exported as @racket[exported], instead of left inline. Use this form in combination with -@scheme[include-previously-extracted] when documentation from a single +@racket[include-previously-extracted] when documentation from a single source is to be split and typeset among multiple documentation -locations. The @scheme[provide-extracted] form extracts the -documentation once, and then @scheme[include-previously-extracted] +locations. The @racket[provide-extracted] form extracts the +documentation once, and then @racket[include-previously-extracted] form extracts documentation for specific bindings as needed.} @defform[(include-previously-extracted module-path regexp)]{ -Similar to @scheme[include-extracted], but instead of referring to the -source that contains its own documentation, @scheme[module-path] -refers to a module that uses @scheme[provide-extracted]. The -@scheme[include-previously-extracted] form expands to documentation -forms for all identifiers whose string forms match @scheme[regexp].} +Similar to @racket[include-extracted], but instead of referring to the +source that contains its own documentation, @racket[module-path] +refers to a module that uses @racket[provide-extracted]. The +@racket[include-previously-extracted] form expands to documentation +forms for all identifiers whose string forms match @racket[regexp].} diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl index fa34ef3e..8ce08ad8 100644 --- a/collects/scribblings/scribble/struct.scrbl +++ b/collects/scribblings/scribble/struct.scrbl @@ -14,18 +14,18 @@ @(define (compat) @italic{For backward compatibility.}) @(define-syntax-rule (compat/comp id) - @elem{@compat[] Compared to the normal constructor for @scheme[id]}) + @elem{@compat[] Compared to the normal constructor for @racket[id]}) @title[#:tag "struct"]{Compatibility Structures And Processing} @defmodule[scribble/struct]{ -The @scheme[scribble/struct] compatibility library mostly re-exports -@scheme[scribble/core], but using some different names (e.g., -@scheme[blockquote] instead of @scheme[nested-flow]).} +The @racket[scribble/struct] compatibility library mostly re-exports +@racket[scribble/core], but using some different names (e.g., +@racket[blockquote] instead of @racket[nested-flow]).} The following structure types and functions are re-exported directly: -@schemeblock[collect-info resolve-info tag? block? +@racketblock[collect-info resolve-info tag? block? delayed-block collected-info delayed-element ; delayed-element-content delayed-block-blocks current-serialize-resolve-info part-relative-element collect-info-parents ; part-relative-element-content delayed-index-desc collect-element render-element generated-tag ; generate-tag current-tag-prefixes add-current-tag-prefix @@ -38,7 +38,7 @@ The following structure types and functions are re-exported directly: The following structure types are re-exported, but the constructors and some selectors are replaced as documented further below: -@schemeblock[part paragraph table itemization compound-paragraph +@racketblock[part paragraph table itemization compound-paragraph element toc-element target-element toc-target-element page-target-element redirect-target-element link-element index-element] @@ -55,14 +55,14 @@ also exported. [parts (listof part?)]) part?]{ -@compat/comp[part], parses @scheme[style] to convert old formats to -the current one. Also, if @scheme[title-content] is a list with a +@compat/comp[part], parses @racket[style] to convert old formats to +the current one. Also, if @racket[title-content] is a list with a single item, the item by itself is stored in the resulting -@scheme[part].} +@racket[part].} @defproc[(part-flow [p part?]) (listof block?)]{ -@compat[] An alias for @scheme[part-blocks].} +@compat[] An alias for @racket[part-blocks].} @defproc[(part-title-content [p part?]) list?]{ @@ -82,10 +82,10 @@ coerced to one.} @defproc[(versioned-part? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-part], but adds a the -@scheme[document-version] @tech{style property} using the given -@scheme[version]. The @scheme[versioned-part?] predicate recognizes a -@scheme[part] with a @scheme[document-version] property.} +@compat[] Like @racket[make-part], but adds a the +@racket[document-version] @tech{style property} using the given +@racket[version]. The @racket[versioned-part?] predicate recognizes a +@racket[part] with a @racket[document-version] property.} @deftogether[( @defproc[(make-unnumbered-part [tag-prefix (or/c false/c string?)] @@ -99,16 +99,16 @@ coerced to one.} @defproc[(unnumbered-part? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-part], but adds the @scheme['unnumbered] -@tech{style property}. The @scheme[unnumbered-part?] predicate -recognizes a @scheme[part] with the @scheme['unnumbered] property.} +@compat[] Like @racket[make-part], but adds the @racket['unnumbered] +@tech{style property}. The @racket[unnumbered-part?] predicate +recognizes a @racket[part] with the @racket['unnumbered] property.} @defproc[(make-paragraph [content list?]) paragraph?]{ @compat/comp[paragraph], omits a style argument. Also, if -@scheme[content] is a list containing a single item, the item by -itself is stored in the resulting @scheme[paragraph].} +@racket[content] is a list containing a single item, the item by +itself is stored in the resulting @racket[paragraph].} @defproc[(paragraph-content [p paragraph?]) list?]{ @@ -123,10 +123,10 @@ coerced to one. @defproc[(styled-paragraph-style [p paragraph?]) style?] )]{ -@compat/comp[paragraph], parses @scheme[style] to convert old formats -to the current one. The @scheme[styled-paragraph?] predicate and -@scheme[styled-paragraph-style] accessor are aliases for -@scheme[paragraph?] and @scheme[paragraph-style].} +@compat/comp[paragraph], parses @racket[style] to convert old formats +to the current one. The @racket[styled-paragraph?] predicate and +@racket[styled-paragraph-style] accessor are aliases for +@racket[paragraph?] and @racket[paragraph-style].} @deftogether[( @@ -134,9 +134,9 @@ to the current one. The @scheme[styled-paragraph?] predicate and @defproc[(omitable-paragraph? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-paragraph], but adds the -@scheme['omitable] @tech{style property}. The -@scheme[omitable-paragraph?] predicate checks for a paragraph with the +@compat[] Like @racket[make-paragraph], but adds the +@racket['omitable] @tech{style property}. The +@racket[omitable-paragraph?] predicate checks for a paragraph with the property.} @@ -146,13 +146,13 @@ property.} @compat/comp[table], the style is converted, and each cell has a list of blocks instead of a single block. If any such list has multiple -blocks, they are combined into a @scheme[nested-flow].} +blocks, they are combined into a @racket[nested-flow].} @defproc[(table-flowss [table table?]) (listof (listof (or/c (listof block?) (one-of/c 'cont))))]{ -@compat[] Like @scheme[table-blockss], but adds a list wrapper to be -consistent with @scheme[make-table].} +@compat[] Like @racket[table-blockss], but adds a list wrapper to be +consistent with @racket[make-table].} @defproc[(make-itemization [blockss (listof (listof block?))]) itemization?]{ @@ -165,16 +165,16 @@ consistent with @scheme[make-table].} @defproc[(styled-itemization-style [i itemization?]) style?] )]{ -@compat/comp[itemization], parses @scheme[style] to convert old -formats to the current one. The @scheme[styled-itemization?] predicate -is an alias for @scheme[itemization?], and -@scheme[styled-itemization-style] is an alias for -@scheme[itemization-style].} +@compat/comp[itemization], parses @racket[style] to convert old +formats to the current one. The @racket[styled-itemization?] predicate +is an alias for @racket[itemization?], and +@racket[styled-itemization-style] is an alias for +@racket[itemization-style].} @defproc[(make-blockquote [style any/c][blocks (listof block?)]) nested-flow?]{ -@compat[] Like @scheme[make-nested-flow], but @scheme[style] is +@compat[] Like @racket[make-nested-flow], but @racket[style] is parsed to the current format.} @@ -185,16 +185,16 @@ parsed to the current format.} @defproc[(auxiliary-table? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-table], but adds the @scheme['aux] -@tech{style property}. The @scheme[auxiliary-table?] predicate recognizes -tables with the @scheme['aux] property.} +@compat[] Like @racket[make-table], but adds the @racket['aux] +@tech{style property}. The @racket[auxiliary-table?] predicate recognizes +tables with the @racket['aux] property.} @defproc[(make-compound-paragraph [style any/c] [blocks (listof block?)]) compound-paragraph?]{ -@compat/comp[compound-paragraph], parses @scheme[style] to convert old +@compat/comp[compound-paragraph], parses @racket[style] to convert old formats to the current one.} @deftogether[( @@ -211,7 +211,7 @@ formats to the current one.} [entry-seq list?] [desc any/c]) index-element?] )]{ -@compat[] Compared to the normal constructors, parses @scheme[style] to convert old +@compat[] Compared to the normal constructors, parses @racket[style] to convert old formats to the current one.} @@ -222,42 +222,42 @@ formats to the current one.} )]{ @compat[] A @tech{content} list is treated as an element by these functions, -and the result of @scheme[element-content] is always a list.} +and the result of @racket[element-content] is always a list.} @defproc[(make-aux-element [style any/c] [content list?]) element?]{ -@compat[] Like @scheme[make-element], but adds the @scheme['aux] +@compat[] Like @racket[make-element], but adds the @racket['aux] @tech{style property}.} @defproc[(make-hover-element [style any/c] [content list?] [text string?]) element?]{ -@compat[] Like @scheme[make-element], but adds @scheme[hover-property] -containing @scheme[text] to the element's style.} +@compat[] Like @racket[make-element], but adds @racket[hover-property] +containing @racket[text] to the element's style.} @defproc[(make-script-element [style any/c] [content list?] [type string?] [script (or/c path-string? (listof string?))]) element?]{ -@compat[] Like @scheme[make-element], but adds @scheme[script-property] -containing @scheme[type] and @scheme[script] to the element's style.} +@compat[] Like @racket[make-element], but adds @racket[script-property] +containing @racket[type] and @racket[script] to the element's style.} @defstruct[with-attributes ([style any/c] [assoc (listof (cons/c symbol? string?))])]{ -@compat[] Used for an @scheme[element]'s style to combine a base style with -arbitrary HTML attributes. When the @scheme[style] field is itself an -instance of @scheme[with-attributes], its content is automatically -flattened into the enclosing @scheme[with-attributes] when it is used -(when, e.g., rendering an @scheme[element] or @scheme[paragraph]).} +@compat[] Used for an @racket[element]'s style to combine a base style with +arbitrary HTML attributes. When the @racket[style] field is itself an +instance of @racket[with-attributes], its content is automatically +flattened into the enclosing @racket[with-attributes] when it is used +(when, e.g., rendering an @racket[element] or @racket[paragraph]).} @defstruct[target-url ([addr path-string?] [style any/c])]{ -@compat[] Used as a style for an @scheme[element]. The @scheme[style] at this +@compat[] Used as a style for an @racket[element]. The @racket[style] at this layer is a style for the hyperlink.} @@ -265,9 +265,9 @@ layer is a style for the hyperlink.} (cons/c 'collects (listof bytes?)))] [scale real?])]{ -@compat[] Used as a style for an @scheme[element] to inline an image. The -@scheme[path] field can be a result of -@scheme[path->main-collects-relative].} +@compat[] Used as a style for an @racket[element] to inline an image. The +@racket[path] field can be a result of +@racket[path->main-collects-relative].} @@ -275,6 +275,6 @@ layer is a style for the hyperlink.} @defproc*[([(element->string (element content?)) string?] [(element->string (element content?) (renderer any/c) (p part?) (info resolve-info?)) string?])]{ -@compat[] An alias for @scheme[content->string]. +@compat[] An alias for @racket[content->string]. } diff --git a/collects/scribblings/scribble/xref.scrbl b/collects/scribblings/scribble/xref.scrbl index 6956616f..ec9100c7 100644 --- a/collects/scribblings/scribble/xref.scrbl +++ b/collects/scribblings/scribble/xref.scrbl @@ -8,7 +8,7 @@ @title[#:tag "xref"]{Cross-Reference Utilities} -@defmodule[scribble/xref]{The @schememodname[scribble/xref] library +@defmodule[scribble/xref]{The @racketmodname[scribble/xref] library provides utilities for querying cross-reference information that was collected from a document build.} @@ -16,8 +16,8 @@ collected from a document build.} @defproc[(xref? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a cross-reference record created -by @scheme[load-xref], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a cross-reference record created +by @racket[load-xref], @racket[#f] otherwise.} @defproc[(load-xref [sources (listof (-> any/c))] @@ -28,18 +28,18 @@ by @scheme[load-xref], @scheme[#f] otherwise.} Creates a cross-reference record given a list of functions that each produce a serialized information obtained from @xmethod[render% -serialize-info]. If a @scheme[sources] element produces @scheme[#f], +serialize-info]. If a @racket[sources] element produces @racket[#f], its result is ignored. Since the format of serialized information is specific to a rendering -class, the optional @scheme[using-render%] argument accepts the +class, the optional @racket[using-render%] argument accepts the relevant class. It default to HTML rendering. -If @scheme[root-path] is not @scheme[#f], then file paths that are -serialized as relative to an instantiation-supplied @scheme[root-path] -are deserialized as relative instead to the given @scheme[root-path]. +If @racket[root-path] is not @racket[#f], then file paths that are +serialized as relative to an instantiation-supplied @racket[root-path] +are deserialized as relative instead to the given @racket[root-path]. -Use @scheme[load-collections-xref] from @schememodname[setup/xref] to +Use @racket[load-collections-xref] from @racketmodname[setup/xref] to get all cross-reference information for installed documentation.} @@ -58,7 +58,7 @@ get all cross-reference information for installed documentation.} [mode (or/c exact-integer? false/c)]) (or/c tag? false/c)]{ -Locates a tag in @scheme[xref] that documents a module export. The +Locates a tag in @racket[xref] that documents a module export. The binding is specified in one of several ways, as described below; all possibilities encode an exporting module and a symbolic name. The name must be exported from the specified module. Documentation is found @@ -66,35 +66,35 @@ either for the specified module or, if the exported name is re-exported from other other module, for the other module (transitively). -The @scheme[mode] argument specifies the relevant phase level for the -binding. The @scheme[binding] is specified in one of four ways: +The @racket[mode] argument specifies the relevant phase level for the +binding. The @racket[binding] is specified in one of four ways: @itemize[ - @item{If @scheme[binding] is an identifier, then - @scheme[identifier-binding] is used with @scheme[mode] to + @item{If @racket[binding] is an identifier, then + @racket[identifier-binding] is used with @racket[mode] to determine the binding.} - @item{If @scheme[binding] is a two-element list, then the first + @item{If @racket[binding] is a two-element list, then the first element provides the exporting module and the second the - exported name. The @scheme[mode] argument is effectively + exported name. The @racket[mode] argument is effectively ignored.} - @item{If @scheme[binding] is a seven-element list, then it corresponds - to a result from @scheme[identifier-binding] using - @scheme[mode].} + @item{If @racket[binding] is a seven-element list, then it corresponds + to a result from @racket[identifier-binding] using + @racket[mode].} - @item{If @scheme[binding] is a five-element list, then the first + @item{If @racket[binding] is a five-element list, then the first element is as for the two-element-list case, and the remain elements are as in the last four elements of the seven-element case.} ] -If a documentation point exists in @scheme[xref], a tag is returned, -which might be used with @scheme[xref-tag->path+anchor] or embedded in -a document rendered via @scheme[xref-render]. If no definition point -is found in @scheme[xref], the result is @scheme[#f].} +If a documentation point exists in @racket[xref], a tag is returned, +which might be used with @racket[xref-tag->path+anchor] or embedded in +a document rendered via @racket[xref-render]. If no definition point +is found in @racket[xref], the result is @racket[#f].} @defproc[(xref-tag->path+anchor [xref xref?] @@ -104,24 +104,24 @@ is found in @scheme[xref], the result is @scheme[#f].} (values (or/c false/c path?) (or/c false/c string?))]{ -Returns a path and anchor string designated by the key @scheme[tag] -according the cross-reference @scheme[xref]. The first result is -@scheme[#f] if no mapping is found for the given tag. The second -result is @scheme[#f] if the first result is @scheme[#f], and it can -also be @scheme[#f] if the tag refers to a page rather than a specific +Returns a path and anchor string designated by the key @racket[tag] +according the cross-reference @racket[xref]. The first result is +@racket[#f] if no mapping is found for the given tag. The second +result is @racket[#f] if the first result is @racket[#f], and it can +also be @racket[#f] if the tag refers to a page rather than a specific point in a page. -The optional @scheme[using-render%] argument is as for -@scheme[load-xref].} +The optional @racket[using-render%] argument is as for +@racket[load-xref].} @defproc[(xref-tag->index-entry [xref xref?] [tag tag?]) (or/c false/c entry?)]{ -Extract an @scheme[entry] structure that provides addition information -about the definition (of any) referenced by @scheme[tag]. This -function can be composed with @scheme[xref-binding->definition-tag] to +Extract an @racket[entry] structure that provides addition information +about the definition (of any) referenced by @racket[tag]. This +function can be composed with @racket[xref-binding->definition-tag] to obtain information about a binding, such as the library that exports the binding and its original name.} @@ -134,22 +134,22 @@ the binding and its original name.} [#:refer-to-existing-files? use-existing? any/c (not dest)]) (or/c void? any/c)]{ -Renders @scheme[doc] using the cross-reference info in @scheme[xref] -to the destination @scheme[dest]. For example, @scheme[doc] might be a +Renders @racket[doc] using the cross-reference info in @racket[xref] +to the destination @racket[dest]. For example, @racket[doc] might be a generated document of search results using link tags described in -@scheme[xref]. +@racket[xref]. -If @scheme[dest] is @scheme[#f], no file is written, and the result is +If @racket[dest] is @racket[#f], no file is written, and the result is an X-expression for the rendered page. Otherwise, the file -@scheme[dest] is written and the result is @|void-const|. +@racket[dest] is written and the result is @|void-const|. -The optional @scheme[using-render%] argument is as for -@scheme[load-xref]. It determines the kind of output that is +The optional @racket[using-render%] argument is as for +@racket[load-xref]. It determines the kind of output that is generated. -If @scheme[use-existing?] is true, then files referenced during +If @racket[use-existing?] is true, then files referenced during rendering (such as image files) are referenced from their existing -locations, instead of copying to the directory of @scheme[dest].} +locations, instead of copying to the directory of @racket[dest].} @defproc[(xref-transfer-info [renderer (is-a?/c render%)] @@ -157,15 +157,15 @@ locations, instead of copying to the directory of @scheme[dest].} [xref xref?]) void?]{ -Transfers cross-reference information to @scheme[ci], which is the -initially collected information from @scheme[renderer].} +Transfers cross-reference information to @racket[ci], which is the +initially collected information from @racket[renderer].} @defproc[(xref-index [xref xref?]) (listof entry?)]{ -Converts indexing information @scheme[xref] into a list of -@scheme[entry] structures.} +Converts indexing information @racket[xref] into a list of +@racket[entry] structures.} @defstruct[entry ([words (and/c (listof string?) cons?)] @@ -175,8 +175,8 @@ Converts indexing information @scheme[xref] into a list of Represents a single entry in a Scribble document index. -The @scheme[words] list corresponds to -@scheme[index-element-plain-seq]. The @scheme[content] list -corresponds to @scheme[index-element-entry-seq]. The @scheme[desc] -value corresponds to @scheme[index-element-desc]. The @scheme[tag] is +The @racket[words] list corresponds to +@racket[index-element-plain-seq]. The @racket[content] list +corresponds to @racket[index-element-entry-seq]. The @racket[desc] +value corresponds to @racket[index-element-desc]. The @racket[tag] is the destination for the index link into the main document.}