4.4 Racket

(require scribble/racket)	package: scribble-lib
(require scribble/scheme)

The scribble/racket library (or scribble/scheme for backward compatibility) provides utilities for typesetting Racket code. The scribble/manual forms provide a higher-level interface.

syntax
(define-code id typeset-expr)
(define-code id typeset-expr uncode-id)
(define-code id typeset-expr uncode-id d->s-expr)
(define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)

Binds id to a form similar to racket or racketblock for typesetting code. The form generated by define-code handles source-location information, escapes via unquote by default, preserves binding and property information, and supports element transformers.

The supplied typeset-expr expression should produce a procedure that performs the actual typesetting. This expression is normally to-element or to-paragraph. The argument supplied to typeset-expr is normally a syntax object, but more generally it is the result of applying d->s-expr.

The optional uncode-id specifies the default escape from literal code to be recognized by id, and the default for uncode-id is unsyntax. A use of the id form can specify an alternate escape via #:escape, as in racketblock and racket.

The optional d->s-expr should produce a procedure that accepts three arguments suitable for datum->syntax: a syntax object or #f, an arbitrary value, and a vector for a source location. The result should record as much or as little of the argument information as needed by typeset-expr to typeset the code. Normally, d->s-expr is datum->syntax.

The stx-prop-expr should produce a procedure for recording a 'paren-shape property when the source expression uses with id has such a property. The default is syntax-property.

procedure
(to-paragraph v
[ #:expr? expr?
#:escapes? escapes?
#:color? color?
#:wrap-elem wrap-elem]) → block?
  v : any/c
  expr? : any/c = #f
  escapes? : any/c = #t
  color? : any/c = #t
  wrap-elem : (element? . -> . element?) = (lambda (e) e)

Typesets an S-expression that is represented by a syntax object, where source-location information in the syntax object controls the generated layout. When source-location information is not available, default spacing is used (in the same single-line style as to-element).

Identifiers that have for-label bindings are typeset and hyperlinked based on definitions declared elsewhere (via defproc, defform, etc.). Unless escapes? is #f, the identifiers code:line, code:comment, code:blank, code:hilite, and code:quote are handled as in racketblock, as are identifiers that start with _.

In addition, the given v can contain var-id, shaped-parens, just-context, or literal-syntax structures to be typeset specially (see each structure type for details), or it can contain element structures that are used directly in the output.

If expr? is true, then v is rendered in expression style, much like print with the print-as-expression parameter set to #t. In that case, for-label bindings on identifiers are ignored, since the identifiers are all quoted in the output. Typically, expr? is set to true for printing result values.

If color? is #f, then the output is typeset without coloring.

The wrap-elem procedure is applied to each element constructed for the resulting block. When combined with #f for color?, for example, the wrap-elem procedure can be used to give a style to an element.

procedure
((to-paragraph/prefix prefix1
prefix
suffix)
v
[ #:expr? expr?
#:escapes? escapes?
#:color? color?
#:wrap-elem wrap-elem]) → block?
  prefix1 : any/c
  prefix : any/c
  suffix : any/c
  v : any/c
  expr? : any/c = #f
  escapes? : any/c = #t
  color? : any/c = #f
  wrap-elem : (element? . -> . element?) = (lambda (e) e)

Like to-paragraph, but prefix1 is prefixed onto the first line, prefix is prefix to any subsequent line, and suffix is added to the end. The prefix1, prefix, and suffix arguments are used as content, except that if suffix is a list of elements, it is added to the end on its own line.

procedure
(to-element v
[ #:expr? expr?
#:escapes? escapes?
#:defn? defn?]) → element?
  v : any/c
  expr? : any/c = #f
  escapes? : any/c = #t
  defn? : any/c = #f

Like to-paragraph, except that source-location information is mostly ignored, since the result is meant to be inlined into a paragraph. If defn? is true, then an identifier is styled as a definition site.

procedure
(to-element/no-color v
[ #:expr? expr?
#:escapes? escapes?]) → element?
  v : any/c
  expr? : any/c = #f
  escapes? : any/c = #t

Like to-element, but for-syntax bindings are ignored, and the generated text is uncolored. This variant is typically used to typeset results.

struct
(struct var-id (sym)
#:extra-constructor-name make-var-id)
sym : (or/c symbol? identifier?)

When to-paragraph and variants encounter a var-id structure, it is typeset as sym in the variable font, like racketvarfont—unless the var-id appears under quote or quasiquote, in which case sym is typeset as a symbol.

struct
(struct shaped-parens (val shape)
    #:extra-constructor-name make-shaped-parens)
  val : any/c
  shape : char?

When to-paragraph and variants encounter a shaped-parens structure, it is typeset like a syntax object that has a 'paren-shape property with value shape.

struct
(struct long-boolean (val)
#:extra-constructor-name make-long-boolean)
val : boolean?

When to-paragraph and variants encounter a long-boolean structure, it is typeset as #true or #false, as opposed to #t or #f.

struct
(struct just-context (val context)
    #:extra-constructor-name make-just-context)
  val : any/c
  context : syntax?

When to-paragraph and variants encounter a just-context structure, it is typeset using the source-location information of val just the lexical context of ctx.

struct
(struct literal-syntax (stx)
#:extra-constructor-name make-literal-syntax)
stx : any/c

When to-paragraph and variants encounter a literal-syntax structure, it is typeset as the string form of stx. This can be used to typeset a syntax-object value in the way that the default printer would represent the value.

procedure
(element-id-transformer? v) → boolean?
v : any/c

Provided for-syntax; returns #t if v is an element transformer created by make-element-id-transformer, #f otherwise.

procedure
(make-element-id-transformer proc) → element-id-transformer?
proc : (syntax? . -> . syntax?)

Provided for-syntax; creates an element transformer. When an identifier has a transformer binding to an element transformer, then forms generated by define-code (including racket and racketblock) typeset the identifier by applying the proc to the identifier. The result must be an expression whose value, typically an element, is passed on to functions like to-paragraph .

procedure
(variable-id? v) → boolean?
v : any/c

Provided for-syntax; returns #t if v is an element transformer created by make-variable-id, #f otherwise.

procedure
(make-variable-id sym) → variable-id?
sym : (or/c symbol? identifier?)

Provided for-syntax; like make-element-id-transformer for a transformer that produces sym typeset as a variable (like racketvarfont)—unless it appears under quote or quasiquote, in which case sym is typeset as a symbol.

value
output-color : style?
value
input-color : style?
value
input-background-color : style?
value
no-color : style?
value
reader-color : style?
value
result-color : style?
value
keyword-color : style?
value
comment-color : style?
value
paren-color : style?
value
meta-color : style?
value
value-color : style?
value
symbol-color : style?
value
variable-color : style?
value
opt-color : style?
value
error-color : style?
value
syntax-link-color : style?
value
value-link-color : style?
value
module-color : style?
value
module-link-color : style?
value
block-color : style?
value
highlighted-color : style?

Styles that are used for coloring Racket programs, results, and I/O.

top ← prev up next →

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.1	Getting Started with Documentation
4.2	Style Guide
4.3	Manual Forms
4.4	Racket
4.5	Evaluation and Examples
4.6	In-Source Documentation
4.7	BNF Grammars
4.8	Compatibility Libraries