329 lines
12 KiB
Racket
329 lines
12 KiB
Racket
#reader(lib "docreader.ss" "scribble")
|
|
@require[(lib "manual.ss" "scribble")]
|
|
@require["utils.ss"]
|
|
@require-for-syntax[mzscheme]
|
|
|
|
@title[#:tag "manual"]{PLT Manual Forms}
|
|
|
|
The @file{manual.ss} module provides all of @file{basic.ss}, and
|
|
more...
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Typesetting Code}
|
|
|
|
@defform[(schemeblock datum ...)]{
|
|
|
|
Typesets the @scheme[datum] sequence as a table of Scheme code inset
|
|
by two spaces. The source locations of the @scheme[datum]s determines
|
|
the generated layout. For example,
|
|
|
|
@schemeblock[
|
|
(schemeblock
|
|
(define (loop x)
|
|
(loop (not x))))
|
|
]
|
|
|
|
produces the output
|
|
|
|
@schemeblock[
|
|
(define (loop x)
|
|
(loop (not x)))
|
|
]
|
|
|
|
with the @scheme[(loop (not x))] indented under @scheme[define],
|
|
because that's the way it is idented the use of @scheme[schemeblock].
|
|
Furthermore, @scheme[define] is typeset as a keyword (bold and black)
|
|
and as a hyperlink to @scheme[define]'s definition in the reference
|
|
manual, because this document was built using information about the
|
|
MzScheme manual. Similarly, @scheme[not] is a hyperlink to the its
|
|
definition in the reference manual.
|
|
|
|
Use @scheme[unsyntax] to escape back to an expression that produces an
|
|
@scheme[element]. For example,
|
|
|
|
@let[([unsyntax #f])
|
|
(schemeblock
|
|
(schemeblock
|
|
(+ 1 (unsyntax (elem (scheme x) (subscript "2"))))))
|
|
]
|
|
|
|
produces
|
|
|
|
@schemeblock[
|
|
(+ 1 (unsyntax (elem (scheme x) (subscript "2"))))
|
|
]
|
|
|
|
The @scheme[unsyntax] form is regonized via
|
|
@scheme[module-identifier=?], so if you want to typeset code that
|
|
includes @scheme[unsyntax], you can simply hide the usual binding:
|
|
|
|
@SCHEMEBLOCK[
|
|
(schemeblock
|
|
(let ([(UNSYNTAX (scheme unsyntax)) #f])
|
|
(schemeblock
|
|
(syntax (+ 1 (unsyntax x))))))
|
|
]
|
|
|
|
Or use @scheme[SCHEMEBLOCK], whose escape form is @scheme[UNSYNTAX]
|
|
instead of @scheme[unsyntax]. See also @scheme[define-code] from
|
|
@file{scheme.ss}.
|
|
|
|
A few other escapes are recognized symbolically:
|
|
|
|
@itemize{
|
|
|
|
@item{@scheme[(#,(scheme code:line) datum ...)] typesets as the
|
|
sequence of @scheme[datum]s (i.e., without the
|
|
@scheme[code:line] wrapper.}
|
|
|
|
@item{@scheme[(#,(scheme code:comment) content-expr)] typesets as a
|
|
comment whose content (i.e., sequence of elements) is produced
|
|
by @scheme[content-expr].}
|
|
|
|
@item{@schemeidfont{code:blank} typesets as a blank line.}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
@defform[(SCHEMEBLOCK datum ...)]{Like @scheme[schemeblock], but with
|
|
the expression escape @scheme[UNSYNTAX] instead of @scheme[unsyntax].}
|
|
|
|
@defform[(schemeblock0 datum ...)]{Like @scheme[schemeblock], but
|
|
without insetting the code.}
|
|
|
|
@defform[(SCHEMEBLOCK0 datum ...)]{Like @scheme[SCHEMEBLOCK], but
|
|
without insetting the code.}
|
|
|
|
@defform[(schemeinput datum ...)]{Like @scheme[schemeblock], but the
|
|
@scheme[datum] are typeset after a prompt representing a REPL.}
|
|
|
|
@defform[(schememod lang datum ...)]{Like @scheme[schemeblock], but
|
|
the @scheme[datum] are typeset inside a @schemefont{#module}-form
|
|
module whose language is @scheme[lang].}
|
|
|
|
@defform[(scheme datum ...)]{Like @scheme[schemeblock], but typeset on
|
|
a single line and wrapped with its enclosing paragraph, independent of
|
|
the formatting of @scheme[datum].}
|
|
|
|
@defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset
|
|
as a REPL value (i.e., a single color with no hperlinks).}
|
|
|
|
@defform[(schemeid datum ...)]{Like @scheme[scheme], but typeset
|
|
as an unbound identifier (i.e., no coloring or hyperlink).}
|
|
|
|
@defform[(schememodname datum ...)]{Like @scheme[scheme], but typeset
|
|
as a @schemefont{#module} language name.}
|
|
|
|
@defproc[(litchar [str string?]) element?]{Typesets @scheme[str] as a
|
|
representation of literal text. Use this when you have to talk about
|
|
the individual characters in a stream of text, as as when documenting
|
|
a reader extension.}
|
|
|
|
@defproc[(verbatim [str string?]) flow-element?]{Typesets @scheme[str]
|
|
as a table/paragraph in typewriter font with the linebreaks specified
|
|
by newline characters in @scheme[str]. ``Here strings'' are often
|
|
useful with @scheme[verbatim].}
|
|
|
|
@defproc[(schemefont [pre-content any/c] ...0) element?]{Typesets the given
|
|
content as uncolored, unhyperlinked Scheme. This procedure is useful
|
|
for typesetting thngs like @scheme{#module}, which are not
|
|
@scheme[read]able by themselves.}
|
|
|
|
@defproc[(schemevalfont [pre-content any/c] ...0) element?]{Like
|
|
@scheme[schemefont], but colored as a value.}
|
|
|
|
@defproc[(schemeresultfont [pre-content any/c] ...0) element?]{Like
|
|
@scheme[schemefont], but colored as a REPL result.}
|
|
|
|
@defproc[(schemeidfont [pre-content any/c] ...0) element?]{Like
|
|
@scheme[schemefont], but colored as an identifier.}
|
|
|
|
@defproc[(schemekeywordfont [pre-content any/c] ...0) element?]{Like
|
|
@scheme[schemefont], but colored as a syntactic form name.}
|
|
|
|
@defproc[(procedure [pre-content any/c] ...0) element?]{Typesets the given
|
|
content as a procedure name in a REPL result (e.g., in typewrite font
|
|
with a @schemefont{#<procedure:} prefix and @schemefont{>} suffix.).}
|
|
|
|
@defform[(var datum)]{Typesets @scheme[var] as an identifier that is
|
|
an argument or sub-form in a procedure being
|
|
documented. Normally, the @scheme[defproc] and @scheme[defform]
|
|
arrange for @scheme[scheme] to format such identifiers automatically
|
|
in the description of the procedure, but use @scheme[var] if that
|
|
cannot work for some reason.}
|
|
|
|
@defform[(svar datum)]{Like @scheme[var], but for subform non-terminals
|
|
in a form definition.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Definition Reference}
|
|
|
|
@defform[(defproc (identifier arg-spec ...) result-contract-expr-datum pre-flow ...)]{Produces
|
|
a sequence of flow elements (encaptured in a @scheme[splice]) to
|
|
document a procedure named @scheme[identifier]. The
|
|
@scheme[identifier] is registered so that @scheme[scheme]-typeset uses
|
|
of the identifier are hyperlinked to this documentation.
|
|
|
|
Each @scheme[arg-spec] must have one of the following forms:
|
|
|
|
@itemize{
|
|
|
|
@item{@specsubform/inline[(arg-identifier contract-expr-datum)]{---
|
|
an argument whose contract is specified by
|
|
@scheme[contract-expr-datum] which is typeset via
|
|
@scheme[scheme].}}
|
|
|
|
@item{@specsubform/inline[(arg-identifier 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.}}
|
|
|
|
@item{@specsubform/inline[(keyword arg-identifier
|
|
contract-expr-datum)]{ --- like the first case, but for a
|
|
keyword-based argument.}}
|
|
|
|
@item{@specsubform/inline[(keyword arg-identifier contract-expr-datum
|
|
default-expr)]{ --- like the previous case, but with a default
|
|
value.}}
|
|
|
|
@item{@scheme[...0] --- any number of the preceding argument
|
|
(normally at the end)}
|
|
|
|
@item{@scheme[...1] --- one or more of the preceding argument
|
|
(normally at the end)}
|
|
|
|
}
|
|
|
|
The @scheme[result-contract-expr-datum] is typeset via
|
|
@scheme[scheme], and it represents a contract on the procedure's
|
|
result.
|
|
|
|
The @scheme[pre-flow]s list is parsed as a flow that documents the
|
|
procedure. In this description, references to @svar[arg-identifier]s
|
|
are typeset as procedure arguments.
|
|
|
|
The typesetting of all data before the @scheme[pre-flow]s ignores the
|
|
source layout.}
|
|
|
|
|
|
@defform[(defproc* (((identifier arg-spec ...) result-contract-expr-datum) ...) pre-flow ...)]{Like
|
|
@scheme[defproc], but for multiple cases with the same @scheme[identifier].
|
|
}
|
|
|
|
|
|
@defform[(defform (identifier . datum) pre-flow ...)]{Produces a
|
|
a sequence of flow elements (encaptured in a @scheme[splice]) to
|
|
document a syntaic form named by @scheme[identifier]. The
|
|
@scheme[identifier] is registered so that @scheme[scheme]-typeset uses
|
|
of the identifier are hyperlinked to this documentation.
|
|
|
|
The @scheme[pre-flow]s list is parsed as a flow that documents the
|
|
procedure. In this description, a reference to any identifier in
|
|
@scheme[datum] is typeset as a sub-form non-terminal.
|
|
|
|
The typesetting of @scheme[(identifier . datum)] preserves the source
|
|
layout, like @scheme[scheme], and unlike @scheme[defproc].}
|
|
|
|
|
|
@defform[(specsubform/inline datum pre-flow ...)]{Similar to
|
|
@scheme[defform], but without any specific identifier being defined,
|
|
without the output format that highlights a definition, and with
|
|
@scheme[datum] as an element rather than a table. This form is
|
|
intended for use when refining the syntax of a non-terminal used in a
|
|
@scheme[defform], @scheme[specsubform], or other
|
|
@scheme[specsubform/inline]. For example, it is used in the
|
|
documentation for @scheme[defproc] in the itemization of possible
|
|
shapes for @svar[arg-spec].
|
|
|
|
The @scheme[pre-flow]s list is parsed as a flow that documents the
|
|
procedure. In this description, a reference to any identifier in
|
|
@scheme[datum] is typeset as a sub-form non-terminal.}
|
|
|
|
|
|
@defform[(specsubform datum pre-flow ...)]{Like
|
|
@scheme[specsubform/inline], but the @scheme[datum] is typeset in the
|
|
resulting flow as a table instead of an element.}
|
|
|
|
|
|
@defform[(defthing identifier contract-expr-datum pre-flow ...)]{Like
|
|
@scheme[defproc], but for a non-procedure binding.}
|
|
|
|
@defform[(defstruct struct-name ([field-name contract-expr-datum] ...) pre-flow ...)]{Similar
|
|
to @scheme[defform], but for a structure definition.
|
|
|
|
The @scheme[struct-name] can be either of the following:
|
|
|
|
@itemize{
|
|
|
|
@item{@specsubform/inline[identifier]{--- a structure type with no
|
|
specified supertype.}}
|
|
|
|
@item{@specsubform/inline[(identifier super-identifier)]{ --- a structure
|
|
type with indicated supertype.}}
|
|
|
|
}}
|
|
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Various String Forms}
|
|
|
|
@defproc[(defterm [pre-content any/c] ...0) element?]{Typesets the given
|
|
content as a defined term (e.g., in italic).}
|
|
|
|
@defproc[(onscreen [pre-content any/c] ...0) element?]{ Typesets the given
|
|
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[(file [pre-content any/c] ...0) element?]{Typesets the given content
|
|
as a file name (e.g., in typewriter font and in in quotes).}
|
|
|
|
@defproc[(exec [pre-content any/c] ...0) element?]{Typesets the given content
|
|
as a command line (e.g., in typewriter font).}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Section Links}
|
|
|
|
@defproc[(secref [tag string?]) element?]{Inserts the hyperlinked
|
|
title of the section tagged @scheme[tag].}
|
|
|
|
@defproc[(seclink [tag string?] [pre-content any/c] ...0) element?]{The content from
|
|
@scheme[pre-content] is hyperlinked to the section tagged @scheme[tag].}
|
|
|
|
@defproc[(schemelink [id symbol?] [pre-content any/c] ...0) element?]{The content from
|
|
@scheme[pre-content] is hyperlinked to the definition of @scheme[id].}
|
|
|
|
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Indexing}
|
|
|
|
@defproc[(idefterm [pre-content any/c] ...0) element?]{Combines
|
|
@scheme[as-index] and @scheme[defterm]. The content normally should be
|
|
plurarl, rather than singular.}
|
|
|
|
@defproc[(pidefterm [pre-content any/c] ...0) element?]{Like
|
|
@scheme[idefterm], but plural: adds an ``s'' on the end of the content
|
|
for the index entry.}
|
|
|
|
@; ------------------------------------------------------------------------
|
|
@section{Miscellaneous}
|
|
|
|
@defthing[PLaneT string?]{@scheme["PLaneT"] (to help make sure you get
|
|
the letters in the right case).}
|
|
|
|
@defproc[(void-const) any/c]{Returns @scheme["void"], as opposed to
|
|
@scheme[(scheme void)]---but we may eventually find a clearer way to
|
|
refer to @void-const in prose.}
|
|
|
|
@defproc[(centerline [pre-flow any/c] ...0) table?]{Produces a
|
|
centered table with the @scheme[pre-flow] parsed by
|
|
@scheme[decode-flow].}
|
|
|
|
@defproc[(commandline [pre-content any/c] ...0) paragraph?]{Produces a
|
|
an inset command-line example (e.g., in typewriter font).}
|