4.2.1 Typesetting Code

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

▼ | 4.2 | Manual Forms

4.2.1 | Typesetting Code
4.2.2 | Documenting Modules
4.2.3 | Documenting Forms, Functions, Structure Types, and Values
4.2.4 | Documenting Classes and Interfaces
4.2.5 | Documenting Signatures
4.2.6 | Various String Forms
4.2.7 | Links
4.2.8 | Indexing
4.2.9 | Bibliography
4.2.10 | Version History
4.2.11 | Miscellaneous
4.2.12 | Index-Entry Descriptions
4.2.13 | Manual Rendering Style

► | 4.2.1 | Typesetting Code

4.2.1.1 | #lang-Specified Code
4.2.1.2 | Racket Code
4.2.1.3 | Preserving Comments
4.2.1.4 | Code Fonts and Styles

On this page:

4.2.1.1`` #lang-Specified Code
codeblock
codeblock0
code
typeset-code
4.2.1.2`` Racket Code
racketblock
RACKETBLOCK
racketblock0
RACKETBLOCK0
racketresultblock
racketresultblock0
RACKETRESULTBLOCK
RACKETRESULTBLOCK0
racketinput
RACKETINPUT
racketinput0
RACKETINPUT0
racketmod
racketmod0
racket
RACKET
racketresult
racketid
schemeblock
SCHEMEBLOCK
schemeblock0
SCHEMEBLOCK0
schemeinput
schememod
scheme
SCHEME
schemeresult
schemeid
4.2.1.3`` Preserving Comments
4.2.1.4`` Code Fonts and Styles
racketmodname
racketmodlink
litchar
racketfont
racketplainfont
racketvalfont
racketresultfont
racketidfont
racketvarfont
racketkeywordfont
racketparenfont
racketoptionalfont
racketmetafont
racketcommentfont
racketerror
racketmodfont
racketoutput
procedure
var
svar
schememodname
schememodlink
schemefont
schemevalfont
schemeresultfont
schemeidfont
schemevarfont
schemekeywordfont
schemeparenfont
schemeoptionalfont
schememetafont
schemeerror
schememodfont
schemeoutput

top contents ← prev up next →

##### 4.2.1`` Typesetting Code🔗ℹ

The codeblock and code forms (see #lang-Specified 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 for-label imports.

The racketblock and racket forms (see Racket Code) typeset S-expression code roughly verbatim, but roughly by quoting the source term with syntax. Identifiers in the quoted S-expression are hyperlinked via for-label imports.

The two different approaches to typesetting code—codeblock and code versus racketblock and racket—have different advantages and disadvantages:

- The codeblock and code forms work with non-S-expression syntax, and they give authors more control over output (e.g., the literal number 2/4 is not normalized to 1/2). The codeblock and code forms do not yet support escapes to Scribble element mode, and they cannot adapt spacing based on the width of elements in escapes.

- The racketblock and racket forms are more efficient and allow escapes to Scribble element mode. The racketblock and 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 2/4 is normalized to 1/2).

##### 4.2.1.1`` #lang-Specified Code🔗ℹ

> syntax (codeblock option ... str-expr ...+)
> option |  | = |  | #:keep-lang-line? keep-expr
> |  | | |  | #:indent indent-expr
> |  | | |  | #:expand expand-expr
> |  | | |  | #:context context-expr
> |  | | |  | #:line-numbers line-number-expr
> |  | | |  | #:line-number-sep line-number-sep-expr
> > | 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 str-exprs as a Racket module (roughly) and produces a block that typesets the code inset via nested with the style 'code-inset. See also typeset-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 0.

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 line-number-expr is true, line number is enabled starting from line-number-expr, and line-number-sep-expr controls the separation (in spaces; defaults to 1) between the line numbers and code.

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

> #lang scribble/manual
> @codeblock{
> #lang scribble/manual
> @title{Hello}
> }

> syntax (codeblock0 option ... str-expr ...+)

Like codeblock, but without the 'code-inset nested wrapper.

> syntax (code option ... str-expr ...+)
> option |  | = |  | #:lang lang-line-expr
> |  | | |  | #:expand expand-expr
> |  | | |  | #:context context-expr
> > | lang-line-expr |  | : |  | (or/c #f string?)
> > | expand-expr |  | : |  | (or/c #f (syntax? . -> . syntax?))
> > | context-expr |  | : |  | (or/c #f syntax?)

Like codeblock, but produces content instead of a block. No #lang line should appear in the string content; instead, it should be provided #:lang (as a string without "#lang ") if needed, and the #lang line is always stripped from the output when provided. Also, each newline in str-exprs is collapsed along with all surrounding whitespace to a single space.

For example,

> This is @code[#:lang "at-exp racket"]|{@bold{Hi}}|'s result:
> @bold{Hi}.

produces the typeset result

> This is @bold{Hi}’s result: Hi.

> > procedure
> > (typeset-code | [ | #:context context |
> > |  | #:expand expand |
> > |  | #:indent indent |
> > |  | #:keep-lang-line? keep? |
> > |  | #:line-numbers line-numbers |
> > |  | #:line-number-sep line-number-sep |
> > |  | #:block? return-block?] |
> > |  | strs ...) |
> → (if return-block? block? element?)
> context : (or/c #f syntax?) = #f
> expand : (or/c #f (syntax? . -> . syntax?)) = #f
> indent : exact-nonnegative-integer? = 2
> keep? : any/c = #t
> line-numbers : (or/c #f exact-nonnegative-integer?) = #f
> line-number-sep : exact-nonnegative-integer? = 1
> return-block? : any/c = #t
> strs : string?

A function-based version of codeblock, allowing you to compute the strs arguments.

Unlike codeblock, the default context argument (#f) implies that the context is untouched and the return-block? argument determines the result structure. The other arguments are treated the same way as codeblock.

##### 4.2.1.2`` Racket Code🔗ℹ

> syntax (racketblock maybe-escape datum ...)
> maybe-escape |  | = |  |
> |  | | |  | #:escape escape-id

Typesets the datum sequence as a table of Racket code inset via nested with the style 'code-inset. The source locations of the datums determine the generated layout. For example,

> (racketblock
> (define (loop x)
> (loop (not x))))

produces the output

> (define (loop x)
> (loop (not x)))

with the (loop (not x)) indented under define, because that’s the way it is idented the use of racketblock. Source-location span information is used to preserve #true versus #t and #false versus #f; span information is also used heuristically to add #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 2/4 as 1/2. 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 form.

> > > See also quote-syntax/keep-srcloc for use in a macro to preserve source-location information in a template.

In the above example, define is typeset as a keyword (in 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 its definition in the reference manual.

Like other forms defined via define-code, racketblock expands identifiers that are bound as element transformers.

An #:escape clause specifies an identifier to escape back to an expression that produces an element. By default, the escape identifier is unsyntax. For example,

> (racketblock
> (+ 1 #,(elem (racket x) (subscript "2"))))

produces

> (+ 1 x2)

The escape-id that defaults to unsyntax is recognized via free-identifier=?, so a binding can hide the escape behavior:

> (racketblock
> (let ([unsyntax #f])
> (racketblock
> #'(+ 1 #,x))))

The RACKETBLOCK form’s default escape 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 content) typesets like content, but colored as a comment and prefixed with a semi-colon. A typical content escapes from Racket-typesetting mode using unsyntax and produces a string, an element using elem, or a paragraph using t:

  (code:comment @#,elem{this is a comment})

  (Note that @#,foo{...} reads as #,(foo "...").)

- (code:comment2 content) is like code:comment, but uses two semi-colons to prefix the comment.

- (code:comment# content) is like code:comment, but uses #; to prefix the comment.

- (code:contract datum ...) typesets like the sequence of datums (including its coloring), but prefixed with a semi-colon.

- (code:contract# datum) is like code:contract, but uses #; to prefix the contract.

- code:blank 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.

Changed in version 1.9 of package scribble-lib: Added heuristic for adding #i to inexact numbers.

> syntax (RACKETBLOCK maybe-escape datum ...)

Like racketblock, but with the default expression escape UNSYNTAX instead of unsyntax.

> syntax (racketblock0 maybe-escape datum ...)

Like racketblock, but without insetting the code via nested.

> syntax (RACKETBLOCK0 maybe-escape datum ...)

Like RACKETBLOCK, but without insetting the code via nested.

> syntax (racketresultblock maybe-escape datum ...)
> syntax (racketresultblock0 maybe-escape datum ...)
> syntax (RACKETRESULTBLOCK maybe-escape datum ...)
> syntax (RACKETRESULTBLOCK0 maybe-escape datum ...)

Like racketblock, etc., but colors the typeset text as a result (i.e., a single color with no hyperlinks) instead of code.

Unlike racketblock, racketresultblock and RACKETRESULTBLOCK implement indentation by adding an (hspace 2) to the start of each line, instead of using nested with the 'code-inset style. To get formatting more like racketblock and racketinput, use (nested #:style 'code-inset (racketresultblock0 datum ...)) instead of (racketresultblock datum ...).

> syntax (racketinput maybe-escape datum ...)
> syntax (RACKETINPUT maybe-escape datum ...)

Like racketblock and RACKETBLOCK, but the datums are typeset after a prompt representing a REPL.

> syntax (racketinput0 maybe-escape datum ...)
> syntax (RACKETINPUT0 maybe-escape datum ...)

Like racketinput and RACKETINPUT, but without insetting the code via nested.

> syntax (racketmod maybe-file maybe-escape lang datum ...)
> maybe-file |  | = |  |
> |  | | |  | #:file filename-expr
> maybe-escape |  | = |  |
> |  | | |  | #:escape escape-id

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.

> syntax (racketmod0 maybe-file maybe-escape lang datum ...)

Like racketmod, but without insetting the code via nested.

> syntax (racket maybe-escape datum ...)

Like racketblock, but typeset on a single line and wrapped with its enclosing paragraph, independent of the formatting of datum.

> syntax (RACKET maybe-escape datum ...)

Like racket, but with the UNSYNTAX escape like racketblock.

> syntax (racketresult maybe-escape datum ...)

Like racket, but typeset as a result (i.e., a single color with no hyperlinks).

> syntax (racketid maybe-escape datum ...)

Like racket, but typeset as an unbound identifier (i.e., no coloring or hyperlinks).

> syntax (schemeblock maybe-escape datum ...)
> syntax (SCHEMEBLOCK maybe-escape datum ...)
> syntax (schemeblock0 maybe-escape datum ...)
> syntax (SCHEMEBLOCK0 maybe-escape datum ...)
> syntax (schemeinput maybe-escape datum ...)
> syntax (schememod lang maybe-escape datum ...)
> syntax (scheme maybe-escape datum ...)
> syntax (SCHEME maybe-escape datum ...)
> syntax (schemeresult maybe-escape datum ...)
> syntax (schemeid maybe-escape datum ...)

Compatibility aliases. Each scheme... name is an alias for the corresponding racket... binding.

##### 4.2.1.3`` Preserving Comments🔗ℹ

#reader scribble/comment-reader | package: scribble-lib

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

> ; This is not a pipe
> (make-pipe)

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.

The implementation of scribble/comment-reader uses unsyntax to typeset comments. When using scribble/comment-reader with, for instance, RACKETBLOCK, unsyntax does not escape, since RACKETBLOCK uses UNSYNTAX as its escape form. You can declare an escape identifier for scribble/comment-reader with #:escape-id. For example,

@#reader scribble/comment-reader #:escape-id UNSYNTAX
(RACKETBLOCK
(define-syntax (m stx)
(syntax-case stx ()
[(_ x)
;; Well this was silly
#`(#,x)]))
)

generates

> (define-syntax (m stx)
> (syntax-case stx ()
> [(_ x)
> ; Well this was silly
> #`(#,x)]))

##### 4.2.1.4`` Code Fonts and Styles🔗ℹ

> syntax (racketmodname datum maybe-indirect)
> (racketmodname (unsyntax expr) maybe-indirect)
> maybe-indirect |  | = |  |
> |  | | |  | #:indirect

Like racket, but typeset as a module path and without special treatment of identifiers (such as code:blank or identifiers that start with _). If datum is an identifier or expr produces a symbol, then it is hyperlinked to the module path’s definition as created by defmodule.

If #:indirect is specified, then the hyperlink is given the 'indirect-link style property, which makes the hyperlink’s resolution in HTML potentially delayed; see 'indirect-link for link-element.

Changed in version 1.21 of package scribble-lib: Disabled racket-style special treatment of identifiers.

> syntax (racketmodlink datum pre-content-expr ...)

Like racketmodname, 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.

> procedure (litchar str ...) → element?
> str : string?

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 when documenting a reader extension.

> procedure (racketfont pre-content ...) → element?
> pre-content : pre-content?

The same as (tt pre-content ...), which applies the 'tt style to immediate strings and symbols among the pre-content arguments. Beware that pre-content is decoded as usual, making racketfont a poor choice for typesetting literal code.

> procedure (racketplainfont pre-content ...) → element?
> pre-content : pre-content?

Applies the 'tt style to pre-content. Beware that pre-content is decoded as usual, making racketplainfont a poor choice for typesetting literal code directly but useful for implementing code-formatting functions.

Added in version 1.6 of package scribble-lib.

> procedure (racketvalfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as a value.

> > procedure
> > (racketresultfont | [ | #:decode? decode?] |  |  |  |
> > |  | pre-content ...) |  | → |  | element?
> decode? : boolean? = #t
> pre-content : pre-content?

Like racketplainfont, but colored as a REPL result. When decode? is #f, then unlike racketplainfont, racketresultfont avoids decodeing its argument.

> procedure (racketidfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as an identifier.

> procedure (racketvarfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as a variable (i.e., an argument or sub-form in a procedure being documented).

> procedure (racketkeywordfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as a syntactic form name.

> procedure (racketparenfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored like parentheses.

> procedure (racketoptionalfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as optional.

Added in version 1.36 of package scribble-lib.

> procedure (racketmetafont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as meta-syntax, such as backquote or unquote.

> procedure (racketcommentfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as a comment.

> procedure (racketerror pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as error-message text.

> procedure (racketmodfont pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as module name.

> procedure (racketoutput pre-content ...) → element?
> pre-content : pre-content?

Like racketplainfont, but colored as output.

> procedure (procedure pre-content ...) → element?
> pre-content : pre-content?

Typesets decoded pre-content as a procedure name in a REPL result (e.g., in typewriter font with a #<procedure: prefix and > suffix.).

> syntax (var datum)

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.

> syntax (svar datum)

Like var, but for subform non-terminals in a form definition.

> syntax (schememodname datum)
> (schememodname (unsyntax expr))
> syntax (schememodlink datum pre-content-expr ...)
> procedure (schemefont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemevalfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemeresultfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemeidfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemevarfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemekeywordfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemeparenfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemeoptionalfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schememetafont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemeerror pre-content ...) → element?
> pre-content : pre-content?
> procedure (schememodfont pre-content ...) → element?
> pre-content : pre-content?
> procedure (schemeoutput pre-content ...) → element?
> pre-content : pre-content?

Compatibility aliases. Each scheme... name is an alias for the corresponding racket... binding.
top contents ← prev up next →