suzanne.soy/hyper-literate
1
0
Fork 0
Code Issues 4 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

rackety Scribble doc

Browse Source 
original commit: fb4af544366583b2d0a154cad2b8251c73b3a439
This commit is contained in:
Matthew Flatt 2010-05-02 12:00:44 -06:00
parent 93eb15e721
commit 15e7763f70
25 changed files with 1701 additions and 1653 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

272
collects/scribblings/scribble/base.scrbl
View File

@ -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.}

10
collects/scribblings/scribble/basic.scrbl
View File

@ -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.}

16
collects/scribblings/scribble/bnf.scrbl
View File

@ -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?]{

578
collects/scribblings/scribble/core.scrbl
View File

File diff suppressed because it is too large Load Diff

108
collects/scribblings/scribble/decode.scrbl
View File

@ -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].
}

18
collects/scribblings/scribble/doclang.scrbl
View File

@ -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.

6
collects/scribblings/scribble/docreader.scrbl
View File

@ -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.}

82
collects/scribblings/scribble/eval.scrbl
View File

@ -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.}

188
collects/scribblings/scribble/how-to-paper.scrbl
View File

@ -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.

204
collects/scribblings/scribble/how-to.scrbl
View File

@ -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.
@;----------------------------------------

26
collects/scribblings/scribble/jfp.scrbl
View File

@ -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.}

156
collects/scribblings/scribble/layers.scrbl
View File

@ -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.

42
collects/scribblings/scribble/lp.scrbl
View File

@ -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.
}

2
collects/scribblings/scribble/manual-stub.scrbl
View File

@ -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:

868
collects/scribblings/scribble/manual.scrbl
View File

File diff suppressed because it is too large Load Diff

4
collects/scribblings/scribble/plt.scrbl
View File

@ -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

100
collects/scribblings/scribble/reader-internals.scrbl
View File

@ -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.}

142
collects/scribblings/scribble/reader.scrbl
View File

@ -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)

58
collects/scribblings/scribble/renderer.scrbl
View File

@ -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.}}

150
collects/scribblings/scribble/scheme.scrbl
View File

@ -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.}

2
collects/scribblings/scribble/scribble.scrbl
View File

@ -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.

20
collects/scribblings/scribble/sigplan.scrbl
View File

@ -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.}

88
collects/scribblings/scribble/srcdoc.scrbl
View File

@ -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].}

112
collects/scribblings/scribble/struct.scrbl
View File

@ -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].
}

102
collects/scribblings/scribble/xref.scrbl
View File

@ -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.}