4.2.1 Typesetting Code
Typesets the datum sequence as a table of Scheme code inset
by two spaces. The source locations of the datums determine
the generated layout. For example,
produces the output
with the (loop (not x)) indented under define,
because that’s the way it is idented the use of schemeblock.
Furthermore, define is typeset as a keyword (bold and black)
and as a hyperlink to define’s definition in the reference
manual, because this document was built using a for-label binding of
define (in the source) that matches a definition in the
reference manual. Similarly, not is a hyperlink to the its
definition in the reference manual.
Use unsyntax to escape back to an expression that produces an
element. For example,
produces
(+ 1 x2)
The unsyntax form is regonized via
free-identifier=?, so if you want to typeset code that
includes unsyntax, you can simply hide the usual binding:
Or use SCHEMEBLOCK, whose escape form is UNSYNTAX
instead of unsyntax.
A few other escapes are recognized symbolically:
(code:line datum ...) typesets as the
sequence of datums (i.e., without the
code:line wrapper).
(code:comment datum) typesets like
datum, but colored as a comment and prefixed with a
semi-colon. A typical datum escapes from
Scheme-typesetting mode using unsyntax and
produces a paragraph using t:
(code:comment @#,t{this is a comment}) |
(Note that @#,foo{...} reads as
#,(foo "...").)
code:blank typesets as a blank space.
_id typesets as id, but
colored as a variable (like schemevarfont); this
escape applies only if _id has no
for-label binding and is not specifically colored as a subform
non-terminal via defform, a variable via
defproc, etc.
See also scribble/comment-reader.
Like
schemeblock, but the
datum are typeset after a prompt representing a REPL.
Like
schemeblock, but
the
datum are typeset inside a
#lang-form
module whose language is
lang. The source location of
lang (relative to the body
datums) determines the
relative positioning of the
#lang line in the typeset
output.
Like
schemeblock, but typeset on
a single line and wrapped with its enclosing paragraph, independent of
the formatting of
datum.
Like
scheme, but typeset
as a REPL value (i.e., a single color with no hyperlinks).
Like
scheme, but typeset
as an unbound identifier (i.e., no coloring or hyperlinks).
Like
scheme, but typeset as a module path. If
datum
is an identifier or
expr produces a symbol, then it is
hyperlinked to the module path’s definition as created by
defmodule.
Like
schememodlink, but separating the module path to link
from the content to be linked. The
datum module path is always
linked, even if it is not an identifier.
Typesets strs 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.
Typesets
decoded
pre-content as uncolored, unhyperlinked
Scheme. This procedure is useful for typesetting things like
#lang, which are not
readable by themselves.
Like
schemefont, but colored as a variable (i.e., an argument or
sub-form in a procedure being documented).
Like
schemefont, but colored as a syntactic form name.
Like
schemefont, but colored as meta-syntax, such as backquote or
unquote.
Like
schemefont, but colored as error-message text.
Typesets
decoded
pre-content as a procedure name in a REPL
result (e.g., in typewriter font with a
#<procedure: prefix
and
> suffix.).
Typesets
datum as an identifier that is
an argument or sub-form in a procedure being documented. Normally, the
defproc and
defform arrange for
scheme to
format such identifiers automatically in the description of the
procedure, but use
var if that cannot work for some reason.
Like
var, but for subform non-terminals
in a form definition.
4.2.1.1 Typesetting Comments
As a reader module, scribble/comment-reader reads a
single S-expression that contains ;-based comment lines, and
it wraps the comments with code:comment for use with forms
like schemeblock. More precisely,
scribble/comment-reader extends the current reader to
adjust the parsing of ;.
For example, within a Scribble document that imports
scribble/manual,
@#reader scribble/comment-reader |
(schemeblock |
;; This is not a pipe |
(make-pipe) |
) |
generates
The initial @ is needed above to shift into S-expression
mode, so that #reader is recognized as a reader
declaration instead of literal text. Also, the example uses
(schemeblock ....) instead of
@schemeblock[....]
because the @-reader would drop comments within the
schemeblock before giving
scribble/comment-reader a chance to convert them.