► |  | Scribble: The Racket Documentation Tool

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

▼ | 4 | Scribbling Documentation

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

On this page:

define-code
to-paragraph
to-paragraph/ prefix
to-element
to-element/ no-color
var-id
shaped-parens
long-boolean
just-context
literal-syntax
element-id-transformer?
make-element-id-transformer
variable-id?
make-variable-id
output-color
input-color
input-background-color
no-color
reader-color
result-color
keyword-color
comment-color
paren-color
meta-color
value-color
symbol-color
variable-color
opt-color
error-color
syntax-link-color
value-link-color
module-color
module-link-color
block-color
highlighted-color

top ← prev up next →

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

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 →