4.3.1 Typesetting Code
| (codeblock option ... str-expr ...+) |
| |
| option | | = | | #:keep-lang-line? keep-expr | | | | | | | #:indent indent-expr | | | | | | | #:expand expand-expr | | | | | | | #:context context-expr |
|
| |
| | expand-expr | | : | | (or/c #f (syntax-object? . -> . syntax-object?)) |
| | context-expr | | : | | syntax-object? |
|
Parses the code formed by the strings produced by the
str-exprs as a Racket module (roughly) and produces a
block that typesets the code. The
str-exprs should
normally start with
#lang to determine the reader syntax for
the module, but the resulting “module” need not expand or
compile—
except as needed by
expand-expr. If
expand-expr is omitted or produces false, then the input
formed by
str-expr is read until an end-of-file is
encountered, otherwise a single form is read from the input.
When keep-expr produces a true value (the default), the first
line in the input (which is typically #lang) is preserved in
the typeset output, otherwise the first line is dropped. The typeset
code is indented by the amount specified by indent-expr,
which defaults to 2.
When expand-expr produces #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 context-expr. The default context-expr
has the same lexical context as the first str-expr.
When 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|{ |
| #lang scribble/manual |
| @codeblock{ |
| #lang scribble/manual |
| @title{Hello} |
| } |
| }| |
produces the typeset result
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, etc., but colors the typeset text as a
result (i.e., a single color with no hyperlinks) instead of code.
| (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 result (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.3.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.