b3f7015cba
Although commit 5415cca336 just made run-time checking consistent with
the documentation, the implementation turned out to allow content
before, and some existing documents relied on that. Changes the
documentation and contract to allow content, instead.
2225 lines
88 KiB
Racket
2225 lines
88 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual "utils.rkt"
|
|
(for-syntax racket/base)
|
|
(for-label scribble/manual-struct
|
|
version/utils
|
|
syntax/quote))
|
|
|
|
@(define lit-ellipses (racket ...))
|
|
@(define lit-ellipses+ (racket ...+))
|
|
|
|
@title[#:tag "manual" #:style 'toc]{Manual Forms}
|
|
|
|
@defmodulelang[scribble/manual]{The @racketmodname[scribble/manual]
|
|
language provides all of @racketmodname[scribble/base] plus many
|
|
additional functions that are specific to writing Racket
|
|
documentation. It also associates @tech{style properties} with the
|
|
generated @racket[doc] export to select the default Racket manual
|
|
style for rendering; see @secref["manual-render-style"] for more
|
|
information.
|
|
|
|
The @racketmodname[scribble/manual] name can also be used as a library
|
|
with @racket[require], in which case it provides all of the same
|
|
bindings, but without setting the reader or setting the default
|
|
rendering format to the Racket manual format.}
|
|
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "scribble:manual:code"]{Typesetting Code}
|
|
|
|
The @racket[codeblock] and @racket[code] forms (see
|
|
@secref["all-code"]) typeset code verbatim, adding a layer of color to
|
|
the code based on the same syntax-coloring parsers that are used by
|
|
DrRacket. Input that is parsed as an identifier is further given a
|
|
lexical context and hyperlinked via @racket[for-label] imports.
|
|
|
|
The @racket[racketblock] and @racket[racket] forms (see
|
|
@secref["racket-code"]) typeset S-expression code roughly verbatim,
|
|
but roughly by quoting the source term with
|
|
@racket[syntax]. Identifiers in the quoted S-expression are
|
|
hyperlinked via @racket[for-label] imports.
|
|
|
|
The two different approaches to typesetting code---@racket[codeblock]
|
|
and @racket[code] versus @racket[racketblock] and
|
|
@racket[racket]---have different advantages and disadvantages:
|
|
|
|
@itemlist[
|
|
|
|
@item{The @racket[codeblock] and @racket[code] forms work with
|
|
non-S-expression syntax, and they give authors more control
|
|
over output (e.g., the literal number @code{2/4} is not
|
|
normalized to @racket[2/4]). The @racket[codeblock] and
|
|
@racket[code] forms do not yet support escapes to Scribble
|
|
element mode, and they cannot adapt spacing based on the width
|
|
of elements in escapes.}
|
|
|
|
@item{The @racket[racketblock] and @racket[racket] forms are more
|
|
efficient and allow escapes to Scribble element mode. The
|
|
@racket[racketblock] and @racket[racket] forms are tied to
|
|
S-expression syntax, however, and they are based on a syntax
|
|
representation that tends to normalize source terms (e.g., the
|
|
literal number @code{2/4} is normalized to @racket[2/4]).}
|
|
|
|
]
|
|
|
|
@; ----------------------------------------
|
|
@subsection[#:tag "all-code"]{@hash-lang[]-Specified Code}
|
|
|
|
@defform/subs[(codeblock option ... str-expr ...+)
|
|
([option (code:line #:keep-lang-line? keep-expr)
|
|
(code:line #:indent indent-expr)
|
|
(code:line #:expand expand-expr)
|
|
(code:line #:context context-expr)
|
|
(code:line #:line-numbers line-number-expr)
|
|
(code:line #:line-number-sep line-number-sep-expr)])
|
|
#:contracts ([keep-expr any/c]
|
|
[indent-expr exact-nonnegative-integer?]
|
|
[expand-expr (or/c #f (syntax? . -> . syntax?))]
|
|
[context-expr (or/c #f syntax?)]
|
|
[line-number-expr (or/c #f exact-nonnegative-integer?)]
|
|
[line-number-sep-expr exact-nonnegative-integer?])]{
|
|
|
|
Parses the code formed by the strings produced by the
|
|
@racket[str-expr]s as a Racket module (roughly) and produces a
|
|
@tech{block} that typesets the code inset via @racket[nested] with the
|
|
style @racket['code-inset]. See also @racket[typeset-code].
|
|
|
|
The @racket[str-expr]s should normally start with @hash-lang[] to
|
|
determine the reader syntax for the module, but the resulting
|
|
``module'' need not expand or compile---except as needed by
|
|
@racket[expand-expr]. If @racket[expand-expr] is omitted or produces
|
|
false, then the input formed by @racket[str-expr] is read until an
|
|
end-of-file is encountered, otherwise a single form is read from the
|
|
input.
|
|
|
|
When @racket[keep-expr] produces a true value (the default), the first
|
|
line in the input (which is typically @hash-lang[]) is preserved in
|
|
the typeset output, otherwise the first line is dropped. The typeset
|
|
code is indented by the amount specified by @racket[indent-expr],
|
|
which defaults to @racket[0].
|
|
|
|
When @racket[expand-expr] produces @racket[#f] (which is the default),
|
|
identifiers in the typeset code are colored and linked based on
|
|
for-label bindings in the lexical environment of the syntax object
|
|
provided by @racket[context-expr]. The default @racket[context-expr]
|
|
has the same lexical context as the first @racket[str-expr].
|
|
When @racket[line-number-expr] is true, line number is enabled starting
|
|
from @racket[line-number-expr], and @racket[line-number-sep-expr] controls
|
|
the separation (in spaces; defaults to 1) between the line numbers and
|
|
code.
|
|
|
|
When @racket[expand-expr] produces a procedure, it is used to
|
|
macro-expand the parsed program, and syntax coloring is based on the
|
|
parsed program.
|
|
|
|
For example,
|
|
|
|
@codeblock[#:keep-lang-line? #f]|<|{
|
|
#lang scribble/manual
|
|
@codeblock|{
|
|
#lang scribble/manual
|
|
@codeblock{
|
|
#lang scribble/manual
|
|
@title{Hello}
|
|
}
|
|
}|
|
|
}|>|
|
|
|
|
produces the typeset result
|
|
|
|
@codeblock|{
|
|
#lang scribble/manual
|
|
@codeblock{
|
|
#lang scribble/manual
|
|
@title{Hello}
|
|
}
|
|
}|
|
|
|
|
}
|
|
|
|
|
|
@defform[(codeblock0 option ... str-expr ...+)]{
|
|
|
|
Like @racket[codeblock], but without the @racket['code-inset]
|
|
@racket[nested] wrapper.}
|
|
|
|
|
|
@defform/subs[(code option ... str-expr ...+)
|
|
([option (code:line #:lang lang-line-expr)
|
|
(code:line #:expand expand-expr)
|
|
(code:line #:context context-expr)])
|
|
#:contracts ([lang-line-expr (or/c #f string?)]
|
|
[expand-expr (or/c #f (syntax? . -> . syntax?))]
|
|
[context-expr (or/c #f syntax?)])]{
|
|
|
|
Like @racket[codeblock], but produces @tech{content} instead of a
|
|
@tech{block}. No @hash-lang[] line should appear in the string content;
|
|
instead, it should be provided @racket[#:lang] (as a string
|
|
without @racket["#lang "]) if needed, and the @hash-lang[] line is always stripped
|
|
from the output when provided. Also, each newline in @racket[str-expr]s is collapsed
|
|
along with all surrounding whitespace to a single space.
|
|
|
|
For example,
|
|
|
|
@codeblock[#:keep-lang-line? #f]|<|{
|
|
#lang scribble/manual
|
|
This is @code[#:lang "at-exp racket"]|{@bold{Hi}}|'s result:
|
|
@bold{Hi}.
|
|
}|>|
|
|
|
|
produces the typeset result
|
|
|
|
@nested[#:style 'inset]{
|
|
This is @code[#:lang "at-exp racket"]|{@bold{Hi}}|'s result:
|
|
@bold{Hi}.
|
|
}
|
|
|
|
}
|
|
|
|
@defproc[(typeset-code [#:context context (or/c #f syntax?) #f]
|
|
[#:expand expand (or/c #f (syntax? . -> . syntax?)) #f]
|
|
[#:indent indent exact-nonnegative-integer? 2]
|
|
[#:keep-lang-line? keep? any/c #t]
|
|
[#:line-numbers line-numbers (or/c #f exact-nonnegative-integer?) #f]
|
|
[#:line-number-sep line-number-sep exact-nonnegative-integer? 1]
|
|
[#:block? return-block? any/c #t]
|
|
[strs string?] ...)
|
|
(if return-block? block? element?)]{
|
|
A function-based version of @racket[codeblock], allowing you to compute the @racket[strs] arguments.
|
|
|
|
Unlike @racket[codeblock], the default @racket[context] argument (@racket[#f]) implies that
|
|
the context is untouched and the @racket[return-block?] argument determines the result
|
|
structure. The other arguments are treated the same way as @racket[codeblock].
|
|
}
|
|
|
|
@; ----------------------------------------
|
|
@subsection[#:tag "racket-code"]{Racket Code}
|
|
|
|
@defform/subs[(racketblock maybe-escape datum ...)
|
|
([maybe-escape code:blank
|
|
(code:line #:escape escape-id)])]{
|
|
|
|
Typesets the @racket[datum] sequence as a table of Racket code
|
|
inset via @racket[nested] with the style @racket['code-inset]. The
|
|
source locations of the @racket[datum]s determine the generated
|
|
layout. For example,
|
|
|
|
@racketblock[
|
|
(racketblock
|
|
(define (loop x)
|
|
(loop (not x))))
|
|
]
|
|
|
|
produces the output
|
|
|
|
@racketblock[
|
|
(define (loop x)
|
|
(loop (not x)))
|
|
]
|
|
|
|
with the @racket[(loop (not x))] indented under @racket[define],
|
|
because that's the way it is idented the use of @racket[racketblock].
|
|
Source-location span information is used to preserve @racket[#true]
|
|
versus @racket[#t] and @racket[#false] versus @racket[#f]; span
|
|
information is also used heuristically to add @racketvalfont{#i}
|
|
to the start of an inexact number if its printed form would otherwise
|
|
be two characters shorter than the source;
|
|
syntax-object properties are used to preserve square brackets and
|
|
curly braces versus parentheses; otherwise, using syntax objects tends
|
|
to normalize the form of S-expression elements, such as rendering
|
|
@code{2/4} as @racket[2/4]. When source-location information is not
|
|
available, such as when it is lost by bytecode-compiled macros,
|
|
spacing is inserted in the same style (within a single line) as the
|
|
@racket[racket] form.
|
|
|
|
@margin-note{See also @racket[quote-syntax/keep-srcloc] for use in a
|
|
macro to preserve source-location information in a template.}
|
|
|
|
In the above example, @racket[define] is typeset as a keyword (in black)
|
|
and as a hyperlink to @racket[define]'s definition in the reference
|
|
manual, because this document was built using a @racket[for-label] binding of
|
|
@racket[define] (in the source) that matches a definition in the
|
|
reference manual. Similarly, @racket[not] is a hyperlink to its
|
|
definition in the reference manual.
|
|
|
|
Like other forms defined via @racket[define-code],
|
|
@racket[racketblock] expands identifiers that are bound as
|
|
@tech{element transformers}.
|
|
|
|
An @racket[#:escape] clause specifies an identifier to escape back to
|
|
an expression that produces an @racket[element]. By default,
|
|
the escape identifier is @racket[unsyntax]. For example,
|
|
|
|
@racketblock[
|
|
#:escape nonesuch
|
|
(racketblock
|
|
(+ 1 (unsyntax (elem (racket x) (subscript "2")))))
|
|
]
|
|
|
|
produces
|
|
|
|
@racketblock[
|
|
(+ 1 (unsyntax (elem (racket x) (subscript "2"))))
|
|
]
|
|
|
|
The @racket[escape-id] that defaults to @racket[unsyntax] is recognized via
|
|
@racket[free-identifier=?], so a binding can hide the escape behavior:
|
|
|
|
@RACKETBLOCK[
|
|
(racketblock
|
|
(let ([(UNSYNTAX (racket unsyntax)) #f])
|
|
(racketblock
|
|
(syntax (+ 1 (unsyntax x))))))
|
|
]
|
|
|
|
The @racket[RACKETBLOCK] form's default escape is @racket[UNSYNTAX]
|
|
instead of @racket[unsyntax].
|
|
|
|
A few other escapes are recognized symbolically:
|
|
|
|
@itemize[
|
|
|
|
@item{@racket[(#,(indexed-racket code:line) _datum ...)] typesets as the
|
|
sequence of @racket[_datum]s (i.e., without the
|
|
@racket[code:line] wrapper).}
|
|
|
|
@item{@racket[(#,(indexed-racket code:comment) _content)] typesets like
|
|
@racket[_content], but colored as a comment and prefixed with a
|
|
semi-colon. A typical @racket[_content] escapes from
|
|
Racket-typesetting mode using @racket[unsyntax] and
|
|
produces a string, an element using @racket[elem],
|
|
or a paragraph using @racket[t]:
|
|
|
|
@verbatim[#:indent 2]|{
|
|
(code:comment @#,elem{this is a comment})
|
|
}|
|
|
|
|
(Note that @litchar|{@#,foo{...}}| reads as
|
|
@RACKET[(unsyntax (foo "..."))].)
|
|
}
|
|
|
|
@item{@racket[(#,(indexed-racket code:contract) _datum ...)] typesets like
|
|
the sequence of @racket[_datum]s (including its coloring), but prefixed with a
|
|
semi-colon.}
|
|
|
|
@item{@as-index[@racketidfont{code:blank}] typesets as a blank space.}
|
|
|
|
@item{@racket[(#,(indexed-racket code:hilite) _datum)] typesets like
|
|
@racket[_datum], but with a background highlight.}
|
|
|
|
@item{@racket[(#,(indexed-racket code:quote) _datum)] typesets like
|
|
@racket[(@#,racketidfont{quote} _datum)], but without rendering the
|
|
@racketidfont{quote} as @litchar{'}.}
|
|
|
|
@item{@racketidfont{_}@racket[_id] typesets as @racket[id], but
|
|
colored as a variable (like @racket[racketvarfont]); this
|
|
escape applies only if @racketidfont{_}@racket[_id] has no
|
|
for-label binding and is not specifically colored as a subform
|
|
non-terminal via @racket[defform], a variable via
|
|
@racket[defproc], etc.}
|
|
|
|
]
|
|
|
|
See also @racketmodname[scribble/comment-reader].
|
|
|
|
@history[#:changed "1.9" @elem{Added heuristic for adding @racketvalfont{#i} to inexact numbers.}]}
|
|
|
|
@defform[(RACKETBLOCK maybe-escape datum ...)]{Like @racket[racketblock], but with
|
|
the default expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].}
|
|
|
|
@defform[(racketblock0 maybe-escape datum ...)]{Like @racket[racketblock], but
|
|
without insetting the code via @racket[nested].}
|
|
|
|
@defform[(RACKETBLOCK0 maybe-escape datum ...)]{Like @racket[RACKETBLOCK], but
|
|
without insetting the code via @racket[nested].}
|
|
|
|
@deftogether[(
|
|
@defform[(racketresultblock maybe-escape datum ...)]
|
|
@defform[(racketresultblock0 maybe-escape datum ...)]
|
|
@defform[(RACKETRESULTBLOCK maybe-escape datum ...)]
|
|
@defform[(RACKETRESULTBLOCK0 maybe-escape datum ...)]
|
|
)]{
|
|
|
|
Like @racket[racketblock], etc., but colors the typeset text as a
|
|
result (i.e., a single color with no hyperlinks) instead of code.
|
|
|
|
Unlike @racket[racketblock], @racket[racketresultblock] and
|
|
@racket[RACKETRESULTBLOCK] implement indentation by adding an
|
|
@racket[(hspace 2)] to the start of each line, instead of using
|
|
@racket[nested] with the @racket['code-inset] style. To get formatting
|
|
more like @racket[racketblock] and @racket[racketinput], use
|
|
@racket[(nested #:style 'code-inset (racketresultblock0 datum ...))]
|
|
instead of @racket[(racketresultblock datum ...)].}
|
|
|
|
@deftogether[(
|
|
@defform[(racketinput maybe-escape datum ...)]
|
|
@defform[(RACKETINPUT maybe-escape datum ...)]
|
|
)]{Like @racket[racketblock] and @racket[RACKETBLOCK], but the
|
|
@racket[datum]s are typeset after a prompt representing a REPL.}
|
|
|
|
@deftogether[(
|
|
@defform[(racketinput0 maybe-escape datum ...)]
|
|
@defform[(RACKETINPUT0 maybe-escape datum ...)]
|
|
)]{
|
|
Like @racket[racketinput] and @racket[RACKETINPUT], but
|
|
without insetting the code via @racket[nested].}
|
|
|
|
@defform/subs[(racketmod maybe-file maybe-escape lang datum ...)
|
|
([maybe-file code:blank
|
|
(code:line #:file filename-expr)]
|
|
[maybe-escape code:blank
|
|
(code:line #:escape escape-id)])]{
|
|
|
|
Like @racket[racketblock], but the @racket[datum] are typeset inside a
|
|
@racketmodfont{#lang}-form module whose language is @racket[lang].
|
|
|
|
The source location of @racket[lang] (relative to the body
|
|
@racket[datum]s) determines the relative positioning of the
|
|
@racketmodfont{#lang} line in the typeset output. So, line up
|
|
@racket[lang] with the left end of the content code.
|
|
|
|
If @racket[#:file] is provided, then the code block is typeset using
|
|
@racket[filebox] with @racket[filename-expr] as the filename
|
|
argument.}
|
|
|
|
@defform[(racketmod0 maybe-file maybe-escape lang datum ...)]{
|
|
Like @racket[racketmod], but
|
|
without insetting the code via @racket[nested].}
|
|
|
|
@defform[(racket maybe-escape datum ...)]{Like @racket[racketblock], but typeset on
|
|
a single line and wrapped with its enclosing paragraph, independent of
|
|
the formatting of @racket[datum].}
|
|
|
|
@defform[(RACKET maybe-escape datum ...)]{Like @racket[racket], but with the
|
|
@racket[UNSYNTAX] escape like @racket[racketblock].}
|
|
|
|
@defform[(racketresult maybe-escape datum ...)]{Like @racket[racket], but typeset
|
|
as a result (i.e., a single color with no hyperlinks).}
|
|
|
|
@defform[(racketid maybe-escape datum ...)]{Like @racket[racket], but typeset
|
|
as an unbound identifier (i.e., no coloring or hyperlinks).}
|
|
|
|
@deftogether[(
|
|
@defform[(schemeblock maybe-escape datum ...)]
|
|
@defform[(SCHEMEBLOCK maybe-escape datum ...)]
|
|
@defform[(schemeblock0 maybe-escape datum ...)]
|
|
@defform[(SCHEMEBLOCK0 maybe-escape datum ...)]
|
|
@defform[(schemeinput maybe-escape datum ...)]
|
|
@defform[(schememod lang maybe-escape datum ...)]
|
|
@defform[(scheme maybe-escape datum ...)]
|
|
@defform[(SCHEME maybe-escape datum ...)]
|
|
@defform[(schemeresult maybe-escape datum ...)]
|
|
@defform[(schemeid maybe-escape datum ...)]
|
|
)]{
|
|
|
|
Compatibility aliases. Each @racketidfont{scheme...} name is an alias for the
|
|
corresponding @racketidfont{racket...} binding.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
|
|
@subsection{Preserving Comments}
|
|
|
|
@defmodulereader[scribble/comment-reader]
|
|
|
|
As a reader module, @racketmodname[scribble/comment-reader] reads a
|
|
single S-expression that contains @litchar{;}-based comment lines, and
|
|
it wraps the comments with @racket[code:comment] for use with forms
|
|
like @racket[racketblock]. More precisely,
|
|
@racketmodname[scribble/comment-reader] extends the current reader to
|
|
adjust the parsing of @litchar{;}.
|
|
|
|
For example, within a Scribble document that imports
|
|
@racketmodname[scribble/manual],
|
|
|
|
@verbatim[#:indent 2]|{
|
|
@#reader scribble/comment-reader
|
|
(racketblock
|
|
;; This is not a pipe
|
|
(make-pipe)
|
|
)
|
|
}|
|
|
|
|
generates
|
|
|
|
@#reader scribble/comment-reader
|
|
(racketblock
|
|
;; This is not a pipe
|
|
(make-pipe)
|
|
)
|
|
|
|
The initial @litchar["@"] is needed above to shift into S-expression
|
|
mode, so that @racketmetafont{#reader} is recognized as a reader
|
|
declaration instead of literal text. Also, the example uses
|
|
@racket[(racketblock ....)] instead of
|
|
@racketmetafont["@"]@racket[racketblock]@racketmetafont["["]@racket[....]@racketmetafont["]"]
|
|
because the @"@"-reader would drop comments within the
|
|
@racket[racketblock] before giving
|
|
@racketmodname[scribble/comment-reader] a chance to convert them.
|
|
|
|
The implementation of @racketmodname[scribble/comment-reader] uses @racket[unsyntax] to
|
|
typeset comments. When using @racketmodname[scribble/comment-reader]
|
|
with, for instance, @racket[RACKETBLOCK], @racket[unsyntax] does not escape,
|
|
since @racket[RACKETBLOCK] uses @racket[UNSYNTAX] as its escape form. You can
|
|
declare an escape identifier for
|
|
@racketmodname[scribble/comment-reader] with @racket[#:escape-id]. For example,
|
|
|
|
@verbatim[#:indent 2]|{
|
|
@#reader scribble/comment-reader #:escape-id UNSYNTAX
|
|
(RACKETBLOCK
|
|
(define-syntax (m stx)
|
|
(syntax-case stx ()
|
|
[(_ x)
|
|
;; Well this was silly
|
|
#`(#,x)]))
|
|
)
|
|
}|
|
|
|
|
generates
|
|
|
|
@#reader scribble/comment-reader #:escape-id UNSYNTAX
|
|
(RACKETBLOCK
|
|
(define-syntax (m stx)
|
|
(syntax-case stx ()
|
|
[(_ x)
|
|
;; Well this was silly
|
|
#`(#,x)]))
|
|
)
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@subsection{Code Fonts and Styles}
|
|
|
|
@defform*[((racketmodname datum maybe-indirect)
|
|
(racketmodname ((unsyntax (racket unsyntax)) expr) maybe-indirect))
|
|
#:grammar ([maybe-indirect code:blank
|
|
#:indirect])]{
|
|
|
|
Like @racket[racket], but typeset as a module path and without special
|
|
treatment of identifiers (such as @racketidfont{code:blank} or identifiers
|
|
that start with @litchar{_}). If @racket[datum] is an identifier or
|
|
@racket[expr] produces a symbol, then it is hyperlinked to the module
|
|
path's definition as created by @racket[defmodule].
|
|
|
|
If @racket[#:indirect] is specified, then the hyperlink is given the
|
|
@racket['indirect-link] @tech{style property}, which makes the
|
|
hyperlink's resolution in HTML potentially delayed; see
|
|
@racket['indirect-link] for @racket[link-element].
|
|
|
|
@history[#:changed "1.21" @elem{Disabled @racket[racket]-style special
|
|
treatment of identifiers.}]}
|
|
|
|
@defform[(racketmodlink datum pre-content-expr ...)]{
|
|
Like @racket[racketmodname], but separating the module path to link
|
|
from the content to be linked. The @racket[datum] module path is always
|
|
linked, even if it is not an identifier.}
|
|
|
|
@defproc[(litchar [str string?] ...) element?]{Typesets @racket[str]s as a
|
|
representation of literal text. Use this when you have to talk about
|
|
the individual characters in a stream of text, as when documenting
|
|
a reader extension.}
|
|
|
|
@defproc[(racketfont [pre-content pre-content?] ...) element?]{The
|
|
same as @racket[(tt pre-content ...)], which applies the @racket['tt]
|
|
style to immediate strings and symbols among the @racket[pre-content]
|
|
arguments. Beware that @racket[pre-content] is @racket[decode]d as
|
|
usual, making @racket[racketfont] a poor choice for typesetting
|
|
literal code.}
|
|
|
|
@defproc[(racketplainfont [pre-content pre-content?] ...) element?]{Applies
|
|
the @racket['tt] style to @racket[pre-content]. Beware
|
|
that @racket[pre-content] is @racket[decode]d as usual, making
|
|
@racket[racketplainfont] a poor choice for typesetting literal code
|
|
directly but useful for implementing code-formatting functions.
|
|
|
|
@history[#:added "1.6"]}
|
|
|
|
@defproc[(racketvalfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as a value.}
|
|
|
|
@defproc[(racketresultfont [#:decode? decode? boolean? #t] [pre-content pre-content?] ...) element?]{
|
|
Like @racket[racketplainfont], but colored as a REPL result. When
|
|
@racket[decode?] is @racket[#f], then unlike @racket[racketplainfont],
|
|
@racket[racketresultfont] avoids @racket[decode]ing its argument.}
|
|
|
|
@defproc[(racketidfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as an identifier.}
|
|
|
|
@defproc[(racketvarfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as a variable (i.e., an argument or
|
|
sub-form in a procedure being documented).}
|
|
|
|
@defproc[(racketkeywordfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as a syntactic form name.}
|
|
|
|
@defproc[(racketparenfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored like parentheses.}
|
|
|
|
@defproc[(racketoptionalfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as optional.
|
|
@history[#:added "1.36"]
|
|
}
|
|
|
|
@defproc[(racketmetafont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as meta-syntax, such as backquote or
|
|
unquote.}
|
|
|
|
@defproc[(racketcommentfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as a comment.}
|
|
|
|
@defproc[(racketerror [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as error-message text.}
|
|
|
|
@defproc[(racketmodfont [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as module name.}
|
|
|
|
@defproc[(racketoutput [pre-content pre-content?] ...) element?]{Like
|
|
@racket[racketplainfont], but colored as output.}
|
|
|
|
@defproc[(procedure [pre-content pre-content?] ...) element?]{Typesets
|
|
@tech{decode}d @racket[pre-content] as a procedure name in a REPL
|
|
result (e.g., in typewriter font with a @litchar{#<procedure:} prefix
|
|
and @litchar{>} suffix.).}
|
|
|
|
@defform[(var datum)]{Typesets @racket[datum] as an identifier that is
|
|
an argument or sub-form in a procedure being documented. Normally, the
|
|
@racket[defproc] and @racket[defform] arrange for @racket[racket] to
|
|
format such identifiers automatically in the description of the
|
|
procedure, but use @racket[var] if that cannot work for some reason.}
|
|
|
|
@defform[(svar datum)]{Like @racket[var], but for subform non-terminals
|
|
in a form definition.}
|
|
|
|
@deftogether[(
|
|
@defform*[((schememodname datum)
|
|
(schememodname ((unsyntax (racket unsyntax)) expr)))]
|
|
@defform[(schememodlink datum pre-content-expr ...)]
|
|
@defproc[(schemefont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemevalfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemeresultfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemeidfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemevarfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemekeywordfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemeparenfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemeoptionalfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schememetafont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemeerror [pre-content pre-content?] ...) element?]
|
|
@defproc[(schememodfont [pre-content pre-content?] ...) element?]
|
|
@defproc[(schemeoutput [pre-content pre-content?] ...) element?]
|
|
)]{
|
|
|
|
Compatibility aliases. Each @racketidfont{scheme...} name is an alias for the
|
|
corresponding @racketidfont{racket...} binding.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "doc-modules"]{Documenting Modules}
|
|
|
|
@defform/subs[(defmodule maybe-req one-or-multi option ... pre-flow ...)
|
|
([maybe-req code:blank
|
|
(code:line #:require-form content-expr)]
|
|
[one-or-multi module-spec
|
|
(code:line #:multi (module-spec ...+))]
|
|
[module-spec module-path
|
|
content-expr]
|
|
[option (code:line #:module-paths (module-path ...))
|
|
#:no-declare
|
|
(code:line #:use-sources (src-module-path ...))
|
|
(code:line #:link-target? link-target?-expr)
|
|
#:indirect
|
|
#:lang
|
|
#:reader
|
|
(code:line #:packages (pkg-expr ...))])]{
|
|
|
|
Produces a sequence of flow elements (in a @racket[splice])
|
|
to start the documentation for a module---or for multiple modules, if
|
|
the @racket[#:multi] form is used.
|
|
|
|
Each documented module specified as either a @racket[module-path] (in
|
|
the sense of @racket[require]), in which case the module path is
|
|
typeset using @racket[racketmodname], or by a
|
|
@racket[content-expr]. The latter case is triggered by the presence of
|
|
a @racket[#:module-paths] clause, which provides a plain
|
|
@racket[module-path] for each @racket[module-spec], and the plain
|
|
@racket[module-path] is used for cross-referencing.
|
|
|
|
If a @racket[#:require-form] clause is provided and if @racket[#:lang]
|
|
and @racket[#:reader] are not provided, the given expression produces
|
|
content to use instead of @racket[require] for the declaration of the
|
|
module. The @racket[#:require-form] clause is useful to suggest a
|
|
different way of accessing the module instead of through
|
|
@racket[require].
|
|
|
|
Besides generating text, unless @racket[#:no-declare] appears as an
|
|
option, this form expands to a use of @racket[declare-exporting] with
|
|
@racket[module-path]s; the @racket[#:use-sources] clause, if provided,
|
|
is propagated to @racket[declare-exporting]. Consequently,
|
|
@racket[defmodule] should be used at most once in a section without
|
|
@racket[#:no-declare], though it can be shadowed with
|
|
@racket[defmodule]s in sub-sections. Use @racket[#:no-declare] form
|
|
when you want to provide a more specific list of modules (e.g., to
|
|
name both a specific module and one that combines several modules) via
|
|
your own @racket[declare-exporting] declaration
|
|
|
|
When @racket[#:link-target?] is omitted or specified with an expression that
|
|
produces a true value, then the @racket[module-path]s are also
|
|
declared as link targets though a @racket[part-tag-decl] (which means
|
|
that the @racket[defmodule] form must appear before any
|
|
sub-parts). These link targets are referenced via
|
|
@racket[racketmodname], which thus points to the enclosing section,
|
|
rather than the individual @racket[module-path]s.
|
|
|
|
Specifying @racket[#:indirect] normally makes sense only when
|
|
@racket[#:link-target?] is specified with a @racket[#f] value. Specifying
|
|
@racket[#:indirect] makes the module path that is displayed (and that
|
|
normally refers to some other declaration of the module) use
|
|
@racket[racketmodname] with @racket[#:indirect].
|
|
|
|
If @racket[#:lang] is provided as an option, then the module name is
|
|
shown after @hash-lang[] (instead of in a @racket[require] form) to
|
|
indicate that the @racket[module-path]s are suitable for use by either
|
|
@racket[require] or @hash-lang[]. If the module path for
|
|
@racket[require] is syntactically different from the @hash-lang[]
|
|
form, use @racket[#:module-paths] to provide the @racket[require]
|
|
variant (and make each @racket[module-spec] a @racket[content-expr]).
|
|
|
|
If @racket[#:reader] is provided, then the module name is shown after
|
|
@racketmetafont{#reader} to indicate that the module path is intended
|
|
for use as a reader module.
|
|
|
|
By default, the package (if any) that supplies the documented module
|
|
is determined automatically, but a set of providing packages can be
|
|
specified explicitly with @racket[#:packages]. Each @racket[pkg-expr]
|
|
result is passed on to a function like @racket[tt] for
|
|
typesetting. Provide an empty sequence after @racket[#:packages] to
|
|
suppress any package name in the output. Each @racket[pkg-expr]
|
|
expression is duplicated for a @racket[declare-exporting] form,
|
|
unless @racket[#:no-declare] is specified.
|
|
|
|
Each @racket[option] form can appear at most once, and @racket[#:lang]
|
|
and @racket[#:reader] are mutually exclusive.
|
|
|
|
The @tech{decode}d @racket[pre-flow]s introduce the module, but need
|
|
not include all of the module content.}
|
|
|
|
|
|
@defform[#:literals (unquote)
|
|
(declare-exporting module-path/escape ... maybe-pkgs maybe-sources)
|
|
#:grammar ([maybe-pkgs code:blank
|
|
(code:line #:packages (pkg-expr ...))]
|
|
[maybe-sources code:blank
|
|
(code:line #:use-sources (module-path/escape ...))]
|
|
[module-path/escape module-path
|
|
,module-path-expr])]{
|
|
|
|
Associates the @racket[module-path]s to all bindings defined within the
|
|
enclosing section, except as overridden by other
|
|
@racket[declare-exporting] declarations in nested sub-sections. The
|
|
list of @racket[module-path]s before @racket[#:use-sources] is shown, for
|
|
example, when the user hovers the mouse over one of the bindings
|
|
defined within the section. A @racket[unquote]-escaped
|
|
@racket[,module-path-expr] can be used in place of a
|
|
@racket[module-path] to compute the module path dynamically.
|
|
|
|
More significantly, the first @racket[module-path] before
|
|
@racket[#:use-sources] plus the @racket[module-path]s after
|
|
@racket[#:use-sources] determine the binding that is documented by
|
|
each @racket[defform], @racket[defproc], or similar form within the
|
|
section that contains the @racket[declare-exporting] declaration:
|
|
|
|
@itemize[
|
|
|
|
@item{If no @racket[#:use-sources] clause is supplied, then the
|
|
documentation applies to the given name as exported by the first
|
|
@racket[module-path].}
|
|
|
|
@item{If @racket[#:use-sources] @racket[module-path]s are supplied, then
|
|
they are tried in order before the first @racket[module-path]. The
|
|
@racket[module-path] that provides an export with the same
|
|
symbolic name and @racket[free-label-identifier=?] to the given
|
|
name is used as the documented binding. This binding is assumed
|
|
to be the same as the identifier as exported by the first
|
|
@racket[module-path] in the @racket[declare-exporting]
|
|
declaration.}
|
|
|
|
]
|
|
|
|
Use @racket[#:use-sources] sparingly, but it is needed when
|
|
|
|
@itemlist[
|
|
|
|
@item{bindings are documented as originating from a module
|
|
@racket[_M], but the bindings are actually re-exported from
|
|
some module @racket[_P]; and}
|
|
|
|
@item{other documented modules also re-export the bindings from
|
|
@racket[_P], but they are documented as re-exporting from
|
|
@racket[_M].}
|
|
|
|
]
|
|
|
|
For example, the @racket[parameterize] binding of
|
|
@racketmodname[mzscheme] is documented as re-exported from
|
|
@racketmodname[racket/base], but @racket[parameterize] happens to be
|
|
implemented in a private module and re-exported by both
|
|
@racketmodname[racket/base] and @racketmodname[mzscheme]. Importing
|
|
@racket[parameterize] from @racketmodname[mzscheme] does not go
|
|
through @racketmodname[racket/base], so a search for documentation on
|
|
@racket[parameterize] in @racketmodname[mzscheme] would not
|
|
automatically connect to the documentation of
|
|
@racketmodname[racket/base]. To make the connection, the documentation
|
|
of @racketmodname[racket/base] declares the private module to be a
|
|
source through @racket[#:use-sources], so that any re-export of
|
|
@racket[parameterize] from the private module connects to the
|
|
documentation for @racketmodname[racket/base] (unless a re-export has
|
|
its own documentation, which would override the automatic connection
|
|
when searching for documentation).
|
|
|
|
The initial @racket[module-path]s sequence can be empty if
|
|
@racket[module-path]s are given with @racket[#:use-sources]. In that
|
|
case, the rendered documentation never reports an exporting module for
|
|
identifiers that are documented within the section, but the
|
|
@racket[module-path]s in @racket[#:use-sources] provide a binding context
|
|
for connecting (via hyperlinks) definitions and uses of identifiers.
|
|
|
|
Supply @racket[#:packages] to specify the package that provides the
|
|
declared modules, which is otherwise inferred automatically from the
|
|
first @racket[module-path]. The package names are used, for example,
|
|
by @racket[history].
|
|
|
|
The @racket[declare-exporting] form should be used no more than once
|
|
per section, since the declaration applies to the entire section,
|
|
although overriding @racket[declare-exporting] forms can appear in
|
|
sub-sections.
|
|
|
|
@history[#:changed "1.1" @elem{Added @racket[#:packages] clause.}
|
|
#:changed "1.17" @elem{Added support for @racket[,module-path-expr].}]}
|
|
|
|
@defform*[[(defmodulelang one-or-multi maybe-sources option ... pre-flow ...)
|
|
(defmodulelang one-or-multi #:module-path module-path
|
|
option ... pre-flow ...)]]{
|
|
Equivalent to @racket[defmodule] with @racket[#:lang]. The
|
|
@racket[#:module-path module-path] is provided, it is converted to
|
|
@racket[#:module-paths (module-path)].}
|
|
|
|
@defform[(defmodulereader one-or-multi option ... pre-flow ...)]{
|
|
Equivalent to @racket[defmodule] with @racket[#:reader].}
|
|
|
|
|
|
@deftogether[(
|
|
@defform[(defmodule* maybe-req (module-spec ...+) option ... pre-flow ...)]
|
|
@defform[(defmodulelang* (module-spec ...+) option ... pre-flow ...)]
|
|
@defform[(defmodulereader* (module-spec ...+) option ... pre-flow ...)]
|
|
)]{
|
|
Equivalent to @racket[defmodule] variants with @racket[#:multi].}
|
|
|
|
@deftogether[(
|
|
@defform[(defmodule*/no-declare maybe-req (module-spec ...) option ... pre-flow ...)]
|
|
@defform[(defmodulelang*/no-declare (module-spec ...) option ... pre-flow ...)]
|
|
@defform[(defmodulereader*/no-declare (module-spec ...) option ... pre-flow ...)]
|
|
)]{
|
|
Equivalent to @racket[defmodule] variants @racket[#:no-declare].}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "doc-forms"]{Documenting Forms, Functions, Structure Types, and Values}
|
|
|
|
@defform/subs[(defproc options prototype
|
|
result-contract-expr-datum
|
|
maybe-value
|
|
pre-flow ...)
|
|
([prototype (id arg-spec ...)
|
|
(prototype arg-spec ...)]
|
|
[arg-spec (arg-id contract-expr-datum)
|
|
(arg-id contract-expr-datum default-expr)
|
|
(keyword arg-id contract-expr-datum)
|
|
(keyword arg-id contract-expr-datum default-expr)
|
|
ellipses
|
|
ellipses+]
|
|
[options (code:line maybe-kind maybe-link maybe-id)]
|
|
[maybe-kind code:blank
|
|
(code:line #:kind kind-content-expr)]
|
|
[maybe-link code:blank
|
|
(code:line #:link-target? link-target?-expr)]
|
|
[maybe-id code:blank
|
|
(code:line #:id [src-id dest-id-expr])]
|
|
[maybe-value code:blank
|
|
(code:line #:value value-expr-datum)]
|
|
[ellipses @#,lit-ellipses]
|
|
[ellipses+ @#,lit-ellipses+])]{
|
|
|
|
Produces a sequence of flow elements (encapsulated in a
|
|
@racket[splice]) to document a procedure named @racket[id]. Nesting
|
|
@racket[prototype]s corresponds to a curried function, as in
|
|
@racket[define]. Unless @racket[link-target?-expr] is specified
|
|
and produces @racket[#f], the @racket[id] is indexed, and it also registered so
|
|
that @racket[racket]-typeset uses of the identifier (with the same
|
|
for-label binding) are hyperlinked to this documentation.
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defproc[(make-sandwich [ingredients (listof ingredient?)])
|
|
sandwich?]{
|
|
Returns a sandwich given the right ingredients.
|
|
}
|
|
|
|
@defproc[#:kind "sandwich-maker"
|
|
(make-reuben [ingredient sauerkraut?] ...
|
|
[#:veggie? veggie? any/c #f])
|
|
sandwich?]{
|
|
Produces a reuben given some number of @racket[ingredient]s.
|
|
|
|
If @racket[veggie?] is @racket[#f], produces a standard
|
|
reuben with corned beef. Otherwise, produces a vegetable
|
|
reuben.
|
|
}
|
|
}|
|
|
|
|
@doc-render-examples[
|
|
@defproc[#:link-target? #f
|
|
(make-sandwich [ingredients (listof ingredient?)])
|
|
sandwich?]{
|
|
Returns a sandwich given the right ingredients.
|
|
}
|
|
|
|
@defproc[#:kind "sandwich-maker"
|
|
#:link-target? #f
|
|
(make-reuben [ingredient sauerkraut?] ...
|
|
[#:veggie? veggie? any/c #f])
|
|
sandwich?]{
|
|
Produces a reuben given some number of @racket[ingredient]s.
|
|
|
|
If @racket[veggie?] is @racket[#f], produces a standard
|
|
reuben with corned beef. Otherwise, produces a vegetable
|
|
reuben.
|
|
}]
|
|
|
|
When @racket[id] is indexed and registered,
|
|
a @racket[defmodule] or @racket[declare-exporting] form (or one of the
|
|
variants) in an enclosing section determines the @racket[id] binding
|
|
that is being defined. The @racket[id] should also have a for-label
|
|
binding (as introduced by @racket[(require (for-label ....))]) that
|
|
matches the definition binding; otherwise, the defined @racket[id]
|
|
will not typeset correctly within the definition.
|
|
|
|
Each @racket[arg-spec] must have one of the following forms:
|
|
|
|
@specsubform[(arg-id contract-expr-datum)]{
|
|
An argument whose contract is specified by
|
|
@racket[contract-expr-datum] which is typeset via
|
|
@racket[racketblock0].}
|
|
|
|
@specsubform[(arg-id contract-expr-datum default-expr)]{
|
|
Like the previous case, but with a default value. All arguments
|
|
with a default value must be grouped together, but they can be
|
|
in the middle of required arguments.}
|
|
|
|
@specsubform[(keyword arg-id contract-expr-datum)]{
|
|
Like the first case, but for a keyword-based argument.}
|
|
|
|
@specsubform[(keyword arg-id contract-expr-datum default-expr)]{
|
|
Like the previous case, but with a default
|
|
value.}
|
|
|
|
@specsubform[@#,lit-ellipses]{Any number of the preceding argument. This
|
|
form is normally used at the end, but keyword-based arguments
|
|
can sensibly appear afterward. See also the documentation for
|
|
@racket[append] for a use of @lit-ellipses before the last
|
|
argument.}
|
|
|
|
@specsubform[@#,lit-ellipses+]{One or more of the preceding argument
|
|
(normally at the end, like @lit-ellipses).}
|
|
|
|
The @racket[result-contract-expr-datum] is typeset via
|
|
@racket[racketblock0], and it represents a contract on the procedure's
|
|
result.
|
|
|
|
The @tech{decode}d @racket[pre-flow] documents the procedure. In this
|
|
description, references to @svar[arg-id]s using @racket[racket],
|
|
@racket[racketblock], @|etc| are typeset as procedure arguments.
|
|
|
|
The typesetting of all information before the @racket[pre-flow]s
|
|
ignores the source layout, except that the local formatting is
|
|
preserved for contracts and default-values expressions. The information
|
|
is formatted to fit (if possible) in the number of characters specified
|
|
by the @racket[current-display-width] parameter.
|
|
|
|
An optional @racket[#:kind] specification chooses the decorative
|
|
label, which defaults to @racket["procedure"]. A @racket[#f]
|
|
result for @racket[kind-content-expr] uses the default, otherwise
|
|
@racket[kind-content-expr] should produce content in the sense of @racket[content?]. An alternate
|
|
label should be all lowercase.
|
|
|
|
If @racket[#:id [src-id dest-id-expr]] is supplied, then
|
|
@racket[src-id] is the identifier as it appears in the
|
|
@racket[prototype] (to be replaced by a defining instance), and
|
|
@racket[dest-id-expr] produces the identifier to be documented in
|
|
place of @racket[src-id]. This split between @racket[src-id] and
|
|
@racket[dest-id-expr] roles is useful for functional abstraction of
|
|
@racket[defproc].
|
|
|
|
If @racket[#:value value-expr-datum] is given, @racket[value-expr-datum]
|
|
is typeset using @racket[racketblock0] and included in the documentation.
|
|
As a service to readers, please use @racket[#:value] to document only
|
|
simple, short functions.
|
|
}
|
|
|
|
@defform[(defproc* options
|
|
([prototype
|
|
result-contract-expr-datum
|
|
maybe-value] ...)
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defproc], but for multiple cases with the same
|
|
@racket[id]. Multiple distinct @racket[id]s can also be defined by a
|
|
single @racket[defproc*], for the case that it's best to document a
|
|
related group of procedures at once (but multiple @racket[defproc]s
|
|
grouped by @racket[deftogether] also works for that case).
|
|
|
|
When an @racket[id] has multiple calling cases, either they must be
|
|
defined with a single @racket[defproc*], so that a single definition
|
|
point exists for the @racket[id], or else all but one definition
|
|
should use @racket[#:link-target? #f].
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defproc*[([(make-pb&j) sandwich?]
|
|
[(make-pb&j [jelly jelly?]) sandwich?])]{
|
|
Returns a peanut butter and jelly sandwich. If @racket[jelly]
|
|
is provided, then it is used instead of the standard (grape)
|
|
jelly.
|
|
}
|
|
}|
|
|
|
|
@doc-render-examples[
|
|
@defproc*[#:link-target? #f
|
|
([(make-pb&j) sandwich?]
|
|
[(make-pb&j [jelly jelly?]) sandwich?])]{
|
|
Returns a peanut butter and jelly sandwich. If @racket[jelly]
|
|
is provided, then it is used instead of the standard (grape)
|
|
jelly.
|
|
}]
|
|
}
|
|
|
|
|
|
@defform/subs[(defform options form-datum
|
|
maybe-grammar maybe-contracts
|
|
pre-flow ...)
|
|
([options (code:line maybe-kind maybe-link maybe-id maybe-literals)]
|
|
[maybe-kind code:blank
|
|
(code:line #:kind kind-content-expr)]
|
|
[maybe-link code:blank
|
|
(code:line #:link-target? link-target?-expr)]
|
|
[maybe-id code:blank
|
|
(code:line #:id id)
|
|
(code:line #:id [id id-expr])]
|
|
[maybe-literals code:blank
|
|
(code:line #:literals (literal-id ...))]
|
|
[maybe-grammar code:blank
|
|
(code:line #:grammar ([nonterm-id clause-datum ...+] ...))]
|
|
[maybe-contracts code:blank
|
|
(code:line #:contracts ([subform-datum contract-expr-datum]
|
|
...))])]{
|
|
|
|
Produces a sequence of flow elements (encapsulated in a
|
|
@racket[splice]) to document a syntatic form named by @racket[id] (or the
|
|
result of @racket[id-expr]) whose syntax is described by
|
|
@racket[form-datum]. If no @racket[#:id] is used to specify
|
|
@racket[id], then @racket[form-datum] must have the form @racket[(id
|
|
. _datum)].
|
|
|
|
If @racket[#:kind kind-content-expr] is supplied, it is used in the
|
|
same way as for @racket[defproc], but the default kind is
|
|
@racket["syntax"].
|
|
|
|
If @racket[#:id [id id-expr]] is supplied, then @racket[id] is the
|
|
identifier as it appears in the @racket[form-datum] (to be replaced by
|
|
a defining instance), and @racket[id-expr] produces the identifier to
|
|
be documented. This split between @racket[id] and @racket[id-expr]
|
|
roles is useful for functional abstraction of @racket[defform].
|
|
|
|
Unless @racket[link-target?-expr] is specified
|
|
and produces @racket[#f],
|
|
the @racket[id] (or result of @racket[id-expr]) is indexed, and it is
|
|
also registered so that @racket[racket]-typeset uses of the identifier
|
|
(with the same for-label binding) are hyperlinked to this
|
|
documentation. The @racket[defmodule] or @racket[declare-exporting]
|
|
requirements, as well as the binding requirements for @racket[id] (or
|
|
result of @racket[id-expr]), are the same as for @racket[defproc].
|
|
|
|
The @tech{decode}d @racket[pre-flow] documents the form. In this
|
|
description, a reference to any identifier in @racket[form-datum] via
|
|
@racket[racket], @racket[racketblock], @|etc| is typeset as a sub-form
|
|
non-terminal. If @racket[#:literals] clause is provided, however,
|
|
instances of the @racket[literal-id]s are typeset normally (i.e., as
|
|
determined by the enclosing context).
|
|
|
|
If a @racket[#:grammar] clause is provided, it includes an auxiliary
|
|
grammar of non-terminals shown with the @racket[id] form. Each
|
|
@racket[nonterm-id] is specified as being any of the corresponding
|
|
@racket[clause-datum]s.
|
|
|
|
If a @racket[#:contracts] clause is provided, each
|
|
@racket[subform-datum] (typically an identifier that serves as a
|
|
meta-variable in @racket[form-datum] or @racket[clause-datum]) is
|
|
shown as producing a value that must satisfy the contract described by
|
|
@racket[contract-expr-datum]. Use @racket[#:contracts] only to
|
|
specify constraints on a @emph{value} produced by an expression; for
|
|
constraints on the @emph{syntax} of a @racket[subform-datum], use
|
|
grammar notation instead, possibly through an auxiliary grammar
|
|
specified with @racket[#:grammar].
|
|
|
|
The typesetting of @racket[form-datum], @racket[clause-datum],
|
|
@racket[subform-datum], and @racket[contract-expr-datum] preserves the
|
|
source layout, like @racket[racketblock].
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defform[(sandwich-promise sandwich-expr)
|
|
#:contracts ([sandwich-expr sandwich?])]{
|
|
Returns a promise to construct a sandwich. When forced, the promise
|
|
will produce the result of @racket[sandwich-expr].
|
|
}
|
|
|
|
@defform[#:literals (sandwich mixins)
|
|
(sandwich-promise* [sandwich sandwich-expr]
|
|
[mixins ingredient-expr ...])
|
|
#:contracts ([sandwich-expr sandwich?]
|
|
[ingredient-expr ingredient?])]{
|
|
Returns a promise to construct a sandwich. When forced, the promise
|
|
will produce the result of @racket[sandwich-expr]. Each result of
|
|
the @racket[ingredient-expr]s will be mixed into the resulting
|
|
sandwich.
|
|
}
|
|
|
|
@defform[(sandwich-factory maybe-name factory-component ...)
|
|
#:grammar
|
|
[(maybe-name (code:line)
|
|
name)
|
|
(factory-component (code:line #:protein protein-expr)
|
|
[vegetable vegetable-expr])]]{
|
|
Constructs a sandwich factory. If @racket[maybe-name] is provided,
|
|
the factory will be named. Each of the @racket[factory-component]
|
|
clauses adds an additional ingredient to the sandwich pipeline.
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defform[#:link-target? #f
|
|
(sandwich-promise sandwich-expr)
|
|
#:contracts ([sandwich-expr sandwich?])]{
|
|
Returns a promise to construct a sandwich. When forced, the promise
|
|
will produce the result of @racket[sandwich-expr].
|
|
}
|
|
|
|
@defform[#:link-target? #f
|
|
#:literals (sandwich mixins)
|
|
(sandwich-promise* [sandwich sandwich-expr]
|
|
[mixins ingredient-expr ...])
|
|
#:contracts ([sandwich-expr sandwich?]
|
|
[ingredient-expr ingredient?])]{
|
|
Returns a promise to construct a sandwich. When forced, the promise
|
|
will produce the result of @racket[sandwich-expr]. Each result of
|
|
the @racket[ingredient-expr]s will be mixed into the resulting
|
|
sandwich.
|
|
}
|
|
|
|
@defform[#:link-target? #f
|
|
(sandwich-factory maybe-name factory-component ...)
|
|
#:grammar
|
|
[(maybe-name (code:line)
|
|
name)
|
|
(factory-component (code:line #:protein protein-expr)
|
|
[vegetable vegetable-expr])]]{
|
|
Constructs a sandwich factory. If @racket[maybe-name] is provided,
|
|
the factory will be named. Each of the @racket[factory-component]
|
|
clauses adds an additional ingredient to the sandwich pipeline.
|
|
}]
|
|
}
|
|
|
|
@defform[(defform* options [form-datum ...+]
|
|
maybe-grammar maybe-contracts
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defform], but for multiple forms using the same
|
|
@racket[_id].
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defform*[((call-with-current-sandwich expr)
|
|
(call-with-current-sandwich expr sandwich-handler-expr))]{
|
|
Runs @racket[expr] and passes it the value of the current
|
|
sandwich. If @racket[sandwich-handler-expr] is provided, its result
|
|
is invoked when the current sandwich is eaten.
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defform*[#:link-target? #f
|
|
((call-with-current-sandwich expr)
|
|
(call-with-current-sandwich expr sandwich-handler-expr))]{
|
|
Runs @racket[expr] and passes it the value of the current
|
|
sandwich. If @racket[sandwich-handler-expr] is provided, its result
|
|
is invoked when the current sandwich is eaten.
|
|
}]
|
|
}
|
|
|
|
|
|
@defform[(defform/none maybe-kind maybe-literal form-datum
|
|
maybe-grammar maybe-contracts
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defform] with @racket[#:link-target? #f].}
|
|
|
|
|
|
@defform[(defidform maybe-kind maybe-link id pre-flow ...)]{
|
|
|
|
Like @racket[defform], but with a plain @racket[id] as the form.}
|
|
|
|
|
|
@defform*[[(defidform/inline id)
|
|
(defidform/inline (@#,racket[unsyntax] id-expr))]]{
|
|
|
|
Like @racket[defidform], but @racket[id] (or the result of
|
|
@racket[id-expr], analogous to @racket[defform]) is typeset as an
|
|
inline element. Use this form sparingly, because the typeset form does
|
|
not stand out to the reader as a specification of @racket[id].}
|
|
|
|
@deftogether[(
|
|
@defform[(defsubform options form-datum
|
|
maybe-grammar maybe-contracts
|
|
pre-flow ...)]
|
|
@defform[(defsubform* options [form-datum ...+]
|
|
maybe-grammar maybe-contracts
|
|
pre-flow ...)]
|
|
)]{
|
|
|
|
Like @racket[defform] and @racket[defform*], but with
|
|
indenting on the left for both the specification and the
|
|
@racket[pre-flow]s.}
|
|
|
|
|
|
@defform[(specform maybe-literals datum maybe-grammar maybe-contracts
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defform] with @racket[#:link-target? #f], but with
|
|
indenting on the left for both the specification and the
|
|
@racket[pre-flow]s.}
|
|
|
|
|
|
@defform[(specsubform maybe-literals datum maybe-grammar maybe-contracts
|
|
pre-flow ...)]{
|
|
|
|
Similar to @racket[defform] with @racket[#:link-target? #f],
|
|
but without the initial identifier as an implicit literal,
|
|
and the table and flow are typeset indented. This form is
|
|
intended for use when refining the syntax of a non-terminal used in a
|
|
@racket[defform] or other @racket[specsubform]. For example, it is
|
|
used in the documentation for @racket[defproc] in the itemization of
|
|
possible shapes for @svar[arg-spec].
|
|
|
|
The @racket[pre-flow]s list is parsed as a flow that documents the
|
|
procedure. In this description, a reference to any identifier in
|
|
@racket[datum] is typeset as a sub-form non-terminal.}
|
|
|
|
|
|
@defform[(specspecsubform maybe-literals datum maybe-grammar maybe-contracts
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[specsubform], but indented an extra level. Since using
|
|
@racket[specsubform] within the body of @racket[specsubform] already
|
|
nests indentation, @racket[specspecsubform] is for extra indentation
|
|
without nesting a description.}
|
|
|
|
|
|
@deftogether[[
|
|
@defform[(defform/subs options form-datum
|
|
([nonterm-id clause-datum ...+] ...)
|
|
maybe-contracts
|
|
pre-flow ...)]
|
|
@defform[(defform*/subs options [form-datum ...+]
|
|
([nonterm-id clause-datum ...+] ...)
|
|
maybe-contracts
|
|
pre-flow ...)]
|
|
@defform[(specform/subs maybe-literals datum
|
|
([nonterm-id clause-datum ...+] ...)
|
|
maybe-contracts
|
|
pre-flow ...)]
|
|
@defform[(specsubform/subs maybe-literals datum
|
|
([nonterm-id clause-datum ...+] ...)
|
|
maybe-contracts
|
|
pre-flow ...)]
|
|
@defform[(specspecsubform/subs maybe-literals datum
|
|
([nonterm-id clause-datum ...+] ...)
|
|
maybe-contracts
|
|
pre-flow ...)]]]{
|
|
|
|
Like @racket[defform], @racket[defform*], @racket[specform],
|
|
@racket[specsubform], and @racket[specspecsubform], respectively, but
|
|
the auxiliary grammar is mandatory and the @racket[#:grammar] keyword
|
|
is omitted.
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defform/subs[(sandwich-factory maybe-name factory-component ...)
|
|
[(maybe-name (code:line)
|
|
name)
|
|
(factory-component (code:line #:protein protein-expr)
|
|
[vegetable vegetable-expr])]]{
|
|
Constructs a sandwich factory. If @racket[maybe-name] is provided,
|
|
the factory will be named. Each of the @racket[factory-component]
|
|
clauses adds an additional ingredient to the sandwich pipeline.
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defform/subs[#:link-target? #f
|
|
(sandwich-factory maybe-name factory-component ...)
|
|
[(maybe-name (code:line)
|
|
name)
|
|
(factory-component (code:line #:protein protein-expr)
|
|
[vegetable vegetable-expr])]]{
|
|
Constructs a sandwich factory. If @racket[maybe-name] is provided,
|
|
the factory will be named. Each of the @racket[factory-component]
|
|
clauses adds an additional ingredient to the sandwich pipeline.
|
|
}]
|
|
}
|
|
|
|
|
|
@defform[(defparam maybe-link id arg-id
|
|
contract-expr-datum
|
|
maybe-value
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defproc], but for a parameter. The
|
|
@racket[contract-expr-datum] serves as both the result contract on the
|
|
parameter and the contract on values supplied for the parameter. The
|
|
@racket[arg-id] refers to the parameter argument in the latter case.
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defparam[current-sandwich sandwich sandwich?
|
|
#:value empty-sandwich]{
|
|
A parameter that defines the current sandwich for operations that
|
|
involve eating a sandwich. Default value is the empty sandwich.
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defparam[#:link-target? #f
|
|
current-sandwich sandwich sandwich? #:value empty-sandwich]{
|
|
A parameter that defines the current sandwich for operations that
|
|
involve eating a sandwich. Default value is the empty sandwich.
|
|
}]
|
|
}
|
|
|
|
|
|
@defform[(defparam* maybe-link id arg-id
|
|
in-contract-expr-datum out-contract-expr-datum
|
|
maybe-value
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defparam], but with separate contracts for when the parameter is being
|
|
set versus when it is being retrieved (for the case that a parameter guard
|
|
coerces values matching a more flexible contract to a more restrictive one;
|
|
@racket[current-directory] is an example).}
|
|
|
|
|
|
@defform[(defboolparam maybe-link id arg-id
|
|
maybe-value
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defparam], but the contract on a parameter argument is
|
|
@racket[any/c], and the contract on the parameter result is
|
|
@racket[boolean?].}
|
|
|
|
|
|
@defform/subs[(defthing options id contract-expr-datum maybe-value
|
|
pre-flow ...)
|
|
([options (code:line maybe-kind maybe-link maybe-id)]
|
|
[maybe-kind code:blank
|
|
(code:line #:kind kind-content-expr)]
|
|
[maybe-link code:blank
|
|
(code:line #:link-target? link-target?-expr)]
|
|
[maybe-id code:blank
|
|
(code:line #:id id-expr)]
|
|
[maybe-value code:blank
|
|
(code:line #:value value-expr-datum)])]{
|
|
|
|
Like @racket[defproc], but for a non-procedure binding.
|
|
|
|
If @racket[#:kind kind-content-expr] is supplied,
|
|
it is used in the same way as for
|
|
@racket[defproc], but the default kind is @racket["value"].
|
|
|
|
If @racket[#:id id-expr] is supplied, then the result of
|
|
@racket[id-expr] is used in place of @racket[id].
|
|
|
|
If @racket[#:value value-expr-datum] is given, @racket[value-expr-datum]
|
|
is typeset using @racket[racketblock0] and included in the documentation.
|
|
Wide values are put on a separate line.
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defthing[moldy-sandwich sandwich?]{
|
|
Don't eat this. Provided for backwards compatibility.
|
|
}
|
|
|
|
@defthing[empty-sandwich sandwich? #:value (make-sandwich empty)]{
|
|
The empty sandwich.
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defthing[#:link-target? #f
|
|
moldy-sandwich sandwich?]{
|
|
Don't eat this. Provided for backwards compatibility.
|
|
}
|
|
@defthing[#:link-target? #f
|
|
empty-sandwich sandwich? #:value (make-sandwich empty)]{
|
|
The empty sandwich.
|
|
}]
|
|
}
|
|
|
|
|
|
@deftogether[(
|
|
@defform[ (defstruct* maybe-link struct-name ([field-name contract-expr-datum] ...)
|
|
maybe-mutable maybe-non-opaque maybe-constructor
|
|
pre-flow ...)]
|
|
@defform/subs[ (defstruct maybe-link struct-name ([field-name contract-expr-datum] ...)
|
|
maybe-mutable maybe-non-opaque maybe-constructor
|
|
pre-flow ...)
|
|
([maybe-link code:blank
|
|
(code:line #:link-target? link-target?-expr)]
|
|
[struct-name id
|
|
(id super-id)]
|
|
[maybe-mutable code:blank
|
|
#:mutable]
|
|
[maybe-non-opaque code:blank
|
|
#:prefab
|
|
#:transparent
|
|
(code:line #:inspector #f)]
|
|
[maybe-constructor code:blank
|
|
(code:line #:constructor-name constructor-id)
|
|
(code:line #:extra-constructor-name constructor-id)
|
|
(code:line #:omit-constructor)])]
|
|
)]{
|
|
|
|
Similar to @racket[defform] or @racket[defproc], but for a structure
|
|
definition. The @racket[defstruct*] form corresponds to @racket[struct],
|
|
while @racket[defstruct] corresponds to @racket[define-struct].
|
|
|
|
Examples:
|
|
|
|
An example using @racket[defstruct]:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defstruct[sandwich ([protein ingredient?] [sauce ingredient?])]{
|
|
A structure type for sandwiches. Sandwiches are a pan-human foodstuff
|
|
composed of a partially-enclosing bread material and various
|
|
ingredients.
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defstruct[#:link-target? #f
|
|
sandwich ([protein ingredient?] [sauce ingredient?])]{
|
|
A structure type for sandwiches. Sandwiches are a pan-human foodstuff
|
|
composed of a partially-enclosing bread material and various
|
|
ingredients.
|
|
}]
|
|
|
|
Additionally, an example using @racket[defstruct*]:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defstruct*[burrito ([salsa ingredient?] [tortilla ingredient?])]{
|
|
A structure type for burritos. Burritos are a pan-human foodstuff
|
|
composed of a @emph{fully}-encolosed bread material and various
|
|
ingredients.
|
|
}
|
|
}|
|
|
}
|
|
@doc-render-examples[
|
|
@defstruct*[#:link-target? #f
|
|
burrito ([salsa ingredient?] [tortilla ingredient?])]{
|
|
A structure type for burritos. Burritos are a pan-human foodstuff
|
|
composed of a @emph{fully}-encolosed bread material and various
|
|
ingredients.
|
|
}]
|
|
|
|
|
|
@defform[(deftogether [def-expr ...] pre-flow ...)]{
|
|
|
|
Combines the definitions created by the @racket[def-expr]s into a
|
|
single definition box. Each @racket[def-expr] should produce a
|
|
definition point via @racket[defproc], @racket[defform], etc. Each
|
|
@racket[def-expr] should have an empty @racket[pre-flow]; the
|
|
@tech{decode}d @racket[pre-flow] sequence for the @racket[deftogether]
|
|
form documents the collected bindings.
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@deftogether[(@defthing[test-sandwich-1 sandwich?]
|
|
@defthing[test-sandwich-2 sandwich?])]{
|
|
Two high-quality sandwiches. These are provided for convenience
|
|
in writing test cases
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@deftogether[(@defthing[#:link-target? #f test-sandwich-1 sandwich?]
|
|
@defthing[#:link-target? #f test-sandwich-2 sandwich?])]{
|
|
Two high-quality sandwiches. These are provided for convenience
|
|
in writing test cases
|
|
}
|
|
]
|
|
}
|
|
|
|
|
|
@defform/subs[(racketgrammar maybe-literals id clause-datum ...+)
|
|
([maybe-literals code:blank
|
|
(code:line #:literals (literal-id ...))])]{
|
|
|
|
Creates a table to define the grammar of @racket[id]. Each identifier
|
|
mentioned in a @racket[clause-datum] is typeset as a non-terminal,
|
|
except for the identifiers listed as @racket[literal-id]s, which are
|
|
typeset as with @racket[racket].}
|
|
|
|
|
|
@defform[(racketgrammar* maybe-literals [id clause-datum ...+] ...)]{
|
|
|
|
Like @racket[racketgrammar], but for typesetting multiple productions
|
|
at once, aligned around the @litchar{=} and @litchar{|}.}
|
|
|
|
@defproc[(defidentifier [id identifier?]
|
|
[#:form? form? boolean? #f]
|
|
[#:index? index? boolean? #t]
|
|
[#:show-libs? show-libs? boolean? #t])
|
|
element?]{
|
|
|
|
Typesets @racket[id] as a Racket identifier, and also establishes the
|
|
identifier as the definition of a binding in the same way as
|
|
@racket[defproc], @racket[defform], etc. As always, the library that
|
|
provides the identifier must be declared via @racket[defmodule] or
|
|
@racket[declare-exporting] for an enclosing section.
|
|
|
|
If @racket[form?] is a true value, then the identifier is documented
|
|
as a syntactic form, so that uses of the identifier (normally
|
|
including @racket[id] itself) are typeset as a syntactic form.
|
|
|
|
If @racket[index?] is a true value, then the identifier is registered
|
|
in the index.
|
|
|
|
If @racket[show-libs?] is a true value, then the identifier's defining
|
|
module may be exposed in the typeset form (e.g., when viewing HTML and
|
|
the mouse hovers over the identifier).}
|
|
|
|
@deftogether[(
|
|
@defform[(schemegrammar maybe-literals id clause-datum ...+)]
|
|
@defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)]
|
|
)]{
|
|
|
|
Compatibility aliases for @racket[racketgrammar] and @racket[racketgrammar*].}
|
|
|
|
@defparam[current-display-width w exact-nonnegative-integer?]{
|
|
|
|
Specifies the target maximum width in characters for the output of
|
|
@racket[defproc] and @racket[defstruct].}
|
|
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "doc-classes"]{Documenting Classes and Interfaces}
|
|
|
|
@defform/subs[(defclass maybe-link id super (intf-id ...) pre-flow ...)
|
|
([maybe-link code:blank
|
|
(code:line #:link-target? link-target?-expr)]
|
|
[super super-id
|
|
(mixin-id super)])]{
|
|
|
|
Creates documentation for a class @racket[id] that is a subclass of
|
|
@racket[super] and implements each interface @racket[intf-id]. Each
|
|
identifier in @racket[super] (except @racket[object%]) and
|
|
@racket[intf-id] must be documented somewhere via @racket[defclass] or
|
|
@racket[definterface].
|
|
|
|
The decoding of the @racket[pre-flow] sequence should start with
|
|
general documentation about the class, followed by constructor
|
|
definition (see @racket[defconstructor]), and then field and method
|
|
definitions (see @racket[defmethod]). In rendered form, the
|
|
constructor and method specification are indented to visually group
|
|
them under the class definition.}
|
|
|
|
@defform[(defclass/title maybe-link id super (intf-id ...) pre-flow ...)]{
|
|
|
|
Like @racket[defclass], also includes a @racket[title] declaration
|
|
with the style @racket['hidden]. In addition, the constructor and
|
|
methods are not left-indented.
|
|
|
|
This form is normally used to create a section to be rendered on its
|
|
own HTML. The @racket['hidden] style is used because the definition
|
|
box serves as a title.}
|
|
|
|
@defform[(definterface id (intf-id ...) pre-flow ...)]{
|
|
|
|
Like @racket[defclass], but for an interfaces. Naturally,
|
|
@racket[pre-flow] should not generate a constructor declaration.}
|
|
|
|
@defform[(definterface/title id (intf-id ...) pre-flow ...)]{
|
|
|
|
Like @racket[definterface], but for single-page rendering as in
|
|
@racket[defclass/title].}
|
|
|
|
@defform[(defmixin id (domain-id ...) (range-id ...) pre-flow ...)]{
|
|
|
|
Like @racket[defclass], but for a mixin. Any number of
|
|
@racket[domain-id] classes and interfaces are specified for the
|
|
mixin's input requires, and any number of result classes and (more
|
|
likely) interfaces are specified for the @racket[range-id]. The
|
|
@racket[domain-id]s supply inherited methods.}
|
|
|
|
@defform[(defmixin/title id (domain-id ...) (range-id ...) pre-flow ...)]{
|
|
|
|
Like @racket[defmixin], but for single-page rendering as in
|
|
@racket[defclass/title].}
|
|
|
|
@defform/subs[(defconstructor (arg-spec ...) pre-flow ...)
|
|
([arg-spec (arg-id contract-expr-datum)
|
|
(arg-id contract-expr-datum default-expr)])]{
|
|
|
|
Like @racket[defproc], but for a constructor declaration in the body
|
|
of @racket[defclass], so no return contract is specified. Also, the
|
|
@racket[new]-style keyword for each @racket[arg-spec] is implicit from
|
|
the @racket[arg-id].}
|
|
|
|
@defform[(defconstructor/make (arg-spec ...) pre-flow ...)]{
|
|
|
|
Like @racket[defconstructor], but specifying by-position
|
|
initialization arguments (for use with @racket[make-object]) instead
|
|
of by-name arguments (for use with @racket[new]).}
|
|
|
|
@defform[(defconstructor*/make [(arg-spec ...) ...] pre-flow ...)]{
|
|
|
|
Like @racket[defconstructor/make], but with multiple constructor
|
|
patterns analogous @racket[defproc*].}
|
|
|
|
@defform[(defconstructor/auto-super [(arg-spec ...) ...] pre-flow ...)]{
|
|
|
|
Like @racket[defconstructor], but the constructor is
|
|
annotated to indicate that additional initialization arguments are
|
|
accepted and propagated to the superclass.}
|
|
|
|
@defform/subs[#:literals (override override-final public-final
|
|
augment augment-final pubment extend extend-final)
|
|
(defmethod maybe-mode maybe-link (id arg-spec ...)
|
|
result-contract-expr-datum
|
|
pre-flow ...)
|
|
([maybe-link code:blank
|
|
(code:line #:link-target? link-target?-expr)]
|
|
[maybe-mode code:blank
|
|
(code:line #:mode public)
|
|
(code:line #:mode public-final)
|
|
(code:line #:mode override)
|
|
(code:line #:mode override-final)
|
|
(code:line #:mode augment)
|
|
(code:line #:mode augment-final)
|
|
(code:line #:mode extend)
|
|
(code:line #:mode extend-final)
|
|
(code:line #:mode pubment)])]{
|
|
|
|
Like @racket[defproc], but for a method within a @racket[defclass] or
|
|
@racket[definterface] body.
|
|
|
|
The @racket[maybe-mode] specifies whether the method overrides a
|
|
method from a superclass, and so on. (For these purposes, use
|
|
@racket[#:mode override] when refining a method of an implemented
|
|
interface.) The @racket[extend] mode is like @racket[override], but
|
|
the description of the method should describe only extensions to the
|
|
superclass implementation. When @racket[maybe-mode] is not supplied,
|
|
it defaults to @racket[public].
|
|
|
|
@history[#:changed "1.35" @elem{Added a check against invalid @racket[maybe-mode].}]}
|
|
|
|
@defform[(defmethod* maybe-mode maybe-link
|
|
([(id arg-spec ...)
|
|
result-contract-expr-datum] ...)
|
|
pre-flow ...)]{
|
|
|
|
Like @racket[defproc*], but for a method within a @racket[defclass] or
|
|
@racket[definterface] body. The @racket[maybe-mode] specification is as in
|
|
@racket[defmethod].}
|
|
|
|
|
|
@defform[(method class/intf-id method-id)]{
|
|
|
|
Creates a hyperlink to the method named by @racket[method-id] in the
|
|
class or interface named by @racket[class/intf-id]. The hyperlink
|
|
names the method, only; see also @racket[xmethod].
|
|
|
|
For-label binding information is used with @racket[class/intf-id], but
|
|
not @racket[method-id].}
|
|
|
|
@defform[(xmethod class/intf-id method-id)]{
|
|
|
|
Like @racket[method], but the hyperlink shows both the method name and
|
|
the containing class/interface.}
|
|
|
|
@defform[(this-obj)]{
|
|
|
|
Within a @racket[defmethod] or similar form, typesets as a
|
|
meta-variable that stands for the target of the method call. Use
|
|
@racket[(this-obj)] to be more precise than prose such as ``this
|
|
method's object.''}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "doc-signatures"]{Documenting Signatures}
|
|
|
|
@defform[(defsignature id (super-id ...) pre-flow ...)]{
|
|
|
|
Defines a signature @racket[id] that extends the @racket[super-id]
|
|
signatures. Any elements defined in @tech{decode}d
|
|
@racket[pre-flow]s---including forms, procedures, structure types,
|
|
classes, interfaces, and mixins---are defined as members of the
|
|
signature instead of direct bindings. These definitions can be
|
|
referenced through @racket[sigelem] instead of @racket[racket].
|
|
|
|
The @tech{decode}d @racket[pre-flow]s inset under the signature
|
|
declaration in the typeset output, so no new sections, @|etc| can be
|
|
started.}
|
|
|
|
@defform[(defsignature/splice id (super-id ...) pre-flow ...)]{
|
|
|
|
Like @racket[defsignature], but the @tech{decode}d @racket[pre-flow]s
|
|
are not typeset under the signature declaration, and new sections,
|
|
@|etc| can be started in the @racket[pre-flow]s.}
|
|
|
|
@defproc[(signature-desc [pre-flow pre-flow?] ...) any/c]{
|
|
|
|
Produces an opaque value that @racket[defsignature] recognizes to
|
|
outdent in the typeset form. This is useful for text describing the
|
|
signature as a whole to appear right after the signature declaration.}
|
|
|
|
@defform[(sigelem sig-id id)]{
|
|
|
|
Typesets the identifier @racket[id] with a hyperlink to its definition
|
|
as a member of the signature named by @racket[sig-id].}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "doc-strings"]{Various String Forms}
|
|
|
|
@defproc[(aux-elem [pre-content pre-content?] ...) element?]{
|
|
Like @racket[elem], but adds an @racket['aux] @tech{style property}.}
|
|
|
|
@defproc[(defterm [pre-content pre-content?] ...) element?]{Typesets the
|
|
@tech{decode}d @racket[pre-content] as a defined term (e.g., in
|
|
italic). Consider using @racket[deftech] instead, though, so that uses
|
|
of @racket[tech] can hyper-link to the definition.}
|
|
|
|
@defproc[(onscreen [pre-content pre-content?] ...) element?]{ Typesets the
|
|
@tech{decode}d @racket[pre-content] as a string that appears in a GUI,
|
|
such as the name of a button.}
|
|
|
|
@defproc[(menuitem [menu-name string?] [item-name string?]) element?]{
|
|
Typesets the given combination of a GUI's menu and item name.}
|
|
|
|
@defproc[(filepath [pre-content pre-content?] ...) element?]{Typesets the
|
|
@tech{decode}d @racket[pre-content] as a file name (e.g., in
|
|
typewriter font and in quotes).}
|
|
|
|
@defproc[(exec [content content?] ...) element?]{Typesets the
|
|
@racket[content] as a command line (e.g., in typewriter font).}
|
|
|
|
@defproc[(envvar [pre-content pre-content?] ...) element?]{Typesets the given
|
|
@tech{decode}d @racket[pre-content] as an environment variable (e.g.,
|
|
in typewriter font).}
|
|
|
|
@defproc[(Flag [pre-content pre-content?] ...) element?]{Typesets the given
|
|
@tech{decode}d @racket[pre-content] as a flag (e.g., in typewriter
|
|
font with a leading @litchar{-}).}
|
|
|
|
@defproc[(DFlag [pre-content pre-content?] ...) element?]{Typesets the given
|
|
@tech{decode}d @racket[pre-content] a long flag (e.g., in typewriter
|
|
font with two leading @litchar{-}s).}
|
|
|
|
@defproc[(PFlag [pre-content pre-content?] ...) element?]{Typesets the given
|
|
@tech{decode}d @racket[pre-content] as a @litchar{+} flag (e.g., in typewriter
|
|
font with a leading @litchar{+}).}
|
|
|
|
@defproc[(DPFlag [pre-content pre-content?] ...) element?]{Typesets the given
|
|
@tech{decode}d @racket[pre-content] a long @litchar{+} flag (e.g., in
|
|
typewriter font with two leading @litchar{+}s).}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "section-links"]{Links}
|
|
|
|
See also @secref["base-links"].
|
|
|
|
@defform*[[(racketlink id #:style style-expr pre-content ...)
|
|
(racketlink id pre-content ...)]
|
|
#:contracts ([id identifier?]
|
|
[pre-content pre-content?])]{
|
|
|
|
An element where the @tech{decode}d @racket[pre-content] is hyperlinked to the definition
|
|
of @racket[id].}
|
|
|
|
@defform[(schemelink id pre-content ...)]{
|
|
|
|
Compatibility alias for @racket[racketlink].}
|
|
|
|
@defproc[(link [url string?] [pre-content any/c] ...
|
|
[#:underline? underline? any/c #t]
|
|
[#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")])
|
|
element?]{
|
|
|
|
Alias of @racket[hyperlink] for backward compatibility.}
|
|
|
|
@defproc[(other-manual [module-path module-path?]
|
|
[#:underline? underline? any/c #t])
|
|
element?]{
|
|
|
|
Alias of @racket[other-doc] for backward compatibility.}
|
|
|
|
@defproc[(deftech [pre-content pre-content?] ...
|
|
[#:key key (or/c string? #f) #f]
|
|
[#:normalize? normalize? any/c #t]
|
|
[#:style? style? any/c #t]) element?]{
|
|
|
|
Produces an element for the @tech{decode}d @racket[pre-content], and
|
|
also defines a term that can be referenced elsewhere using
|
|
@racket[tech].
|
|
|
|
When @racket[key] is @racket[#f], the @racket[content->string] result
|
|
of the @tech{decode}d @racket[pre-content] is used as a key for
|
|
references. If @racket[normalize?] is true, then the key string is
|
|
normalized as follows:
|
|
|
|
@itemize[
|
|
|
|
@item{The string is case-folded.}
|
|
|
|
@item{A trailing ``ies'' is replaced by ``y''.}
|
|
|
|
@item{A trailing ``s'' is removed.}
|
|
|
|
@item{Consecutive hyphens and whitespaces are all replaced by a
|
|
single space.}
|
|
|
|
]
|
|
|
|
These normalization steps help support natural-language references
|
|
that differ slightly from a defined form. For example, a definition of
|
|
``bananas'' can be referenced with a use of ``banana''.
|
|
|
|
If @racket[style?] is true, then @racket[defterm] is used on
|
|
@racket[pre-content].}
|
|
|
|
@defproc[(tech [pre-content pre-content?] ...
|
|
[#:key key (or/c string? #f) #f]
|
|
[#:normalize? normalize? any/c #t]
|
|
[#:doc module-path (or/c module-path? #f) #f]
|
|
[#:tag-prefixes prefixes (or/c (listof string?) #f) #f])
|
|
element?]{
|
|
|
|
Produces an element for the @tech{decode}d @racket[pre-content], and
|
|
hyperlinks it to the definition of the key as established by
|
|
@racket[deftech]. If @racket[key] is false, the decoded content is
|
|
converted to a string (using @racket[content->string]) to use as a
|
|
key; in either case, if @racket[normalize?] is true, the key is normalized in the same way as for
|
|
@racket[deftech]. The @racket[#:doc] and @racket[#:tag-prefixes]
|
|
arguments support cross-document and section-specific references, like
|
|
in @racket[secref].
|
|
For example:
|
|
@racketblock[@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{blame object}]
|
|
|
|
creates a link to @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{blame object} in
|
|
@other-doc['(lib "scribblings/reference/reference.scrbl")].
|
|
|
|
With the default style files, the hyperlink created by @racket[tech]
|
|
is somewhat quieter than most hyperlinks: the underline in HTML output
|
|
is gray, instead of blue, and the term and underline turn blue only
|
|
when the mouse is moved over the term.
|
|
|
|
In some cases, combining both natural-language uses of a term and
|
|
proper linking can require some creativity, even with the
|
|
normalization performed on the term. For example, if ``bind'' is
|
|
defined, but a sentence uses the term ``binding,'' the latter can be
|
|
linked to the former using @racketfont["@tech{bind}ing"].}
|
|
|
|
@defproc[(techlink [pre-content pre-content?] ...
|
|
[#:key key (or/c string? #f) #f]
|
|
[#:normalize? normalize? any/c #t]
|
|
[#:doc module-path (or/c module-path? #f) #f]
|
|
[#:tag-prefixes prefixes (or/c (listof string?) #f) #f])
|
|
element?]{
|
|
|
|
Like @racket[tech], but the link is not quiet. For example, in HTML
|
|
output, a hyperlink underline appears even when the mouse is not over
|
|
the link.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "manual-indexing"]{Indexing}
|
|
|
|
See also @secref["base-indexing"] for @racketmodname[scribble/base].
|
|
|
|
@defform[(indexed-racket datum ...)]{
|
|
|
|
A combination of @racket[racket] and @racket[as-index], with the
|
|
following special cases when a single @racket[datum] is provided:
|
|
|
|
@itemize[
|
|
|
|
@item{If @racket[datum] is a @racket[quote] form, then the quote is
|
|
removed from the key (so that it's sorted using its unquoted
|
|
form).}
|
|
|
|
@item{If @racket[datum] is a string, then quotes are removed from the
|
|
key (so that it's sorted using the string content).}
|
|
|
|
]}
|
|
|
|
@defform[(indexed-scheme datum ...)]{
|
|
|
|
Compatibility alias for @racket[indexed-racket].}
|
|
|
|
@defproc[(idefterm [pre-content pre-content?] ...) element?]{Combines
|
|
@racket[as-index] and @racket[defterm]. The content normally should be
|
|
plural, rather than singular. Consider using @racket[deftech],
|
|
instead, which always indexes.}
|
|
|
|
@defproc[(pidefterm [pre-content pre-content?] ...) element?]{Like
|
|
@racket[idefterm], but plural: adds an ``s'' on the end of the content
|
|
for the index entry. Consider using @racket[deftech], instead.}
|
|
|
|
@defproc[(indexed-file [pre-content pre-content?] ...) element?]{A
|
|
combination of @racket[file] and @racket[as-index], but where the sort
|
|
key for the index iterm does not include quotes.}
|
|
|
|
@defproc[(indexed-envvar [pre-content pre-content?] ...) element?]{A
|
|
combination of @racket[envvar] and @racket[as-index].}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Bibliography}
|
|
|
|
@margin-note{See also @racketmodname[scriblib/autobib].}
|
|
|
|
@defproc[(cite [key string?] ...+) element?]{
|
|
|
|
Links to a bibliography entry, using the @racket[key]s both to indicate the
|
|
bibliography entry and, in square brackets, as the link text.}
|
|
|
|
@defproc[(bibliography [#:tag tag string? "doc-bibliography"]
|
|
[entry bib-entry?] ...)
|
|
part?]{
|
|
|
|
Creates a bibliography part containing the given entries, each of
|
|
which is created with @racket[bib-entry]. The entries are typeset in
|
|
order as given.}
|
|
|
|
@defproc[(bib-entry [#:key key string?]
|
|
[#:title title (or/c #f pre-content?)]
|
|
[#:is-book? is-book? boolean? #f]
|
|
[#:author author (or/c #f pre-content?) #f]
|
|
[#:location location (or/c #f pre-content?) #f]
|
|
[#:date date (or/c #f pre-content?) #f]
|
|
[#:url url (or/c #f pre-content?) #f]
|
|
[#:note note (or/c #f pre-content?) #f])
|
|
bib-entry?]{
|
|
|
|
Creates a bibliography entry. The @racket[key] is used to refer to the
|
|
entry via @racket[cite]. The other arguments are used as elements in
|
|
the entry:
|
|
|
|
@itemize[
|
|
|
|
@item{@racket[title] is the title of the cited work. It will be
|
|
surrounded by quotes in typeset form if @racket[is-book?] is
|
|
@racket[#f], otherwise it is typeset via @racket[italic].}
|
|
|
|
@item{@racket[author] lists the authors. Use names in their usual
|
|
order (as opposed to ``last, first''), and separate multiple
|
|
names with commas using ``and'' before the last name (where
|
|
there are multiple names). The @racket[author] is typeset in
|
|
the bibliography as given, or it is omitted if given as
|
|
@racket[#f].}
|
|
|
|
@item{@racket[location] names the publication venue, such as a
|
|
conference name or a journal with volume, number, and
|
|
pages. The @racket[location] is typeset in the bibliography as
|
|
given, or it is omitted if given as @racket[#f].}
|
|
|
|
@item{@racket[date] is a date, usually just a year (as a string). It
|
|
is typeset in the bibliography as given, or it is omitted if
|
|
given as @racket[#f].}
|
|
|
|
@item{@racket[url] is an optional URL. It is typeset in the
|
|
bibliography using @racket[tt] and hyperlinked, or it is
|
|
omitted if given as @racket[#f].}
|
|
|
|
@item{@racket[note] is an optional comment about the work. It is typeset
|
|
in the bibliography as given, and appears directly after the date
|
|
(or URL, if given) with no space or punctuation in between.}
|
|
]
|
|
|
|
@history[#:changed "1.29" @elem{Added the @racket[#:note] option.}]}
|
|
|
|
|
|
@defproc[(bib-entry? [v any/c]) boolean?]{
|
|
|
|
Returns @racket[#t] if @racket[v] is a bibliography entry created by
|
|
@racket[bib-entry], @racket[#f] otherwise.}
|
|
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Version History}
|
|
|
|
@defform[(history clause ...)
|
|
#:grammar ([clause (code:line #:added version-expr)
|
|
(code:line #:changed version-expr content-expr)])
|
|
#:contracts ([version-expr valid-version?]
|
|
[content-expr content?])]{
|
|
|
|
Generates a @tech{block} for version-history notes. The version
|
|
refers to a package as determined by a @racket[defmodule] or
|
|
@racket[declare-exporting] declaration within an enclosing section.
|
|
|
|
Normally, @racket[history] should be used at the end of a
|
|
@racket[defform], @racket[defproc], @|etc|, entry, although it may
|
|
also appear in a section that introduces a module (that has been added
|
|
to a package). In the case of a @racket[changed] entry, the content
|
|
produced by @racket[content-expr] should normally start with a capital
|
|
letter and end with a period, but it can be a sentence fragment such
|
|
as ``Added a @racket[#:changed] form.''
|
|
|
|
Examples:
|
|
@codeblock[#:keep-lang-line? #f]|{
|
|
#lang scribble/manual
|
|
@defthing[tasty-burrito burrito?]{
|
|
Compatible with the API of a sandwich, but not legally a
|
|
sandwich in Massachusetts.
|
|
|
|
@history[#:added "1.0"
|
|
#:changed "1.1" "Refactored tortilla."
|
|
#:changed "1.2" @elem{Now includes @emph{guacamole}.}]
|
|
}
|
|
}|
|
|
@doc-render-examples[
|
|
@defthing[tasty-burrito burrito?]{
|
|
Compatible with the API of a sandwich, but not legally a
|
|
sandwich in Massachusetts.
|
|
|
|
@history[#:added "1.0"
|
|
#:changed "1.1" "Refactored tortilla."
|
|
#:changed "1.2" @elem{Now includes @emph{guacamole}.}]
|
|
}]
|
|
|
|
@history[#:added "1.1"]}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Miscellaneous}
|
|
|
|
@defproc[(t [pre-content pre-content?] ...) paragraph?]{Wraps the
|
|
@tech{decode}d @racket[pre-content] as a paragraph.}
|
|
|
|
@defthing[etc element?]{Like @racket["etc."], but with an
|
|
abbreviation-ending period for use in the middle of a sentence.}
|
|
|
|
@defthing[PLaneT element?]{@racket["PLaneT"] (to help make sure you get
|
|
the letters in the right case).}
|
|
|
|
@defthing[manual-doc-style style?]{
|
|
|
|
A style to be used for a document's main @racket[part] to get the
|
|
style configuration of @racket[@#,hash-lang[] @#,racketmodname[scribble/manual]].
|
|
See @secref["manual-render-style"].}
|
|
|
|
@defproc[(hash-lang) element?]{Returns an element for @hash-lang[]
|
|
that is hyperlinked to an explanation.}
|
|
|
|
@defthing[void-const element?]{Returns an element for @|void-const|.}
|
|
|
|
@defthing[undefined-const element?]{Returns an element for @|undefined-const|.}
|
|
|
|
@defproc[(commandline [content content?] ...) paragraph?]{Produces
|
|
an inset command-line example (e.g., in typewriter font).}
|
|
|
|
@defproc[(inset-flow [pre-flow pre-flow?] ...) nested-flow?]{
|
|
|
|
Creates a @racket[nested-flow] with indenting on the left and right.
|
|
|
|
Using @racket[nested] with the @racket['inset] style is a prefered
|
|
alternative.}
|
|
|
|
@defproc[(centerline [pre-flow pre-flow?] ...) nested-flow?]{
|
|
|
|
An alias for @racket[centered] for backward compatibility.}
|
|
|
|
@defproc[(math [pre-content any/c] ...) element?]{The @tech{decode}d
|
|
@racket[pre-content] is further transformed:
|
|
|
|
@itemize[
|
|
|
|
@item{Any immediate @racket['rsquo] is converted to @racket['prime].}
|
|
|
|
@item{Parentheses and sequences of decimal digits in immediate
|
|
strings are left as-is, but any other immediate string is
|
|
italicized.}
|
|
|
|
@item{When @litchar{_} appears before a non-empty sequence of numbers
|
|
and letters, the sequence is typeset as a subscript.}
|
|
|
|
@item{When @litchar{^} appears before a non-empty sequence of numbers
|
|
and letters, the sequence is typeset as a superscript.}
|
|
|
|
]}
|
|
|
|
@defproc[(filebox [filename (or/c string? element?)] [pre-flow pre-flow?] ...)
|
|
block?]{
|
|
|
|
Typesets the @racket[pre-flow]s as the content of
|
|
@racket[filename]. For example, the content may be inset on the page
|
|
with @racket[filename] above it. If @racket[filename] is a string, it
|
|
is passed to @racket[filepath] to obtain an @racket[element].}
|
|
|
|
@defproc[(deprecated [#:what what content? "library"]
|
|
[replacement content?]
|
|
[additional-notes content?] ...)
|
|
block?]{
|
|
Produces an inset warning for deprecated libraries, functions, @|etc| (as
|
|
described by @racket[what]), where @racket[replacement] describes a
|
|
suitable replacement. The @racket[additional-notes] are included after the
|
|
initial deprecation message.}
|
|
|
|
@defproc[(image/plain [filename-relative-to-source string?]
|
|
[pre-element any/c] ...)
|
|
element?]{
|
|
|
|
An alias for @racket[image] for backward compatibility.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section[#:tag "index-entries"]{Index-Entry Descriptions}
|
|
|
|
@defmodule[scribble/manual-struct]{The
|
|
@racketmodname[scribble/manual-struct] library provides types used to
|
|
describe index entries created by @racketmodname[scribble/manual]
|
|
functions. These structure types are provided separate from
|
|
@racketmodname[scribble/manual] so that
|
|
@racketmodname[scribble/manual] need not be loaded when deserializing
|
|
cross-reference information that was generated by a previously
|
|
rendered document.}
|
|
|
|
@defstruct[module-path-index-desc ()]{
|
|
|
|
Indicates that the index entry corresponds to a module definition via
|
|
@racket[defmodule] and company.}
|
|
|
|
@deftogether[(
|
|
@defstruct[(language-index-desc module-path-index-desc) ()]{}
|
|
@defstruct[(reader-index-desc module-path-index-desc) ()]{}
|
|
)]{
|
|
Indicates that the index entry corresponds to a module definition via
|
|
@racket[defmodule] with the @racket[#:lang] or @racket[#:reader] option.
|
|
For example, a module definition via @racket[defmodulelang] has a
|
|
@racket[language-index-desc] index entry and a module definition via
|
|
@racket[defmodulereader] has a @racket[reader-index-desc] index entry.}
|
|
|
|
@defstruct[exported-index-desc ([name symbol?]
|
|
[from-libs (listof module-path?)])]{
|
|
|
|
Indicates that the index entry corresponds to the definition of an
|
|
exported binding. The @racket[name] field and @racket[from-libs] list
|
|
correspond to the documented name of the binding and the primary
|
|
modules that export the documented name (but this list is not
|
|
exhaustive, because new modules can re-export the binding).}
|
|
|
|
@defstruct[(form-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of a
|
|
syntactic form via @racket[defform] and company.}
|
|
|
|
@defstruct[(procedure-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of a
|
|
procedure binding via @racket[defproc] and company.}
|
|
|
|
@defstruct[(thing-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of a
|
|
binding via @racket[defthing] and company.}
|
|
|
|
@defstruct[(struct-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of a
|
|
structure type via @racket[defstruct] and company.}
|
|
|
|
@defstruct[(class-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of a
|
|
class via @racket[defclass] and company.}
|
|
|
|
@defstruct[(interface-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of an
|
|
interface via @racket[definterface] and company.}
|
|
|
|
@defstruct[(mixin-index-desc exported-index-desc) ()]{
|
|
|
|
Indicates that the index entry corresponds to the definition of a
|
|
mixin via @racket[defmixin] and company.}
|
|
|
|
@defstruct[(method-index-desc exported-index-desc) ([method-name symbol?]
|
|
[class-tag tag?])]{
|
|
|
|
Indicates that the index entry corresponds to the definition of an
|
|
method via @racket[defmethod] and company. The @racket[_name] field
|
|
from @racket[exported-index-desc] names the class or interface that
|
|
contains the method. The @racket[method-name] field names the method.
|
|
The @racket[class-tag] field provides a pointer to the start of the
|
|
documentation for the method's class or interface.}
|
|
|
|
@defstruct[(constructor-index-desc exported-index-desc) ([class-tag tag?])]{
|
|
|
|
Indicates that the index entry corresponds to a constructor
|
|
via @racket[defconstructor] and company. The @racket[_name] field
|
|
from @racket[exported-index-desc] names the class or interface that
|
|
contains the method.
|
|
The @racket[class-tag] field provides a pointer to the start of the
|
|
documentation for the method's class or interface.}
|
|
|
|
@;----------------------------------------
|
|
|
|
@section[#:tag "manual-render-style"]{Manual Rendering Style}
|
|
|
|
Using @racket[@#,hash-lang[] @#,racketmodname[scribble/manual]] for the
|
|
main @racket[part] of a document associates @tech{style properties} on
|
|
the @racket[doc] export to select the Racket manual style for
|
|
rendering.
|
|
|
|
A @racket[html-defaults] @tech{style property} is added to
|
|
@racket[doc], unless @racket[doc]'s style already has a
|
|
@racket[html-defaults] @tech{style property} (e.g., supplied to
|
|
@racket[title]). Similarly, a @racket[latex-default] @tech{style
|
|
property} is added if one is not already present. Finally, an
|
|
@racket[css-style-addition] property is always added.
|
|
|
|
For HTML rendering:
|
|
|
|
@itemlist[
|
|
|
|
@item{The document's @tech{prefix file} is set to
|
|
@filepath{scribble-prefix.html}, as usual, in @racket[html-defaults].}
|
|
|
|
@item{The document's @tech{style file} is set to
|
|
@filepath{manual-style.css} from the @filepath{scribble}
|
|
collection in @racket[html-defaults].}
|
|
|
|
@item{The file @filepath{manual-fonts.css} from the
|
|
@filepath{scribble} collection is designated as an additional
|
|
accompanying file in @racket[html-defaults].}
|
|
|
|
@item{The file @filepath{manual-racket.css} from the
|
|
@filepath{scribble} collection is added as a
|
|
@racket[css-style-addition].}
|
|
|
|
]
|
|
|
|
To obtain this configuration without using @racket[@#,hash-lang[]
|
|
@#,racketmodname[scribble/manual]], use @racket[manual-doc-style].
|