4.2.1 Typesetting Code
Typesets the datum sequence as a table of Racket 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 racketblock.
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 RACKETBLOCK, 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
Racket-typesetting mode using unsyntax and
produces a paragraph using t:
(code:comment @#,t{this is a comment}) |
(Note that @#,foo{...} reads as
#,(foo "...").)
typesets as a blank space.
(code:hilite datum) typesets like
datum, but with a background highlight.
(code:quote datum) typesets like
(quote datum), but without rendering the
quote as '.
_id typesets as id, but
colored as a variable (like racketvarfont); 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
racketblock, but the
datum are typeset after a prompt representing a REPL.
| (racketmod maybe-file lang datum ...) |
| |
| maybe-file | | = | | | | | | | | | #:file filename-expr |
|
Like
racketblock, 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. So, line up
lang with the left end of the content code.
If #:file is provided, then the code block is typeset using
filebox with filename-expr as the filename
argument.
Like
racketblock, but typeset on
a single line and wrapped with its enclosing paragraph, independent of
the formatting of
datum.
Like
racket, but typeset
as a REPL value (i.e., a single color with no hyperlinks).
Like
racket, but typeset
as an unbound identifier (i.e., no coloring or hyperlinks).
Like
racket, 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
racketmod, 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
Racket. This procedure is useful for typesetting things like
#lang, which are not
readable by themselves.
Like
racketfont, but colored as a variable (i.e., an argument or
sub-form in a procedure being documented).
Like
racketfont, but colored as a syntactic form name.
Like
racketfont, but colored as meta-syntax, such as backquote or
unquote.
Like
racketfont, 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
racket 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.
Compatibility aliases. Each scheme... name is an alias for the
corresponding racket... binding.
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 racketblock. 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 |
(racketblock |
;; 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
(racketblock ....) instead of
@racketblock[....]
because the @-reader would drop comments within the
racketblock before giving
scribble/comment-reader a chance to convert them.