commit 4b7c597f04c8f6db046b592924e519d24b813615
parent a2f330a9c11a7adf9180bcea139941c810bd18c2
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 15 Aug 2011 18:54:32 -0600
add an `#:escape' clause to all `schemeblock'-like forms
original commit: a1eaecb337f2d4e55c7f8638b70226c76554f204
Diffstat:
6 files changed, 211 insertions(+), 193 deletions(-)
diff --git a/collects/scribble/eval.rkt b/collects/scribble/eval.rkt
@@ -386,45 +386,48 @@
(define-syntax racketinput*
(syntax-rules (eval:alts code:comment)
- [(_ (code:comment . rest)) (racketblock0 (code:comment . rest))]
- [(_ (eval:alts a b)) (racketinput* a)]
- [(_ e) (racketinput0 e)]))
+ [(_ #:escape id (code:comment . rest)) (racketblock0 #:escape id (code:comment . rest))]
+ [(_ #:escape id (eval:alts a b)) (racketinput* #:escape id a)]
+ [(_ #:escape id e) (racketinput0 #:escape id e)]))
(define-code racketblock0+line (to-paragraph/prefix "" "" (list " ")))
(define-syntax (racketdefinput* stx)
(syntax-case stx (define define-values define-struct)
- [(_ (define . rest))
+ [(_ #:escape id (define . rest))
(syntax-case stx ()
- [(_ e) #'(racketblock0+line e)])]
- [(_ (define-values . rest))
+ [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])]
+ [(_ #:escape id (define-values . rest))
(syntax-case stx ()
- [(_ e) #'(racketblock0+line e)])]
- [(_ (define-struct . rest))
+ [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])]
+ [(_ #:escape id (define-struct . rest))
(syntax-case stx ()
- [(_ e) #'(racketblock0+line e)])]
- [(_ (code:line (define . rest) . rest2))
+ [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])]
+ [(_ #:escape id (code:line (define . rest) . rest2))
(syntax-case stx ()
- [(_ e) #'(racketblock0+line e)])]
- [(_ e) #'(racketinput* e)]))
+ [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])]
+ [(_ #:escape id e) #'(racketinput* #:escape id e)]))
(define (do-titled-interaction who inset? ev t shows evals)
(interleave inset? t shows (map (do-eval ev who) evals)))
(define-syntax titled-interaction
(syntax-rules ()
- [(_ who inset? #:eval ev t racketinput* e ...)
+ [(_ who inset? t racketinput* #:eval ev #:escape unsyntax-id e ...)
(do-titled-interaction
- 'who inset? ev t (list (racketinput* e) ...) (list (quote-expr e) ...))]
+ 'who inset? ev t (list (racketinput* #:escape unsyntax-id e) ...) (list (quote-expr e) ...))]
+ [(_ who inset? t racketinput* #:eval ev e ...)
+ (titled-interaction
+ who inset? t racketinput* #:eval ev #:escape unsyntax e ...)]
+ [(_ who inset? t racketinput* #:escape unsyntax-id e ...)
+ (titled-interaction
+ who inset? t racketinput* #:eval (make-base-eval) #:escape unsyntax-id e ...)]
[(_ who inset? t racketinput* e ...)
(titled-interaction
- who inset? #:eval (make-base-eval) t racketinput* e ...)]))
+ who inset? t racketinput* #:eval (make-base-eval) e ...)]))
(define-syntax (-interaction stx)
(syntax-case stx ()
- [(_ who #:eval ev e ...)
- (syntax/loc stx
- (titled-interaction who #f #:eval ev #f racketinput* e ...))]
[(_ who e ...)
(syntax/loc stx
(titled-interaction who #f #f racketinput* e ...))]))
@@ -437,57 +440,70 @@
(syntax-case stx ()
[(H e ...) (syntax/loc stx (-interaction H e ...))]))
-(define-syntax racketblock+eval
+(define-syntax racketblockX+eval
(syntax-rules ()
- [(_ #:eval ev e ...)
+ [(_ racketblock #:eval ev #:escape unsyntax-id e ...)
(let ([eva ev])
(#%expression
(begin (interaction-eval #:eval eva e) ...
- (racketblock e ...))))]
+ (racketblock #:escape unsyntax-id e ...))))]
+ [(_ racketblock #:eval ev e ...)
+ (racketblockX+eval racketblock #:eval ev #:escape unsyntax e ...)]
+ [(_ racketblock #:escape unsyntax-id e ...)
+ (racketblockX+eval racketblock #:eval (make-base-eval) #:escape unsyntax-id e ...)]
+ [(_ racketblock e ...)
+ (racketblockX+eval racketblock #:eval (make-base-eval) #:escape unsyntax e ...)]))
+
+(define-syntax racketblock+eval
+ (syntax-rules ()
[(_ e ...)
- (racketblock+eval #:eval (make-base-eval) e ...)]))
+ (racketblockX+eval racketblock e ...)]))
(define-syntax racketblock0+eval
(syntax-rules ()
- [(_ #:eval ev e ...)
- (let ([eva ev])
- (#%expression (begin (interaction-eval #:eval eva e) ...
- (racketblock0 e ...))))]
[(_ e ...)
- (racketblock0+eval #:eval (make-base-eval) e ...)]))
+ (racketblockX+eval racketblock0 e ...)]))
(define-syntax racketmod+eval
(syntax-rules ()
- [(_ #:eval ev name e ...)
+ [(_ #:eval ev #:escape unsyntax-id name e ...)
(let ([eva ev])
(#%expression
(begin (interaction-eval #:eval eva e) ...
- (racketmod name e ...))))]
+ (racketmod #:escape unsyntax-id name e ...))))]
+ [(_ #:eval ev name e ...)
+ (racketmod+eval #:eval ev #:escape unsyntax name e ...)]
+ [(_ #:escape unsyntax-id name e ...)
+ (racketmod+eval #:eval (make-base-eval) #:escape unsyntax-id name e ...)]
[(_ name e ...)
- (racketmod+eval #:eval (make-base-eval) name e ...)]))
-
-(define-syntax (def+int stx)
- (syntax-case stx ()
- [(H #:eval ev def e ...)
- (syntax/loc stx
- (let ([eva ev])
- (column (list (racketblock0+eval #:eval eva def)
- blank-line
- (-interaction H #:eval eva e ...)))))]
- [(_ def e ...)
- (syntax/loc stx (def+int #:eval (make-base-eval) def e ...))]))
+ (racketmod+eval #:eval (make-base-eval) #:escape unsyntax name e ...)]))
(define-syntax (defs+int stx)
(syntax-case stx ()
- [(H #:eval ev [def ...] e ...)
+ [(H #:eval ev #:escape unsyntax-id [def ...] e ...)
(syntax/loc stx
(let ([eva ev])
- (column (list (racketblock0+eval #:eval eva def ...)
+ (column (list (racketblock0+eval #:eval eva #:escape unsyntax-id def ...)
blank-line
- (-interaction H #:eval eva e ...)))))]
+ (-interaction H #:eval eva #:escape unsyntax-id e ...)))))]
+ [(H #:eval ev [def ...] e ...)
+ (syntax/loc stx (defs+int #:eval ev #:escape unsyntax [def ...] e ...))]
+ [(_ #:escape unsyntax-id [def ...] e ...)
+ (syntax/loc stx (defs+int #:eval (make-base-eval) #:escape unsyntax-id [def ...] e ...))]
[(_ [def ...] e ...)
(syntax/loc stx (defs+int #:eval (make-base-eval) [def ...] e ...))]))
+(define-syntax def+int
+ (syntax-rules ()
+ [(H #:eval ev #:escape unsyntax-id def e ...)
+ (defs+int #:eval ev #:escape unsyntax-id [def] e ...)]
+ [(H #:eval ev def e ...)
+ (defs+int #:eval ev [def] e ...)]
+ [(H #:escape unsyntax-id def e ...)
+ (defs+int #:escape unsyntax-id [def] e ...)]
+ [(H def e ...)
+ (defs+int [def] e ...)]))
+
(define example-title
(make-paragraph (list "Example:")))
(define examples-title
@@ -500,37 +516,23 @@
(define-syntax (examples stx)
(syntax-case stx ()
- [(H #:eval ev e ...)
- (syntax/loc stx
- (titled-interaction
- H #t #:eval ev (pick-example-title e ...) racketinput* e ...))]
[(H e ...)
(syntax/loc stx
(titled-interaction
H #t (pick-example-title e ...) racketinput* e ...))]))
(define-syntax (examples* stx)
(syntax-case stx ()
- [(H #:eval ev example-title e ...)
- (syntax/loc stx
- (titled-interaction H #t #:eval ev example-title racketinput* e ...))]
[(H example-title e ...)
(syntax/loc stx
(titled-interaction H #t example-title racketinput* e ...))]))
(define-syntax (defexamples stx)
(syntax-case stx ()
- [(H #:eval ev e ...)
- (syntax/loc stx
- (titled-interaction
- H #t #:eval ev (pick-example-title e ...) racketdefinput* e ...))]
[(H e ...)
(syntax/loc stx
(titled-interaction
H #t (pick-example-title e ...) racketdefinput* e ...))]))
(define-syntax (defexamples* stx)
(syntax-case stx ()
- [(H #:eval ev example-title e ...)
- (syntax/loc stx
- (titled-interaction H #t #:eval ev example-title racketdefinput* e ...))]
[(H example-title e ...)
(syntax/loc stx
(titled-interaction H #t example-title racketdefinput* e ...))]))
diff --git a/collects/scribble/private/manual-scheme.rkt b/collects/scribble/private/manual-scheme.rkt
@@ -89,7 +89,7 @@
(define-syntax (racketmod0 stx)
(syntax-case stx ()
- [(_ #:file filename lang rest ...)
+ [(_ #:file filename #:escape unsyntax-id lang rest ...)
(with-syntax ([modtag (datum->syntax
#'here
`(unsyntax (make-element
@@ -106,8 +106,10 @@
(quasisyntax/loc stx
(filebox
filename
- #,(syntax/loc stx (racketblock0 modtag rest ...))))
- (syntax/loc stx (racketblock0 modtag rest ...))))]
+ #,(syntax/loc stx (racketblock0 #:escape unsyntax-id modtag rest ...))))
+ (syntax/loc stx (racketblock0 #:escape unsyntax-id modtag rest ...))))]
+ [(_ #:file filename lang rest ...)
+ (syntax/loc stx (racketmod0 #:file #f #:escape unsyntax lang rest ...))]
[(_ lang rest ...)
(syntax/loc stx (racketmod0 #:file #f lang rest ...))]))
diff --git a/collects/scribble/racket.rkt b/collects/scribble/racket.rkt
@@ -914,56 +914,64 @@
,(syntax-column v)
,(syntax-position v)
,(syntax-span v))))
- (define (stx->loc-s-expr v)
- (let ([slv (and (identifier? v)
- (syntax-local-value v (lambda () #f)))])
- (cond
- [(variable-id? slv)
- (wrap-loc v #f `(,#'make-var-id ',(variable-id-sym slv)))]
- [(element-id-transformer? slv)
- (wrap-loc v #f ((element-id-transformer-proc slv) v))]
- [(syntax? v)
- (let ([mk (wrap-loc
- v
- `(quote-syntax ,(datum->syntax v 'defcode))
- (syntax-case v (uncode)
- [(uncode e) #'e]
- [else (stx->loc-s-expr (syntax-e v))]))])
- (let ([prop (syntax-property v 'paren-shape)])
- (if prop
- `(,#'stx-prop ,mk 'paren-shape ,prop)
- mk)))]
- [(null? v) 'null]
- [(list? v) `(list . ,(map stx->loc-s-expr v))]
- [(pair? v) `(cons ,(stx->loc-s-expr (car v))
- ,(stx->loc-s-expr (cdr v)))]
- [(vector? v) `(vector ,@(map
- stx->loc-s-expr
- (vector->list v)))]
- [(and (struct? v) (prefab-struct-key v))
- `(make-prefab-struct (quote ,(prefab-struct-key v))
- ,@(map
- stx->loc-s-expr
- (cdr (vector->list (struct->vector v)))))]
- [(box? v) `(box ,(stx->loc-s-expr (unbox v)))]
- [(hash? v) `(,(cond
- [(hash-eq? v) 'make-immutable-hasheq]
- [(hash-eqv? v) 'make-immutable-hasheqv]
- [else 'make-immutable-hash])
- (list
- ,@(hash-map
- v
- (lambda (k v)
- `(cons (quote ,k)
- ,(stx->loc-s-expr v))))))]
- [else `(quote ,v)])))
- (define (cvt s)
- (datum->syntax #'here (stx->loc-s-expr s) #f))
+ (define (stx->loc-s-expr/esc v uncode-id)
+ (define (stx->loc-s-expr v)
+ (let ([slv (and (identifier? v)
+ (syntax-local-value v (lambda () #f)))])
+ (cond
+ [(variable-id? slv)
+ (wrap-loc v #f `(,#'make-var-id ',(variable-id-sym slv)))]
+ [(element-id-transformer? slv)
+ (wrap-loc v #f ((element-id-transformer-proc slv) v))]
+ [(syntax? v)
+ (let ([mk (wrap-loc
+ v
+ `(quote-syntax ,(datum->syntax v 'defcode))
+ (syntax-case v ()
+ [(esc e)
+ (and (identifier? #'esc)
+ (free-identifier=? #'esc uncode-id))
+ #'e]
+ [else (stx->loc-s-expr (syntax-e v))]))])
+ (let ([prop (syntax-property v 'paren-shape)])
+ (if prop
+ `(,#'stx-prop ,mk 'paren-shape ,prop)
+ mk)))]
+ [(null? v) 'null]
+ [(list? v) `(list . ,(map stx->loc-s-expr v))]
+ [(pair? v) `(cons ,(stx->loc-s-expr (car v))
+ ,(stx->loc-s-expr (cdr v)))]
+ [(vector? v) `(vector ,@(map
+ stx->loc-s-expr
+ (vector->list v)))]
+ [(and (struct? v) (prefab-struct-key v))
+ `(make-prefab-struct (quote ,(prefab-struct-key v))
+ ,@(map
+ stx->loc-s-expr
+ (cdr (vector->list (struct->vector v)))))]
+ [(box? v) `(box ,(stx->loc-s-expr (unbox v)))]
+ [(hash? v) `(,(cond
+ [(hash-eq? v) 'make-immutable-hasheq]
+ [(hash-eqv? v) 'make-immutable-hasheqv]
+ [else 'make-immutable-hash])
+ (list
+ ,@(hash-map
+ v
+ (lambda (k v)
+ `(cons (quote ,k)
+ ,(stx->loc-s-expr v))))))]
+ [else `(quote ,v)])))
+ (stx->loc-s-expr v))
+ (define (cvt s uncode-id)
+ (datum->syntax #'here (stx->loc-s-expr/esc s uncode-id) #f))
(if (eq? (syntax-local-context) 'expression)
(syntax-case stx ()
- [(_ expr) #`(typeset-code #,(cvt #'expr))]
+ [(_ #:escape uncode-id expr) #`(typeset-code #,(cvt #'expr #'uncode-id))]
+ [(_ expr) #`(typeset-code #,(cvt #'expr #'uncode))]
+ [(_ #:escape uncode-id expr (... ...))
+ #`(typeset-code #,(cvt #'(code:line expr (... ...)) #'uncode-id))]
[(_ expr (... ...))
- #`(typeset-code #,(cvt #'(code:line expr (... ...))))])
+ #`(typeset-code #,(cvt #'(code:line expr (... ...)) #'uncode))])
(quasisyntax/loc stx
(#%expression #,stx)))))]
[(_ code typeset-code uncode d->s)
diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl
@@ -8,8 +8,11 @@ utilities for evaluating code at document-build time and incorporating
the results in the document, especially to show example uses of
defined procedures and syntax.}
-@defform*[[(interaction datum ...)
- (interaction #:eval eval-expr datum ...)]]{
+@defform/subs[(interaction maybe-eval maybe-escape datum ...)
+ ([maybe-eval code:blank
+ (code:line #:eval eval-expr)]
+ [maybe-escape code:blank
+ (code:line #:escape escape-id)])]{
Like @racket[racketinput], except that the result for each input
@racket[datum] is shown on the next line. The result is determined by
@@ -19,28 +22,10 @@ evaluator produced by @racket[eval-expr], if provided.
The @racket[eval-expr] must produce a sandbox evaluator via
@racket[make-evaluator] or @racket[make-module-evaluator] with the
@racket[sandbox-output] and @racket[sandbox-error-output] parameters
-set to @racket['string]. If @racket[eval] is not provided, an
+set to @racket['string]. If @racket[eval-expr] is not provided, an
evaluator is created using @racket[make-base-eval]. See also
@racket[make-eval-factory].
-As an example,
-@codeblock|{
-#lang scribble/manual
-@(require racket/sandbox
- scribble/eval)
-@(define my-evaluator
- (parameterize ([sandbox-output 'string]
- [sandbox-error-output 'string])
- (make-evaluator 'typed/racket/base)))
-@interaction[#:eval my-evaluator
-
- (: my-sqr (Real -> Real))
- (define (my-sqr x)
- (* x x))
- (my-sqr 42)]
-}|
-uses an evaluator whose language is @racketmodname[typed/racket/base].
-
If the value of @racket[current-print] in the sandbox is changed from
its default value, or if @racket[print-as-expression] in the sandbox
is set to @racket[#f], then each evaluation result is formatted to a
@@ -61,67 +46,77 @@ typeset, while @svar[eval-datum] is evaluated.
If a @racket[datum] has the form
@racket[(@#,indexed-racket[eval:check] #,(svar eval-datum) #,(svar
expect-datum))], then both @svar[eval-datum] and @svar[check-datum]
-are evaluated, and an error is raised if they are not @racket[equal?].}
+are evaluated, and an error is raised if they are not @racket[equal?].
+
+As an example,
+
+@codeblock|{
+#lang scribble/manual
+@(require racket/sandbox
+ scribble/eval)
+@(define my-evaluator
+ (parameterize ([sandbox-output 'string]
+ [sandbox-error-output 'string])
+ (make-evaluator 'typed/racket/base)))
+@interaction[#:eval my-evaluator
+
+ (: my-sqr (Real -> Real))
+ (define (my-sqr x)
+ (* x x))
+ (my-sqr 42)]
+}|
+
+uses an evaluator whose language is @racketmodname[typed/racket/base].}
-@defform*[[(interaction0 datum ...)
- (interaction0 #:eval eval-expr datum ...)]]{
+@defform[(interaction0 maybe-eval maybe-escape datum ...)]{
Like @racket[interaction], but without insetting the code via
@racket[nested].}
-@defform*[[(interaction-eval datum)
- (interaction-eval #:eval eval-expr datum)]]{
+@defform[(interaction-eval maybe-eval maybe-escape datum)]{
Like @racket[interaction], evaluates the @racket[quote]d form of
@racket[datum], but returns the empty string.}
-@defform*[[(interaction-eval-show datum)
- (interaction-eval-show #:eval eval-expr datum)]]{
+@defform[(interaction-eval-show maybe-eval maybe-escape datum)]{
Like @racket[interaction-eval], but produces an element representing
the printed form of the evaluation result.}
-@defform*[[(racketblock+eval datum ...)
- (racketblock+eval #:eval eval-expr datum ...)]]{
+@defform[(racketblock+eval maybe-eval maybe-escape datum ...)]{
Combines @racket[racketblock] and @racket[interaction-eval].}
-@defform*[[(racketblock0+eval datum ...)
- (racketblock0+eval #:eval eval-expr datum ...)]]{
+@defform[(racketblock0+eval maybe-eval maybe-escape datum ...)]{
Combines @racket[racketblock0] and @racket[interaction-eval].}
-@defform*[[(racketmod+eval name datum ...)
- (racketmod+eval #:eval eval-expr name datum ...)]]{
+@defform[(racketmod+eval maybe-eval maybe-escape name datum ...)]{
Combines @racket[racketmod] and @racket[interaction-eval].}
-@defform*[[(def+int defn-datum expr-datum ...)
- (def+int #:eval eval-expr defn-datum expr-datum ...)]]{
+@defform[(def+int maybe-eval maybe-escape defn-datum expr-datum ...)]{
Like @racket[interaction], except the @racket[defn-datum] is
typeset as for @racket[racketblock] (i.e., no prompt) and a line of
space is inserted before the @racket[expr-datum]s.}
-@defform*[[(defs+int (defn-datum ...) expr-datum ...)
- (defs+int #:eval eval-expr (defn-datum ...) expr-datum ...)]]{
+@defform[(defs+int maybe-eval maybe-escape (defn-datum ...) expr-datum ...)]{
Like @racket[def+int], but for multiple leading definitions.}
-@defform*[[(examples datum ...)
- (examples #:eval eval-expr datum ...)]]{
+@defform[(examples maybe-eval maybe-escape datum ...)]{
Like @racket[interaction], but with an ``Examples:'' label prefixed.}
-@defform*[[(defexamples datum ...)
- (defexamples #:eval eval-expr datum ...)]]{
+@defform[(defexamples maybe-eval maybe-escape datum ...)]{
Like @racket[examples], but each definition using @racket[define] or
@racket[define-struct] among the @racket[datum]s is typeset without a
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
@@ -97,7 +97,9 @@ produces the typeset result
}
-@defform[(racketblock datum ...)]{
+@defform/subs[(racketblock maybe-escape datum ...)
+ ([maybe-escape code:blank
+ (code:line #:escape escape-id)])]{
Typesets the @racket[datum] sequence as a table of Racket code inset
inset via @racket[nested] with the style @racket['code-inset]. The
@@ -120,20 +122,25 @@ produces the output
with the @racket[(loop (not x))] indented under @racket[define],
because that's the way it is idented the use of @racket[racketblock].
-Furthermore, @racket[define] is typeset as a keyword (bold and black)
+Furthermore, @racket[define] is typeset as a keyword (in black)
and as a hyperlink to @racket[define]'s definition in the reference
manual, because this document was built using a for-label binding of
@racket[define] (in the source) that matches a definition in the
reference manual. Similarly, @racket[not] is a hyperlink to the its
definition in the reference manual.
-Use @racket[unsyntax] to escape back to an expression that produces an
-@racket[element]. For example,
+Like other forms defined via @racket[define-code],
+@racket[racketblock] expands identifiers that are bound as
+@tech{element transformers}.
-@let[([unsyntax #f])
+An @racket[#:escape] clause specifies an identifier to escape back to
+an expression that produces produces an @racket[element]. But default,
+the escape identifier is @racket[unsyntax]. For example,
+
+@racketblock[
+#:escape nonesuch
(racketblock
- (racketblock
- (+ 1 (unsyntax (elem (racket x) (subscript "2"))))))
+ (+ 1 (unsyntax (elem (racket x) (subscript "2")))))
]
produces
@@ -142,9 +149,8 @@ produces
(+ 1 (unsyntax (elem (racket x) (subscript "2"))))
]
-The @racket[unsyntax] form is regonized via
-@racket[free-identifier=?], so if you want to typeset code that
-includes @racket[unsyntax], you can simply hide the usual binding:
+The @racket[escape-id] that defaults to @racket[unsyntax] is regonized via
+@racket[free-identifier=?], so a binding can hide the escape behavior:
@RACKETBLOCK[
(racketblock
@@ -153,7 +159,7 @@ includes @racket[unsyntax], you can simply hide the usual binding:
(syntax (+ 1 (unsyntax x))))))
]
-Or use @racket[RACKETBLOCK], whose escape form is @racket[UNSYNTAX]
+The @racket[RACKETBLOCK] form's default escape is @racket[UNSYNTAX]
instead of @racket[unsyntax].
A few other escapes are recognized symbolically:
@@ -199,41 +205,43 @@ A few other escapes are recognized symbolically:
See also @racketmodname[scribble/comment-reader].
}
-@defform[(RACKETBLOCK datum ...)]{Like @racket[racketblock], but with
-the expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].}
+@defform[(RACKETBLOCK maybe-escape datum ...)]{Like @racket[racketblock], but with
+the default expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].}
-@defform[(racketblock0 datum ...)]{Like @racket[racketblock], but
+@defform[(racketblock0 maybe-escape datum ...)]{Like @racket[racketblock], but
without insetting the code via @racket[nested].}
-@defform[(RACKETBLOCK0 datum ...)]{Like @racket[RACKETBLOCK], but
+@defform[(RACKETBLOCK0 maybe-escape datum ...)]{Like @racket[RACKETBLOCK], but
without insetting the code via @racket[nested].}
@deftogether[(
-@defform[(racketresultblock datum ...)]
-@defform[(racketresultblock0 datum ...)]
-@defform[(RACKETRESULTBLOCK datum ...)]
-@defform[(RACKETRESULTBLOCK0 datum ...)]
+@defform[(racketresultblock maybe-escape datum ...)]
+@defform[(racketresultblock0 maybe-escape datum ...)]
+@defform[(RACKETRESULTBLOCK maybe-escape datum ...)]
+@defform[(RACKETRESULTBLOCK0 maybe-escape datum ...)]
)]{
Like @racket[racketblock], etc., but colors the typeset text as a
result (i.e., a single color with no hyperlinks) instead of code.}
@deftogether[(
-@defform[(racketinput datum ...)]
-@defform[(RACKETINPUT datum ...)]
+@defform[(racketinput maybe-escape datum ...)]
+@defform[(RACKETINPUT maybe-escape datum ...)]
)]{Like @racket[racketblock] and @racket[RACKETBLOCK], but the
@racket[datum]s are typeset after a prompt representing a REPL.}
@deftogether[(
-@defform[(racketinput0 datum ...)]
-@defform[(RACKETINPUT0 datum ...)]
+@defform[(racketinput0 maybe-escape datum ...)]
+@defform[(RACKETINPUT0 maybe-escape datum ...)]
)]{
Like @racket[racketinput] and @racket[RACKETINPUT], but
without insetting the code via @racket[nested].}
-@defform/subs[(racketmod maybe-file lang datum ...)
+@defform/subs[(racketmod maybe-file maybe-escape lang datum ...)
([maybe-file code:blank
- (code:line #:file filename-expr)])]{
+ (code:line #:file filename-expr)]
+ [maybe-escape code:blank
+ (code:line #:escape escape-id)])]{
Like @racket[racketblock], but the @racket[datum] are typeset inside a
@racketmodfont{#lang}-form module whose language is @racket[lang].
@@ -247,21 +255,21 @@ If @racket[#:file] is provided, then the code block is typeset using
@racket[filebox] with @racket[filename-expr] as the filename
argument.}
-@defform[(racketmod0 maybe-file lang datum ...)]{
+@defform[(racketmod0 maybe-file maybe-escape lang datum ...)]{
Like @racket[racketmod], but
without insetting the code via @racket[nested].}
-@defform[(racket datum ...)]{Like @racket[racketblock], but typeset on
+@defform[(racket maybe-escape datum ...)]{Like @racket[racketblock], but typeset on
a single line and wrapped with its enclosing paragraph, independent of
the formatting of @racket[datum].}
-@defform[(RACKET datum ...)]{Like @racket[racket], but with the
+@defform[(RACKET maybe-escape datum ...)]{Like @racket[racket], but with the
@racket[UNSYNTAX] escape like @racket[racketblock].}
-@defform[(racketresult datum ...)]{Like @racket[racket], but typeset
+@defform[(racketresult maybe-escape datum ...)]{Like @racket[racket], but typeset
as a result (i.e., a single color with no hyperlinks).}
-@defform[(racketid datum ...)]{Like @racket[racket], but typeset
+@defform[(racketid maybe-escape datum ...)]{Like @racket[racket], but typeset
as an unbound identifier (i.e., no coloring or hyperlinks).}
@defform*[((racketmodname datum)
@@ -333,15 +341,15 @@ procedure, but use @racket[var] if that cannot work for some reason.}
in a form definition.}
@deftogether[(
-@defform[(schemeblock datum ...)]
-@defform[(SCHEMEBLOCK datum ...)]
-@defform[(schemeblock0 datum ...)]
-@defform[(SCHEMEBLOCK0 datum ...)]
-@defform[(schemeinput datum ...)]
-@defform[(schememod lang datum ...)]
-@defform[(scheme datum ...)]
-@defform[(SCHEME datum ...)]
-@defform[(schemeresult datum ...)]
+@defform[(schemeblock maybe-escape datum ...)]
+@defform[(SCHEMEBLOCK maybe-escape datum ...)]
+@defform[(schemeblock0 maybe-escape datum ...)]
+@defform[(SCHEMEBLOCK0 maybe-escape datum ...)]
+@defform[(schemeinput maybe-escape datum ...)]
+@defform[(schememod lang maybe-escape datum ...)]
+@defform[(scheme maybe-escape datum ...)]
+@defform[(SCHEME maybe-escape datum ...)]
+@defform[(schemeresult maybe-escape datum ...)]
@defform[(schemeid datum ...)]
@defform*[((schememodname datum)
(schememodname ((unsyntax (racket unsyntax)) expr)))]
diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl
@@ -17,8 +17,8 @@ interface.}
Binds @racket[id] to a form similar to @racket[racket] or
@racket[racketblock] for typesetting code. The form generated by
@racket[define-code] handles source-location information, escapes via
-@racket[unquote], preservation of binding and property information,
-and @tech{element transformers}.
+@racket[unquote] by default, preserves binding and property information,
+and supports @tech{element transformers}.
The supplied @racket[typeset-expr] expression should produce a
procedure that performs the actual typesetting. This expression is
@@ -26,8 +26,11 @@ normally @racket[to-element] or @racket[to-paragraph]. The argument
supplied to @racket[typeset-expr] is normally a syntax object, but
more generally it is the result of applying @racket[d->s-expr].
-The optional @racket[uncode-id] specifies the escape from literal code
-to be recognized by @racket[id]. The default is @racket[unsyntax].
+The optional @racket[uncode-id] specifies the default escape from
+literal code to be recognized by @racket[id], and the default for
+@racket[uncode-id] is @racket[unsyntax]. A use of the @racket[id] form
+can specify an alternate escape via @racket[#:escape], as in
+@racket[racketblock] and @racket[racket].
The optional @racket[d->s-expr] should produce a procedure that
accepts three arguments suitable for @racket[datum->syntax]: a syntax
