2216 lines
88 KiB
Racket
2216 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[(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[(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-string-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-string-expr] uses the default, otherwise
|
|
@racket[kind-string-expr] should produce a string. 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-string-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-string-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-string-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-string-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 override)
|
|
(code:line #:mode override-final)
|
|
(code:line #:mode public-final)
|
|
(code:line #:mode augment)
|
|
(code:line #:mode augment-final)
|
|
(code:line #:mode pubment)
|
|
(code:line #:mode extend)
|
|
(code:line #:mode extend-final)])]{
|
|
|
|
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.}
|
|
|
|
@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 [pre-content pre-content?] ...) element?]{Typesets the
|
|
@tech{decode}d @racket[pre-content] as a command line (e.g., in
|
|
typewriter font).}
|
|
|
|
@defproc[(envvar [pre-content pre-content?] ...) element?]{Typesets the given
|
|
@tech{decode}d @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/guide/guide.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 [pre-content pre-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-files.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].
|