4.2.1 Typesetting Code

4.2.1.1#lang-Specified Code🔗 i

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 |{

#langscribble/manual

@codeblock{

#langscribble/manual

@title{Hello}

}

}|

produces the typeset result

#lang scribble/manual

@codeblock {

#langscribble/manual

@title {Hello}

}

For example,

Thisis@code [#:lang"at-expracket"]|{@bold{Hi}}|'sresult:

@bold {Hi}.

produces the typeset result

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

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.2Racket Code🔗 i

(racketblock

(define (loopx)

(loop(not x))))

produces the output

(define (loopx)

(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

(+ 1x2)

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:linedatum... ) typesets as the sequence of datums (i.e., without the code:line wrapper).

• ( code:commentcontent) 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:comment2content) 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:contractdatum... ) 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:hilitedatum) typesets like datum, but with a background highlight.

• ( code:quotedatum) typesets like (quotedatum), 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.

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... ).

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.

4.2.1.3Preserving Comments🔗 i

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,

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,

generates

(define-syntax (mstx)

(syntax-case stx()

[(_ x)

;Well this was silly

#`(#,x)]))

4.2.1.4Code Fonts and Styles🔗 i

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.

Added in version 1.6 of package scribble-lib.